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
@@ -53,7 +53,7 @@ The rest of the defaults work as-is. `ROBOT_*`, `LIVEKIT_*`, billing, and Stripe
 cp frontend/.env.template frontend/.env
 ```
 
-The defaults (`VITE_API_URL=http://127.0.0.1:3000`) point at the backend and work out of the box.
+The defaults (`VITE_API_URL=http://127.0.0.1:2892`) point at the backend and work out of the box.
 
 ### 4. Install dependencies and run
 
@@ -62,7 +62,7 @@ cd frontend && bun install && cd ..
 just dev
 ```
 
-This starts the backend (with auto-reload on file changes) at `http://127.0.0.1:3000` and the frontend at `http://127.0.0.1:5173`.
+This starts the backend (with auto-reload on file changes) at `http://127.0.0.1:2892` and the frontend at `http://127.0.0.1:5173`.
 
 ## Project docs
 

backend/.env.template

@@ -1,6 +1,6 @@
 # Server
 HOST=127.0.0.1
-PORT=3000
+PORT=2892
 ALLOW_ORIGINS=                 # Optional comma-separated allowed CORS origins; empty = permissive
 
 # Auth
@@ -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
-STRIPE_SECRET_KEY=            # Stripe API secret key (sk_...)
-STRIPE_WEBHOOK_SECRET=        # Secret for verifying Stripe webhook signatures (whsec_...)
+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/Dockerfile

@@ -26,6 +26,6 @@ WORKDIR /app
 
 COPY --from=build /app/target/release/backend /app/backend
 
-EXPOSE 3000
+EXPOSE 2892
 
 CMD ["/app/backend"]

backend/README.md

@@ -30,27 +30,37 @@ backend/
 
 Environment variables:
 
-| Variable | Description | Default |
-|---|---|---|
-| `DATABASE_URL` | SQLite URL. Relative paths are resolved under `backend/`. | `sqlite://<backend>/data/caravel.db` |
-| `HOST` | API bind host (also used for NIP-98 `u` host check) | `127.0.0.1` |
-| `PORT` | API bind port | `3000` |
-| `ADMINS` | Comma-separated admin pubkeys (hex) | _optional_ |
-| `ALLOW_ORIGINS` | Comma-separated CORS origins. If empty, CORS is permissive. | _optional_ |
-| `ZOOID_API_URL` | Zooid API base URL used by infra worker | _required for infra sync_ |
-| `ZOOID_API_SECRET` | Nostr secret key used for authentication of requests to the zooid API | _required_ |
-| `RELAY_DOMAIN` | Base domain appended to relay subdomains | empty |
-| `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_ |
-| `NWC_URL` | Platform NWC URL used to generate BOLT11 invoices | _required for invoice generation_ |
-| `ROBOT_SECRET` | Robot Nostr secret key | _required_ |
-| `ROBOT_NAME` | Robot display name (kind `0`) | _optional_ |
-| `ROBOT_DESCRIPTION` | Robot description (kind `0`) | _optional_ |
-| `ROBOT_PICTURE` | Robot picture URL (kind `0`) | _optional_ |
-| `ROBOT_OUTBOX_RELAYS` | Comma-separated relays published as kind `10002` | _required_ |
-| `ROBOT_INDEXER_RELAYS` | Comma-separated relays used for recipient relay discovery | _required_ |
-| `ROBOT_MESSAGING_RELAYS` | Comma-separated relays published as kind `10050` | _required_ |
+| Variable                 | Description                                                             | Default                              |
+| ------------------------ | ----------------------------------------------------------------------- | ------------------------------------ |
+| `DATABASE_URL`           | SQLite URL. Relative paths are resolved under `backend/`.               | `sqlite://<backend>/data/caravel.db` |
+| `HOST`                   | API bind host (also used for NIP-98 `u` host check)                     | `127.0.0.1`                          |
+| `PORT`                   | API bind port                                                           | `2892`                               |
+| `ADMINS`                 | Comma-separated admin pubkeys (hex)                                     | _optional_                           |
+| `ALLOW_ORIGINS`          | Comma-separated CORS origins. If empty, CORS is permissive.             | _optional_                           |
+| `ZOOID_API_URL`          | Zooid API base URL used by infra worker                                 | _required for infra sync_            |
+| `ZOOID_API_SECRET`       | Nostr secret key used for authentication of requests to the zooid API   | _required_                           |
+| `RELAY_DOMAIN`           | Base domain appended to relay subdomains                                | empty                                |
+| `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_                           |
+| `ROBOT_PICTURE`          | Robot picture URL (kind `0`)                                            | _optional_                           |
+| `ROBOT_OUTBOX_RELAYS`    | Comma-separated relays published as kind `10002`                        | _required_                           |
+| `ROBOT_INDEXER_RELAYS`   | Comma-separated relays used for recipient relay discovery               | _required_                           |
+| `ROBOT_MESSAGING_RELAYS` | Comma-separated relays published as kind `10050`                        | _required_                           |
 
 Relay list env vars are comma-separated and trimmed. If a relay has no `ws://` or `wss://` scheme, `wss://` is prepended.
 
@@ -60,16 +70,39 @@ See [spec](spec) for more details
 
 ## API Routes
 
-All routes are NIP-98 protected.
+Most API routes are NIP-98 protected.
 
-- `GET /identity` — get auth identity (`pubkey`, `is_admin`)
+Public exceptions:
+
+- `GET /plans`
+- `GET /plans/:id`
+- `POST /stripe/webhook` (validated with Stripe signatures)
+
+- `GET /identity` — get auth identity (`pubkey`, `is_admin`); side-effect-free
 - `GET /tenants` — list tenants (admin)
-- `POST /tenants` — create current auth pubkey as tenant
+- `POST /tenants` — idempotently ensure a tenant row exists for the current auth pubkey (creates Stripe customer + tenant on first call, returns existing tenant otherwise)
 - `GET /tenants/:pubkey` — get tenant (admin or same tenant)
-- `PUT /tenants/:pubkey/billing` — update tenant `nwc_url` (admin or same tenant)
-- `GET /relays` — list relays (`?tenant=<pubkey>` allowed for admin only)
+- `PUT /tenants/:pubkey` — update tenant `nwc_url` (admin or same tenant)
+- `GET /tenants/:pubkey/relays` — list tenant relays (admin or same tenant)
+- `GET /relays` — list relays (admin)
 - `POST /relays` — create relay (admin or relay tenant)
 - `GET /relays/:id` — get relay (admin or relay tenant)
+- `GET /relays/:id/members` — list relay members from zooid (admin or relay tenant)
 - `PUT /relays/:id` — update relay (admin or relay tenant)
+- `GET /relays/:id/activity` — list relay activity (admin or relay tenant)
 - `POST /relays/:id/deactivate` — deactivate relay (admin or relay tenant)
-- `GET /invoices` — list invoices (`?tenant=<pubkey>` allowed for admin only)
+- `POST /relays/:id/reactivate` — reactivate relay (admin or relay tenant)
+- `GET /tenants/:pubkey/invoices` — list tenant invoices (admin or same tenant)
+- `GET /invoices/:id` — get invoice (admin or same tenant)
+- `GET /invoices/:id/bolt11` — get invoice bolt11 (admin or same tenant)
+- `GET /tenants/:pubkey/stripe/session` — create Stripe customer portal session (admin or same tenant)
+
+## API Auth Model
+
+Caravel intentionally uses a session-style variant of NIP-98 for client-to-backend API auth.
+
+- Frontend signs one kind `27235` event with `u = VITE_API_URL` and caches that header for about 10 minutes.
+- Backend verifies event kind, signature, and that `u` contains configured `HOST`.
+- Backend intentionally does not bind auth to exact request URL/method/query, and does not enforce payload hash, timestamp freshness window, or replay cache.
+- Goal: reduce repeated wallet signing prompts and avoid cookie-based sessions.
+- Tradeoff: this is weaker request-intent binding than strict NIP-98 semantics.

backend/migrations/0002_hot_path_indexes.sql

@@ -0,0 +1,11 @@
+CREATE INDEX IF NOT EXISTS idx_tenant_stripe_customer_id
+ON tenant (stripe_customer_id);
+
+CREATE INDEX IF NOT EXISTS idx_relay_tenant_id
+ON relay (tenant, id);
+
+CREATE INDEX IF NOT EXISTS idx_relay_tenant_status_plan
+ON relay (tenant, status, plan);
+
+CREATE INDEX IF NOT EXISTS idx_activity_resource_type_resource_id_created_at_id
+ON activity (resource_type, resource_id, created_at DESC, id DESC);

backend/migrations/0003_invoice_nwc_payment_guard.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS invoice_nwc_payment (
+  invoice_id TEXT PRIMARY KEY,
+  tenant_pubkey TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('pending', 'paid')),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (tenant_pubkey) REFERENCES tenant(pubkey)
+);
+
+CREATE INDEX IF NOT EXISTS idx_invoice_nwc_payment_tenant_pubkey
+ON invoice_nwc_payment (tenant_pubkey);

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

@@ -9,6 +9,7 @@ Members:
 - `query: Query`
 - `command: Command`
 - `billing: Billing`
+- `infra: Infra`
 
 Notes:
 
@@ -46,9 +47,8 @@ Notes:
 
 - Serves `GET /identity`
 - Authorizes anyone, but must be authorized
-- If a tenant for the identity doesn't exist:
-  - Call the Stripe API to create a new customer
-  - Create a new tenant using `command.create_tenant` with payload and `stripe_customer_id`. No subscription is created yet — that happens when the first relay is added.
+- Side-effect-free: returns `{ pubkey, is_admin }` only
+- Clients must call `POST /tenants` before any tenant-scoped write
 - Return `data` is an `Identity` struct
 
 --- Tenant routes
@@ -57,20 +57,33 @@ 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`
+
+- Serves `POST /tenants`
+- Authorizes anyone, but must be authorized
+- No request body; target pubkey is derived from NIP-98 auth
+- Idempotent: if a tenant already exists for the auth pubkey, return it without calling Stripe or writing to the DB
+- Otherwise, call the Stripe API to create a new customer and create a new tenant using `command.create_tenant` with the resulting `stripe_customer_id`. No subscription is created yet — that happens when the first relay is added.
+- 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 `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`
 
@@ -92,6 +105,14 @@ Notes:
 - Authorizes admin or relay owner
 - Return `data` is a single relay struct from `query.get_relay`
 
+## `async fn list_relay_members(...) -> Response`
+
+- Serves `GET /relays/:id/members`
+- Authorizes admin or relay owner
+- For unsynced relays, returns an empty member list without calling zooid
+- For synced relays, proxies the member list from zooid via `infra`
+- Return `data` is `{ members }`
+
 ## `async fn create_relay(...) -> Response`
 
 - Serves `POST /relays`
@@ -106,6 +127,7 @@ Notes:
 - Serves `PUT /relays/:id`
 - Authorizes admin or relay owner
 - Validates/prepares the relay data to be saved using `prepare_relay`
+- If the requested plan changes to a plan with a finite member limit and the current member count exceeds that limit, return a `422` with `code=member-limit-exceeded`
 - Updates the given relay using `command.update_relay`
 - If relay is a duplicate by subdomain, return a `422` with `code=subdomain-exists`
 - Return `data` is a single relay struct.
@@ -121,7 +143,7 @@ Notes:
 
 - Serves `POST /relays/:id/deactivate`
 - Authorizes admin or relay owner
-- If relay is already inactive, return a `400` with `code=relay-is-inactive`
+- If relay status is `inactive` or `delinquent`, return a `400` with `code=relay-is-inactive`
 - Call `command.deactivate_relay`
 - Return `data` is empty
 
@@ -178,15 +200,18 @@ Notes:
 - Reads raw request body and `Stripe-Signature` header
 - Calls `billing.handle_webhook(payload, signature)`
 - Returns `200` on success, `400` on signature verification failure
+- Startup requires non-empty `STRIPE_WEBHOOK_SECRET`
 
 --- Utilities
 
 ## `extract_auth_pubkey(&self, headers: &HeaderMap) -> Result<String>`
 
 - Parses `Authorization` header
-- Validates event kind and signature using `nostr_sdk`
-- Validates event `u` against `HOST` (not the request path. Non-standard, but correct)
-- Does not validate `method` tag
+- Validates event kind (`27235`) and signature using `nostr_sdk`
+- Validates event `u` contains configured `HOST`
+- Intentionally does **not** enforce exact request URL/method/query matching
+- Intentionally does **not** validate `payload` tag/hash, `created_at` freshness window, or replay nonce/cache
+- This is a deliberate session-style tradeoff to reduce repeated signer prompts in the client
 - Returns pubkey if header all checks pass
 
 Refer to https://github.com/nostr-protocol/nips/blob/master/98.md for details. Use `nostr_sdk` functionality where possible.
@@ -202,7 +227,8 @@ Refer to https://github.com/nostr-protocol/nips/blob/master/98.md for details. U
 ## `prepare_relay(&self, relay: Relay) -> anyhow::Result<Relay>`
 
 - Validate `subdomain`
-- If `plan` is free and `blossom` is enabled, return `premium-feature`
-- If `plan` is free and `livekit` is enabled, return `premium-feature`
+- Validate that `plan` matches a known plan id from `Query::list_plans`
+- If selected `plan` does not include `blossom` and `blossom` is enabled, return `premium-feature`
+- If selected `plan` does not include `livekit` and `livekit` is enabled, return `premium-feature`
 - Populate `schema` if not already set
 - Populate missing fields using reasonable defaults

backend/spec/billing.md

@@ -2,77 +2,120 @@
 
 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_webhook_secret: String` - secret for verifying Stripe webhook signatures, from `STRIPE_WEBHOOK_SECRET`
+- `stripe: Stripe` - thin wrapper around the Stripe REST API (see `spec/stripe.md`), built from `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET`
+- `bitcoin: Bitcoin` - the Bitcoin-facing config: system NWC wallet (`NWC_URL`) plus the BTC price-feed HTTP client (see `spec/bitcoin.md`)
 - `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` or `STRIPE_WEBHOOK_SECRET` is missing/empty (`NWC_URL` is optional)
 
 ## `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.
 
-- Fetch the relay and tenant associated with the `activity`
-- **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 check cleanup (below). Return early.
-- **If relay is `inactive`**: 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.
-- **If relay is `active` and on a paid plan**:
-  - **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.
-  - **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`.
-- **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`.
+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 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.
+- **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.
+- **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.
+- **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`.
+- **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.
+- **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**: 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.
 
 ## `pub fn handle_webhook(&self, payload: &str, signature: &str) -> Result<()>`
 
-- Verify the webhook signature using `self.stripe_webhook_secret`
-- Parse the event and dispatch by type:
+- Verify and parse the event via `self.stripe.construct_event(payload, signature)` (checks the `Stripe-Signature` HMAC and timestamp tolerance — see `spec/stripe.md`)
+- Dispatch by type:
   - `invoice.created` -> `self.handle_invoice_created`
   - `invoice.paid` -> `self.handle_invoice_paid`
   - `invoice.payment_failed` -> `self.handle_invoice_payment_failed`
   - `invoice.overdue` -> `self.handle_invoice_overdue`
   - `customer.subscription.updated` -> `self.handle_subscription_updated`
   - `customer.subscription.deleted` -> `self.handle_subscription_deleted`
+  - `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
-- Returns the `data` array from the Stripe response
+- Delegates to `stripe.list_invoices` — returns the `data` array of the customer's invoices
 
-## `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
-- Returns the full Stripe invoice object
+- Delegates to `stripe.create_portal_session` — returns the Customer Portal session URL
 
-## `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>`
+## `pub async fn pay_outstanding_nwc_invoices(&self, tenant: &Tenant) -> Result<()>`
 
-- Creates a Stripe Customer Portal session for the given customer
-- Returns the portal session URL
+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`.
+- For each invoice with `status == "open"` and `amount_due > 0`:
+  - Attempt NWC payment via `nwc_pay_invoice`.
+  - 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 (`stripe.has_payment_method`), return early.
+- 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.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. Payment priority:
+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`:
-   - Create a bolt11 Lightning invoice for the invoice amount using `self.nwc_url` (the receiving/system wallet)
-   - Pay the bolt11 invoice using the tenant's `nwc_url` (the spending/tenant wallet)
-   - 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 payment fails: set `nwc_error` on tenant via `command.set_tenant_nwc_error`. Fall through to next option.
-2. **Card on file**: If the tenant has a payment method on the Stripe customer, do nothing — Stripe will charge automatically.
+1. **NWC auto-pay**: If the tenant has a `nwc_url`, run `nwc_pay_invoice` (decrypting the tenant's stored `nwc_url` first):
+   - 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.
+   - 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 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 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.
 
 Skip invoices with `amount_due` of 0.
@@ -82,7 +125,7 @@ Skip invoices with `amount_due` of 0.
 - Look up tenant by `stripe_customer_id`
 - If tenant has `past_due_at` set:
   - Clear `past_due_at` via `command.clear_tenant_past_due`
-  - Find all `inactive` relays for the tenant that were deactivated due to non-payment (i.e. relays on paid plans that are inactive)
+  - Find all `delinquent` relays on paid plans for the tenant (relays marked delinquent by the billing system due to non-payment)
   - Reactivate each one via `command.activate_relay`
 
 ## `fn handle_invoice_payment_failed(&self, invoice: &Invoice)`
@@ -95,7 +138,7 @@ Skip invoices with `amount_due` of 0.
 ## `fn handle_invoice_overdue(&self, invoice: &Invoice)`
 
 - Look up tenant by `stripe_customer_id`
-- Deactivate all active relays on paid plans via `command.deactivate_relay`
+- Mark all active relays on paid plans as delinquent via `command.mark_relay_delinquent` (sets status to `delinquent`, distinct from user-initiated `deactivate_relay`)
 - Send a DM via `robot.send_dm` notifying the tenant that their paid relays have been deactivated due to non-payment
 
 ## `fn handle_subscription_updated(&self, subscription: &Subscription)`
@@ -103,10 +146,14 @@ Skip invoices with `amount_due` of 0.
 - Look up tenant by `stripe_customer_id`
 - If subscription status is `canceled` or `unpaid`:
   - Clear `stripe_subscription_id` via `command.clear_tenant_subscription`
-  - Deactivate all active paid relays for the tenant via `command.deactivate_relay`
+  - Mark all active paid relays as delinquent via `command.mark_relay_delinquent`
 
 ## `fn handle_subscription_deleted(&self, subscription: &Subscription)`
 
 - Look up tenant by `stripe_customer_id`
 - Clear `stripe_subscription_id` via `command.clear_tenant_subscription`
 
+## `fn handle_payment_method_attached(&self, stripe_customer_id: &str)`
+
+- Look up tenant by `stripe_customer_id`
+- Call `pay_outstanding_card_invoices` so invoices that were due before card setup are retried immediately

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/command.md

@@ -44,6 +44,14 @@ Notes:
 
 - Sets relay status to `inactive`
 - Logs activity as `(deactivate_relay, relay_id)`
+- Used for user/admin-initiated deactivation only
+
+## `pub fn mark_relay_delinquent(&self, relay: &Relay) -> Result<()>`
+
+- Sets relay status to `delinquent`
+- Logs activity as `(deactivate_relay, relay_id)`
+- Used exclusively by the billing system when a relay's subscription becomes past due
+- `delinquent` relays are automatically reactivated via `activate_relay` when payment is received
 
 ## `pub fn activate_relay(&self, relay: &Relay) -> Result<()>`
 

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`
 
@@ -15,12 +16,15 @@ Members:
 ## `pub async fn start(self)`
 
 - Subscribes to `command.notify`
+- On startup, schedules delayed sync retries for relays whose `sync_error` is non-empty.
 - Loops on `rx.recv()`, calling `handle_activity` for each received `Activity`.
 
 ## `async fn handle_activity(&self, activity: &Activity)`
 
-- For `create_relay`, `update_relay`, `activate_relay`, or `deactivate_relay` activity, calls `sync_and_report`.
-- All other activity types are ignored (e.g. `fail_relay_sync`, `complete_relay_sync`).
+- For `create_relay`, `update_relay`, `activate_relay`, or `deactivate_relay` activity, calls `sync_and_report` immediately.
+- For `fail_relay_sync`, schedules a delayed retry using exponential backoff based on consecutive failures for the relay.
+- Retry scheduling stops after the configured max attempts to avoid infinite retry loops.
+- Other activity types are ignored (e.g. `complete_relay_sync`).
 
 ## `async fn sync_and_report(&self, relay: &Relay, is_new: bool)`
 
@@ -30,5 +34,7 @@ Members:
 ## `async fn sync_relay(&self, relay: &Relay, is_new: bool)`
 
 - If `is_new`, sends `POST /relay/:id` to create the relay in zooid.
-- Otherwise, sends `PUT /relay/:id` to update it.
-- Passes full relay configuration in the body including host, schema, secret, inactive flag, info, policy, groups, management, blossom, livekit, push, and roles.
+- 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,13 +63,13 @@ 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.
-- `status` - `active|inactive`. Only `active` relays count toward billing.
+- `status` - one of `active|inactive|delinquent`. Only `active` relays count toward billing. `delinquent` is set by the billing system when a relay's subscription becomes past due; `inactive` is set when a user or admin manually deactivates a relay.
 - `synced` - whether the relay has been successfully synced to zooid at least once.
 - `sync_error` - a string indicating any errors encountered when synchronizing.
 - `info_name` - the relay's name
@@ -85,9 +85,8 @@ A relay is a nostr relay owned by a `tenant` and hosted by the attached zooid in
 
 Some attributes persisted to zooid via API have special handling:
 
-- The relay's `secret` is generated once and persisted to the zooid configuration but isn't stored in the database.
+- The relay's `secret` is generated once on relay creation, persisted to the zooid configuration, and isn't stored in the database. Relay updates do not resend `secret`.
 - The relay's `host` is calculated based on `subdomain` + `RELAY_DOMAIN`
 - The value of `inactive` is calculated based on `status`
 - The relay's `livekit_*` configuration is inferred based on environment variables and `livekit_enabled`.
 - The relay's `roles` are hard-coded for now.
-

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

@@ -1,9 +1,9 @@
 use std::sync::Arc;
 
-use anyhow::anyhow;
+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},
@@ -14,10 +14,12 @@ use serde::{Deserialize, Serialize};
 
 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)]
@@ -27,6 +29,7 @@ pub struct Api {
     query: Query,
     command: Command,
     billing: Billing,
+    infra: Infra,
 }
 
 async fn stripe_webhook(
@@ -72,6 +75,11 @@ enum ApiError {
     Unauthorized(anyhow::Error),
     Forbidden(&'static str),
     NotFound(&'static str),
+    Client {
+        status: StatusCode,
+        code: &'static str,
+        message: &'static str,
+    },
     Internal(String),
 }
 
@@ -81,13 +89,38 @@ impl IntoResponse for ApiError {
             Self::Unauthorized(e) => err(StatusCode::UNAUTHORIZED, "unauthorized", &e.to_string()),
             Self::Forbidden(message) => err(StatusCode::FORBIDDEN, "forbidden", message),
             Self::NotFound(message) => err(StatusCode::NOT_FOUND, "not-found", message),
+            Self::Client {
+                status,
+                code,
+                message,
+            } => err(status, code, message),
             Self::Internal(message) => err(StatusCode::INTERNAL_SERVER_ERROR, "internal", &message),
         }
     }
 }
 
+fn map_invoice_lookup_error(error: InvoiceLookupError) -> ApiError {
+    match error {
+        InvoiceLookupError::StripeClient { status } => {
+            let status = StatusCode::from_u16(status.as_u16()).unwrap_or(StatusCode::BAD_REQUEST);
+            match status {
+                StatusCode::NOT_FOUND => ApiError::NotFound("invoice not found"),
+                StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => {
+                    ApiError::Forbidden("invoice access denied")
+                }
+                _ => ApiError::Client {
+                    status,
+                    code: "invoice-request-rejected",
+                    message: "invoice request rejected",
+                },
+            }
+        }
+        InvoiceLookupError::Internal(error) => ApiError::Internal(error.to_string()),
+    }
+}
+
 impl Api {
-    pub fn new(query: Query, command: Command, billing: Billing) -> Self {
+    pub fn new(query: Query, command: Command, billing: Billing, infra: Infra) -> Self {
         let host = std::env::var("HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
         let admins = std::env::var("ADMINS")
             .unwrap_or_default()
@@ -101,6 +134,7 @@ impl Api {
             query,
             command,
             billing,
+            infra,
         }
     }
 
@@ -109,15 +143,16 @@ impl Api {
             api: Arc::new(self),
         };
 
-        Router::new()
+        let router = Router::new()
             .route("/identity", get(get_identity))
             .route("/plans", get(list_plans))
             .route("/plans/:id", get(get_plan))
-            .route("/tenants", get(list_tenants))
+            .route("/tenants", get(list_tenants).post(create_tenant))
             .route("/tenants/:pubkey", get(get_tenant).put(update_tenant))
             .route("/tenants/:pubkey/relays", get(list_tenant_relays))
             .route("/relays", get(list_relays).post(create_relay))
             .route("/relays/:id", get(get_relay).put(update_relay))
+            .route("/relays/:id/members", get(list_relay_members))
             .route("/relays/:id/activity", get(list_relay_activity))
             .route("/relays/:id/deactivate", post(deactivate_relay))
             .route("/relays/:id/reactivate", post(reactivate_relay))
@@ -128,8 +163,9 @@ impl Api {
                 "/tenants/:pubkey/stripe/session",
                 get(create_stripe_session),
             )
-            .route("/stripe/webhook", post(stripe_webhook))
-            .with_state(state)
+            .route("/stripe/webhook", post(stripe_webhook));
+
+        router.with_state(state)
     }
 
     fn extract_auth_pubkey(&self, headers: &HeaderMap) -> std::result::Result<String, ApiError> {
@@ -179,6 +215,9 @@ impl Api {
             return Err(ApiError::Unauthorized(anyhow!("missing u tag")));
         };
 
+        // Intentional session-style variant of NIP-98 for Caravel API auth.
+        // We validate signer identity plus host affinity, and do not bind to exact
+        // request URL/method or maintain replay state here.
         if !self.host.is_empty() && !got_u.contains(&self.host) {
             return Err(ApiError::Unauthorized(anyhow!(
                 "authorization host mismatch"
@@ -217,25 +256,26 @@ impl Api {
         }
     }
 
-    fn prepare_relay(&self, mut relay: Relay) -> anyhow::Result<Relay> {
-        if !relay
-            .subdomain
-            .chars()
-            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
-        {
-            return Err(anyhow!("invalid-subdomain"));
+    async fn fetch_relay_members(&self, relay: &Relay) -> Result<Vec<String>> {
+        if relay.synced == 0 {
+            return Ok(Vec::new());
         }
 
-        if relay.plan == "free" && relay.blossom_enabled == 1 {
-            return Err(anyhow!("premium-feature"));
+        self.infra.list_relay_members(&relay.id).await
+    }
+
+    fn prepare_relay(&self, mut relay: Relay) -> std::result::Result<Relay, RelayValidationError> {
+        validate_subdomain_label(&relay.subdomain)?;
+
+        let plan = Query::get_plan(&relay.plan).ok_or(RelayValidationError::InvalidPlan)?;
+
+        if !plan.blossom && relay.blossom_enabled == 1 {
+            return Err(RelayValidationError::PremiumFeature);
         }
-        if relay.plan == "free" && relay.livekit_enabled == 1 {
-            return Err(anyhow!("premium-feature"));
+        if !plan.livekit && relay.livekit_enabled == 1 {
+            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();
         }
@@ -243,20 +283,106 @@ impl Api {
         relay.policy_strip_signatures = parse_bool_default(relay.policy_strip_signatures, 0);
         relay.groups_enabled = parse_bool_default(relay.groups_enabled, 1);
         relay.management_enabled = parse_bool_default(relay.management_enabled, 1);
-        relay.blossom_enabled = parse_bool_default(
-            relay.blossom_enabled,
-            if relay.plan == "free" { 0 } else { 1 },
-        );
-        relay.livekit_enabled = parse_bool_default(
-            relay.livekit_enabled,
-            if relay.plan == "free" { 0 } else { 1 },
-        );
+        relay.blossom_enabled =
+            parse_bool_default(relay.blossom_enabled, if plan.blossom { 1 } else { 0 });
+        relay.livekit_enabled =
+            parse_bool_default(relay.livekit_enabled, if plan.livekit { 1 } else { 0 });
         relay.push_enabled = parse_bool_default(relay.push_enabled, 1);
 
         Ok(relay)
     }
 }
 
+const SUBDOMAIN_LABEL_MAX_LEN: usize = 63;
+const RESERVED_SUBDOMAIN_LABELS: [&str; 2] = ["api", "admin"];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SubdomainValidationError {
+    Empty,
+    TooLong,
+    Reserved,
+    EdgeHyphen,
+    InvalidCharacters,
+}
+
+impl SubdomainValidationError {
+    fn code(self) -> &'static str {
+        match self {
+            Self::Empty => "subdomain-empty",
+            Self::TooLong => "subdomain-too-long",
+            Self::Reserved => "subdomain-reserved",
+            Self::EdgeHyphen => "subdomain-invalid-hyphen",
+            Self::InvalidCharacters => "subdomain-invalid-characters",
+        }
+    }
+
+    fn message(self) -> &'static str {
+        match self {
+            Self::Empty => "subdomain is required",
+            Self::TooLong => "subdomain must be 63 characters or fewer",
+            Self::Reserved => "subdomain is reserved",
+            Self::EdgeHyphen => "subdomain cannot start or end with a hyphen",
+            Self::InvalidCharacters => {
+                "subdomain may only contain lowercase letters, numbers, and hyphens"
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum RelayValidationError {
+    InvalidPlan,
+    PremiumFeature,
+    Subdomain(SubdomainValidationError),
+}
+
+impl RelayValidationError {
+    fn code(self) -> &'static str {
+        match self {
+            Self::InvalidPlan => "invalid-plan",
+            Self::PremiumFeature => "premium-feature",
+            Self::Subdomain(reason) => reason.code(),
+        }
+    }
+
+    fn message(self) -> &'static str {
+        match self {
+            Self::InvalidPlan => "plan not found",
+            Self::PremiumFeature => "feature requires a paid plan",
+            Self::Subdomain(reason) => reason.message(),
+        }
+    }
+}
+
+impl From<SubdomainValidationError> for RelayValidationError {
+    fn from(value: SubdomainValidationError) -> Self {
+        Self::Subdomain(value)
+    }
+}
+
+fn validate_subdomain_label(subdomain: &str) -> std::result::Result<(), SubdomainValidationError> {
+    if subdomain.is_empty() {
+        return Err(SubdomainValidationError::Empty);
+    }
+    if subdomain.len() > SUBDOMAIN_LABEL_MAX_LEN {
+        return Err(SubdomainValidationError::TooLong);
+    }
+    if subdomain.starts_with('-') || subdomain.ends_with('-') {
+        return Err(SubdomainValidationError::EdgeHyphen);
+    }
+    if RESERVED_SUBDOMAIN_LABELS.contains(&subdomain) {
+        return Err(SubdomainValidationError::Reserved);
+    }
+    if !subdomain
+        .chars()
+        .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
+    {
+        return Err(SubdomainValidationError::InvalidCharacters);
+    }
+
+    Ok(())
+}
+
 fn ok<T: Serialize>(status: StatusCode, data: T) -> Response {
     (status, Json(OkResponse { data, code: "ok" })).into_response()
 }
@@ -284,6 +410,14 @@ fn parse_bool_default(value: i64, default: i64) -> i64 {
     }
 }
 
+fn relay_validation_error_response(error: RelayValidationError) -> Response {
+    err(
+        StatusCode::UNPROCESSABLE_ENTITY,
+        error.code(),
+        error.message(),
+    )
+}
+
 fn map_unique_error(err: &anyhow::Error) -> Option<&'static str> {
     let sqlx_err = err.downcast_ref::<sqlx::Error>()?;
     let sqlx::Error::Database(db_err) = sqlx_err else {
@@ -309,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,
@@ -350,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",
@@ -369,10 +534,17 @@ async fn get_identity(
 ) -> std::result::Result<Response, ApiError> {
     let pubkey = state.api.extract_auth_pubkey(&headers)?;
     let is_admin = state.api.admins.iter().any(|a| a == &pubkey);
+    Ok(ok(StatusCode::OK, IdentityResponse { pubkey, is_admin }))
+}
+
+async fn create_tenant(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+) -> std::result::Result<Response, ApiError> {
+    let pubkey = state.api.extract_auth_pubkey(&headers)?;
 
-    // Ensure tenant exists.
     match state.api.query.get_tenant(&pubkey).await {
-        Ok(Some(_)) => {}
+        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,
@@ -396,31 +568,39 @@ async fn get_identity(
             };
 
             match state.api.command.create_tenant(&tenant).await {
-                Ok(()) => {}
-                Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {}
-                Err(e) => {
-                    return Ok(err(
-                        StatusCode::INTERNAL_SERVER_ERROR,
-                        "internal",
-                        &e.to_string(),
-                    ));
+                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, TenantResponse::from(t))),
+                        Ok(None) => Ok(err(
+                            StatusCode::INTERNAL_SERVER_ERROR,
+                            "internal",
+                            "tenant row missing after unique-constraint race",
+                        )),
+                        Err(e) => Ok(err(
+                            StatusCode::INTERNAL_SERVER_ERROR,
+                            "internal",
+                            &e.to_string(),
+                        )),
+                    }
                 }
-            };
-        }
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
+                Err(e) => Ok(err(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "internal",
+                    &e.to_string(),
+                )),
+            }
         }
+        Err(e) => Ok(err(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal",
+            &e.to_string(),
+        )),
     }
-
-    Ok(ok(StatusCode::OK, IdentityResponse { pubkey, is_admin }))
 }
 
 async fn get_plan(Path(id): Path<String>) -> Response {
-    match Query::list_plans().into_iter().find(|p| p.id == id) {
+    match Query::get_plan(&id) {
         Some(plan) => ok(StatusCode::OK, plan),
         None => err(StatusCode::NOT_FOUND, "not-found", "plan not found"),
     }
@@ -434,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(
@@ -530,6 +710,40 @@ async fn list_relay_activity(
     }
 }
 
+async fn list_relay_members(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    Path(id): Path<String>,
+) -> std::result::Result<Response, ApiError> {
+    let auth = state.api.extract_auth_pubkey(&headers)?;
+
+    let relay = match state.api.query.get_relay(&id).await {
+        Ok(Some(r)) => r,
+        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
+        Err(e) => {
+            return Ok(err(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal",
+                &e.to_string(),
+            ));
+        }
+    };
+
+    state.api.require_admin_or_tenant(&auth, &relay.tenant)?;
+
+    match state.api.fetch_relay_members(&relay).await {
+        Ok(members) => Ok(ok(
+            StatusCode::OK,
+            serde_json::json!({ "members": members }),
+        )),
+        Err(e) => Ok(err(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "internal",
+            &e.to_string(),
+        )),
+    }
+}
+
 async fn create_relay(
     State(state): State<AppState>,
     headers: HeaderMap,
@@ -538,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,
@@ -562,19 +782,8 @@ async fn create_relay(
 
     relay = match state.api.prepare_relay(relay) {
         Ok(r) => r,
-        Err(e) if e.to_string() == "premium-feature" => {
-            return Ok(err(
-                StatusCode::UNPROCESSABLE_ENTITY,
-                "premium-feature",
-                "feature requires a paid plan",
-            ));
-        }
-        Err(_) => {
-            return Ok(err(
-                StatusCode::UNPROCESSABLE_ENTITY,
-                "invalid-relay",
-                "relay validation failed",
-            ));
+        Err(e) => {
+            return Ok(relay_validation_error_response(e));
         }
     };
 
@@ -620,10 +829,13 @@ async fn update_relay(
 
     state.api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
+    let current_plan = relay.plan.clone();
+    let requested_plan = payload.plan.clone();
+
     if let Some(v) = payload.subdomain {
         relay.subdomain = v;
     }
-    if let Some(v) = payload.plan {
+    if let Some(v) = requested_plan.clone() {
         relay.plan = v;
     }
     if let Some(v) = payload.info_name {
@@ -659,22 +871,43 @@ async fn update_relay(
 
     relay = match state.api.prepare_relay(relay) {
         Ok(r) => r,
-        Err(e) if e.to_string() == "premium-feature" => {
-            return Ok(err(
-                StatusCode::UNPROCESSABLE_ENTITY,
-                "premium-feature",
-                "feature requires a paid plan",
-            ));
-        }
-        Err(_) => {
-            return Ok(err(
-                StatusCode::UNPROCESSABLE_ENTITY,
-                "invalid-relay",
-                "relay validation failed",
-            ));
+        Err(e) => {
+            return Ok(relay_validation_error_response(e));
         }
     };
 
+    let plan_changed = requested_plan
+        .as_deref()
+        .is_some_and(|requested| requested != current_plan);
+
+    if plan_changed {
+        let selected_plan = Query::get_plan(&relay.plan).expect("validated plan must exist");
+        if let Some(limit) = selected_plan.members {
+            let current_members = match state.api.fetch_relay_members(&relay).await {
+                Ok(members) => members.len() as i64,
+                Err(e) => {
+                    return Ok(err(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "internal",
+                        &e.to_string(),
+                    ));
+                }
+            };
+
+            if current_members > limit {
+                let message = format!(
+                    "relay has {current_members} members, which exceeds the {} plan limit of {limit}",
+                    selected_plan.name.to_lowercase()
+                );
+                return Ok(err(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "member-limit-exceeded",
+                    &message,
+                ));
+            }
+        }
+    }
+
     match state.api.command.update_relay(&relay).await {
         Ok(()) => Ok(ok(StatusCode::OK, relay)),
         Err(e) => {
@@ -808,9 +1041,16 @@ async fn get_invoice(
         .billing
         .get_invoice_with_tenant(&id)
         .await
-        .map_err(|e| ApiError::Internal(e.to_string()))?;
+        .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))
 }
 
@@ -825,9 +1065,16 @@ async fn get_invoice_bolt11(
         .billing
         .get_invoice_with_tenant(&id)
         .await
-        .map_err(|e| ApiError::Internal(e.to_string()))?;
+        .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(
@@ -840,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,
@@ -850,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)?;
@@ -862,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 }))),
@@ -884,12 +1142,34 @@ async fn update_tenant(
     state.api.require_admin_or_tenant(&auth, &pubkey)?;
     let mut tenant = state.api.get_tenant_or_404(&pubkey).await?;
 
+    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 {
-        Ok(()) => Ok(ok(StatusCode::OK, tenant)),
+        Ok(()) => {
+            // When NWC is first connected, attempt to pay any outstanding open invoices.
+            if nwc_previously_empty && !tenant.nwc_url.is_empty() {
+                let billing = state.api.billing.clone();
+                let tenant_clone = tenant.clone();
+                tokio::spawn(async move {
+                    if let Err(e) = billing.pay_outstanding_nwc_invoices(&tenant_clone).await {
+                        tracing::error!(
+                            error = %e,
+                            pubkey = %tenant_clone.pubkey,
+                            "pay_outstanding_nwc_invoices failed after NWC setup"
+                        );
+                    }
+                });
+            }
+            Ok(ok(StatusCode::OK, TenantResponse::from(tenant)))
+        }
         Err(e) => Ok(err(
             StatusCode::INTERNAL_SERVER_ERROR,
             "internal",

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

@@ -32,7 +32,7 @@ impl Command {
                     .fetch_one(&mut **tx)
                     .await?
             }
-            _ => anyhow::bail!("unknown resource_type: {}", resource_type),
+            _ => anyhow::bail!("unknown resource_type: {resource_type}"),
         };
 
         let id = uuid::Uuid::new_v4().to_string();
@@ -113,12 +113,12 @@ impl Command {
 
         sqlx::query(
             "INSERT INTO relay (
-                id, tenant, schema, subdomain, plan, status, sync_error,
+                id, tenant, schema, subdomain, plan, status, synced, sync_error,
                 info_name, info_icon, info_description,
                 policy_public_join, policy_strip_signatures,
                 groups_enabled, management_enabled, blossom_enabled,
                 livekit_enabled, push_enabled
-            ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            ) VALUES (?, ?, ?, ?, ?, 'active', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
         )
         .bind(&relay.id)
         .bind(&relay.tenant)
@@ -151,7 +151,7 @@ impl Command {
 
         sqlx::query(
             "UPDATE relay
-             SET tenant = ?, schema = ?, subdomain = ?, plan = ?, status = ?, sync_error = ?,
+             SET tenant = ?, schema = ?, subdomain = ?, plan = ?, status = ?, sync_error = ?, synced = 0,
                  info_name = ?, info_icon = ?, info_description = ?,
                  policy_public_join = ?, policy_strip_signatures = ?,
                  groups_enabled = ?, management_enabled = ?, blossom_enabled = ?,
@@ -203,7 +203,7 @@ impl Command {
     ) -> Result<()> {
         let mut tx = self.pool.begin().await?;
 
-        sqlx::query("UPDATE relay SET status = ? WHERE id = ?")
+        sqlx::query("UPDATE relay SET status = ?, synced = 0 WHERE id = ?")
             .bind(status)
             .bind(relay_id)
             .execute(&mut *tx)
@@ -224,7 +224,7 @@ impl Command {
     pub async fn fail_relay_sync(&self, relay: &Relay, sync_error: String) -> Result<()> {
         let mut tx = self.pool.begin().await?;
 
-        sqlx::query("UPDATE relay SET sync_error = ? WHERE id = ?")
+        sqlx::query("UPDATE relay SET synced = 0, sync_error = ? WHERE id = ?")
             .bind(&sync_error)
             .bind(&relay.id)
             .execute(&mut *tx)
@@ -313,6 +313,70 @@ impl Command {
         Ok(())
     }
 
+    pub async fn insert_pending_invoice_nwc_payment(
+        &self,
+        invoice_id: &str,
+        tenant_pubkey: &str,
+    ) -> Result<bool> {
+        let now = chrono::Utc::now().timestamp();
+        let result = sqlx::query(
+            "INSERT INTO invoice_nwc_payment (invoice_id, tenant_pubkey, state, created_at, updated_at)
+             VALUES (?, ?, 'pending', ?, ?)
+             ON CONFLICT(invoice_id) DO NOTHING",
+        )
+        .bind(invoice_id)
+        .bind(tenant_pubkey)
+        .bind(now)
+        .bind(now)
+        .execute(&self.pool)
+        .await?;
+
+        Ok(result.rows_affected() > 0)
+    }
+
+    pub async fn mark_invoice_nwc_payment_paid(&self, invoice_id: &str) -> Result<()> {
+        let now = chrono::Utc::now().timestamp();
+        let result = sqlx::query(
+            "UPDATE invoice_nwc_payment
+             SET state = 'paid', updated_at = ?
+             WHERE invoice_id = ?",
+        )
+        .bind(now)
+        .bind(invoice_id)
+        .execute(&self.pool)
+        .await?;
+
+        if result.rows_affected() == 0 {
+            anyhow::bail!("invoice_nwc_payment row missing for invoice_id: {invoice_id}");
+        }
+
+        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

@@ -1,10 +1,56 @@
 use anyhow::Result;
 use nostr_sdk::prelude::*;
+use std::time::Duration;
 
 use crate::command::Command;
-use crate::models::{Activity, RELAY_STATUS_DELINQUENT, RELAY_STATUS_INACTIVE};
+use crate::models::{Activity, RELAY_STATUS_DELINQUENT, RELAY_STATUS_INACTIVE, Relay};
 use crate::query::Query;
 
+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,
@@ -13,33 +59,48 @@ pub struct Infra {
     livekit_api_key: String,
     livekit_api_secret: String,
     api_secret: String,
+    blossom_s3: Option<BlossomS3Sync>,
     query: Query,
     command: Command,
 }
 
 impl Infra {
-    pub fn new(query: Query, command: Command) -> Self {
+    pub fn new(query: Query, command: Command) -> Result<Self> {
         let api_url = std::env::var("ZOOID_API_URL").unwrap_or_default();
         let relay_domain = std::env::var("RELAY_DOMAIN").unwrap_or_default();
         let livekit_url = std::env::var("LIVEKIT_URL").unwrap_or_default();
         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();
-        Self {
+        let blossom_s3 = BlossomS3Sync::from_env();
+
+        if api_url.trim().is_empty() {
+            anyhow::bail!("missing ZOOID_API_URL");
+        }
+        if api_secret.trim().is_empty() {
+            anyhow::bail!("missing ZOOID_API_SECRET");
+        }
+
+        Ok(Self {
             api_url,
             relay_domain,
             livekit_url,
             livekit_api_key,
             livekit_api_secret,
             api_secret,
+            blossom_s3,
             query,
             command,
-        }
+        })
     }
 
     pub async fn start(self) {
         let mut rx = self.command.notify.subscribe();
 
+        if let Err(error) = self.reconcile_relay_state("startup").await {
+            tracing::error!(error = %error, "failed to reconcile relay state on startup");
+        }
+
         loop {
             match rx.recv().await {
                 Ok(activity) => {
@@ -49,6 +110,10 @@ impl Infra {
                 }
                 Err(tokio::sync::broadcast::error::RecvError::Lagged(n)) => {
                     tracing::warn!(missed = n, "infra lagged");
+
+                    if let Err(error) = self.reconcile_relay_state("lagged").await {
+                        tracing::error!(error = %error, "failed to reconcile relay state after lag");
+                    }
                 }
                 Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
             }
@@ -58,19 +123,108 @@ impl Infra {
     async fn handle_activity(&self, activity: &Activity) -> Result<()> {
         let needs_sync = should_sync_relay_activity(activity.activity_type.as_str());
 
-        if needs_sync {
-            let Some(relay) = self.query.get_relay(&activity.resource_id).await? else {
-                return Ok(());
-            };
+        if !needs_sync || activity.resource_type != "relay" {
+            return Ok(());
+        }
 
-            let is_new = relay.synced == 0;
-            self.sync_and_report(&relay, is_new).await;
+        if activity.activity_type == "fail_relay_sync" {
+            self.schedule_relay_sync_retry(&activity.resource_id, "activity")
+                .await?;
+            return Ok(());
+        }
+
+        let Some(relay) = self.query.get_relay(&activity.resource_id).await? else {
+            return Ok(());
+        };
+
+        let is_new = self.relay_sync_is_new(&relay).await?;
+        self.sync_and_report(&relay, is_new).await;
+
+        Ok(())
+    }
+
+    async fn reconcile_relay_state(&self, source: &str) -> Result<()> {
+        let relays = self.query.list_relays_pending_sync().await?;
+
+        if relays.is_empty() {
+            return Ok(());
+        }
+
+        tracing::info!(source, relay_count = relays.len(), "reconciling pending relay state");
+
+        for relay in relays {
+            if relay.sync_error.trim().is_empty() {
+                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?;
+            }
         }
 
         Ok(())
     }
 
-    async fn sync_and_report(&self, relay: &crate::models::Relay, is_new: bool) {
+    async fn schedule_relay_sync_retry(&self, relay_id: &str, source: &str) -> Result<()> {
+        let activities = self.query.list_activity_for_relay(relay_id).await?;
+        let consecutive_failures = consecutive_sync_failures(&activities);
+
+        let Some(delay) = relay_sync_retry_delay(consecutive_failures) else {
+            tracing::warn!(
+                relay = relay_id,
+                consecutive_failures,
+                max_attempts = RELAY_SYNC_RETRY_MAX_ATTEMPTS,
+                "relay sync retries exhausted; awaiting manual intervention"
+            );
+            return Ok(());
+        };
+
+        tracing::info!(
+            relay = relay_id,
+            source,
+            consecutive_failures,
+            delay_secs = delay.as_secs(),
+            "scheduled relay sync retry"
+        );
+
+        let relay_id = relay_id.to_string();
+        let infra = self.clone();
+
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+
+            if let Err(e) = infra.retry_relay_sync(&relay_id).await {
+                tracing::error!(relay = %relay_id, error = %e, "relay sync retry task failed");
+            }
+        });
+
+        Ok(())
+    }
+
+    async fn retry_relay_sync(&self, relay_id: &str) -> Result<()> {
+        let Some(relay) = self.query.get_relay(relay_id).await? else {
+            return Ok(());
+        };
+
+        if relay.sync_error.trim().is_empty() {
+            tracing::debug!(relay = %relay.id, "skip relay sync retry; relay has no sync_error");
+            return Ok(());
+        }
+
+        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(()) => {
                 tracing::info!(relay = %relay.id, "relay sync succeeded");
@@ -96,7 +250,29 @@ impl Infra {
         Ok(auth)
     }
 
-    async fn sync_relay(&self, relay: &crate::models::Relay, is_new: bool) -> Result<()> {
+    pub async fn list_relay_members(&self, relay_id: &str) -> Result<Vec<String>> {
+        let client = reqwest::Client::new();
+        let base = self.api_url.trim_end_matches('/');
+        let url = format!("{base}/relay/{relay_id}/members");
+        let auth = self.nip98_auth(&url, HttpMethod::GET).await?;
+
+        let response = client
+            .get(&url)
+            .header("Authorization", auth)
+            .send()
+            .await?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            anyhow::bail!("zooid members returned {status}: {body}");
+        }
+
+        let body = response.text().await?;
+        parse_relay_members_response(&body)
+    }
+
+    async fn sync_relay(&self, relay: &Relay, is_new: bool) -> Result<()> {
         let client = reqwest::Client::new();
         let base = self.api_url.trim_end_matches('/');
 
@@ -106,8 +282,6 @@ impl Infra {
             format!("{}.{}", relay.subdomain, self.relay_domain)
         };
 
-        let secret = Keys::generate().secret_key().to_secret_hex();
-
         let livekit = if relay.livekit_enabled == 1 {
             serde_json::json!({
                 "enabled": true,
@@ -119,65 +293,188 @@ impl Infra {
             serde_json::json!({ "enabled": false })
         };
 
-        let body = serde_json::json!({
-            "host": host,
-            "schema": relay.schema,
-            "secret": secret,
-            "inactive": relay.status == RELAY_STATUS_INACTIVE
-                || relay.status == RELAY_STATUS_DELINQUENT,
-            "info": {
-                "name": relay.info_name,
-                "icon": relay.info_icon,
-                "description": relay.info_description,
-                "pubkey": relay.tenant,
-            },
-            "policy": {
-                "public_join": relay.policy_public_join == 1,
-                "strip_signatures": relay.policy_strip_signatures == 1,
-            },
-            "groups": { "enabled": relay.groups_enabled == 1 },
-            "management": { "enabled": relay.management_enabled == 1 },
-            "blossom": { "enabled": relay.blossom_enabled == 1 },
-            "livekit": livekit,
-            "push": { "enabled": relay.push_enabled == 1 },
-            "roles": {
-                "admin": { "can_manage": true, "can_invite": true },
-                "member": { "can_invite": true },
-            },
-        });
+        let body = relay_sync_body(
+            relay,
+            host,
+            livekit,
+            is_new.then(|| Keys::generate().secret_key().to_secret_hex()),
+            self.blossom_s3.as_ref(),
+        );
 
-        let response = if is_new {
-            let url = format!("{}/relay/{}", base, relay.id);
-            let auth = self.nip98_auth(&url, HttpMethod::POST).await?;
-            client
-                .post(&url)
-                .header("Authorization", auth)
-                .json(&body)
-                .send()
-                .await?
+        let url = format!("{}/relay/{}", base, relay.id);
+        let auth = self
+            .nip98_auth(&url, zooid_sync_http_method(is_new))
+            .await?;
+
+        let request = if is_new {
+            client.post(&url)
         } else {
-            let url = format!("{}/relay/{}", base, relay.id);
-            let auth = self.nip98_auth(&url, HttpMethod::PUT).await?;
-            client
-                .put(&url)
-                .header("Authorization", auth)
-                .json(&body)
-                .send()
-                .await?
+            client.patch(&url)
         };
 
+        let response = request
+            .header("Authorization", auth)
+            .json(&body)
+            .send()
+            .await?;
+
         if !response.status().is_success() {
             let status = response.status();
             let body = response.text().await.unwrap_or_default();
-            anyhow::bail!("zooid sync returned {}: {}", status, body)
+            anyhow::bail!("zooid sync returned {status}: {body}")
         }
         Ok(())
     }
 }
 
+fn zooid_sync_http_method(is_new: bool) -> HttpMethod {
+    if is_new {
+        HttpMethod::POST
+    } else {
+        HttpMethod::PATCH
+    }
+}
+
+fn parse_relay_members_response(body: &str) -> Result<Vec<String>> {
+    let value: serde_json::Value = serde_json::from_str(body)?;
+
+    if let Some(members) = members_from_value(&value) {
+        return Ok(members);
+    }
+    if let Some(members) = value.get("members").and_then(members_from_value) {
+        return Ok(members);
+    }
+    if let Some(members) = value
+        .get("data")
+        .and_then(|data| data.get("members"))
+        .and_then(members_from_value)
+    {
+        return Ok(members);
+    }
+
+    anyhow::bail!("zooid members response missing members array")
+}
+
+fn members_from_value(value: &serde_json::Value) -> Option<Vec<String>> {
+    let values = value.as_array()?;
+    values
+        .iter()
+        .map(|value| value.as_str().map(ToString::to_string))
+        .collect()
+}
+
+fn relay_sync_body(
+    relay: &Relay,
+    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,
+        "inactive": relay.status == RELAY_STATUS_INACTIVE
+            || relay.status == RELAY_STATUS_DELINQUENT,
+        "info": {
+            "name": relay.info_name,
+            "icon": relay.info_icon,
+            "description": relay.info_description,
+            "pubkey": relay.tenant,
+        },
+        "policy": {
+            "public_join": relay.policy_public_join == 1,
+            "strip_signatures": relay.policy_strip_signatures == 1,
+        },
+        "groups": { "enabled": relay.groups_enabled == 1 },
+        "management": { "enabled": relay.management_enabled == 1 },
+        "blossom": blossom,
+        "livekit": livekit,
+        "push": { "enabled": relay.push_enabled == 1 },
+        "roles": {
+            "admin": { "can_manage": true, "can_invite": true },
+            "member": { "can_invite": true },
+        },
+    });
+
+    if let (Some(secret), Some(body_obj)) = (secret, body.as_object_mut()) {
+        body_obj.insert("secret".to_string(), serde_json::Value::String(secret));
+    }
+
+    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,
-        "create_relay" | "update_relay" | "activate_relay" | "deactivate_relay"
+        "create_relay" | "update_relay" | "activate_relay" | "deactivate_relay" | "fail_relay_sync"
     )
 }
+
+fn consecutive_sync_failures(activities: &[Activity]) -> usize {
+    activities
+        .iter()
+        .take_while(|activity| activity.activity_type == "fail_relay_sync")
+        .count()
+}
+
+fn relay_sync_retry_delay(consecutive_failures: usize) -> Option<Duration> {
+    let retry_attempt = consecutive_failures.max(1);
+    if retry_attempt > RELAY_SYNC_RETRY_MAX_ATTEMPTS {
+        return None;
+    }
+
+    let exponent = (retry_attempt - 1).min(31);
+    let multiplier = 1u64 << exponent;
+    let delay_secs = RELAY_SYNC_RETRY_BASE_DELAY_SECS
+        .saturating_mul(multiplier)
+        .min(RELAY_SYNC_RETRY_MAX_DELAY_SECS);
+
+    Some(Duration::from_secs(delay_secs))
+}

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 query;
 mod pool;
+mod query;
 mod robot;
+mod stripe;
 
 use anyhow::Result;
 use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
@@ -33,14 +36,14 @@ async fn main() -> Result<()> {
     let query = Query::new(pool.clone());
     let command = Command::new(pool);
     let billing = Billing::new(query.clone(), command.clone(), robot.clone());
-    let infra = Infra::new(query.clone(), command.clone());
-    let api = Api::new(query, command, billing.clone());
+    let infra = Infra::new(query.clone(), command.clone())?;
+    let api = Api::new(query, command, billing.clone(), infra.clone());
 
     let host = std::env::var("HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
     let port: u16 = std::env::var("PORT")
         .ok()
         .and_then(|v| v.parse().ok())
-        .unwrap_or(3000);
+        .unwrap_or(2892);
     let origins: Vec<String> = std::env::var("ALLOW_ORIGINS")
         .unwrap_or_default()
         .split(',')

backend/src/pool.rs

@@ -21,8 +21,7 @@ pub async fn create_pool() -> Result<SqlitePool> {
         std::fs::create_dir_all(parent)?;
     }
 
-    let connect_options =
-        SqliteConnectOptions::from_str(&database_url)?.create_if_missing(true);
+    let connect_options = SqliteConnectOptions::from_str(&database_url)?.create_if_missing(true);
 
     let pool = SqlitePoolOptions::new()
         .max_connections(5)

backend/src/query.rs

@@ -68,6 +68,16 @@ impl Query {
         ]
     }
 
+    pub fn get_plan(plan_id: &str) -> Option<Plan> {
+        Self::list_plans().into_iter().find(|p| p.id == plan_id)
+    }
+
+    pub fn is_paid_plan(plan_id: &str) -> bool {
+        Self::get_plan(plan_id)
+            .map(|p| p.id != "free")
+            .unwrap_or(false)
+    }
+
     pub async fn list_relays(&self) -> Result<Vec<Relay>> {
         let rows = sqlx::query_as::<_, Relay>(
             "SELECT id, tenant, schema, subdomain, plan, stripe_subscription_item_id,
@@ -84,6 +94,23 @@ impl Query {
         Ok(rows)
     }
 
+    pub async fn list_relays_pending_sync(&self) -> Result<Vec<Relay>> {
+        let rows = sqlx::query_as::<_, Relay>(
+            "SELECT id, tenant, schema, subdomain, plan, stripe_subscription_item_id,
+                     status, sync_error,
+                     info_name, info_icon, info_description,
+                     policy_public_join, policy_strip_signatures,
+                     groups_enabled, management_enabled, blossom_enabled,
+                     livekit_enabled, push_enabled, synced
+              FROM relay
+              WHERE synced = 0 OR TRIM(sync_error) != ''
+              ORDER BY id",
+        )
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows)
+    }
+
     pub async fn list_relays_for_tenant(&self, tenant_id: &str) -> Result<Vec<Relay>> {
         let rows = sqlx::query_as::<_, Relay>(
             "SELECT id, tenant, schema, subdomain, plan, stripe_subscription_item_id,
@@ -134,14 +161,27 @@ impl Query {
         Ok(row)
     }
 
-    pub async fn has_active_paid_relays(&self, tenant_id: &str) -> Result<bool> {
-        let count = sqlx::query_scalar::<_, i64>(
-            "SELECT COUNT(*) FROM relay WHERE tenant = ? AND status = 'active' AND plan != 'free'",
+    pub async fn get_invoice_nwc_payment_state(&self, invoice_id: &str) -> Result<Option<String>> {
+        let state = sqlx::query_scalar::<_, String>(
+            "SELECT state FROM invoice_nwc_payment WHERE invoice_id = ?",
         )
-        .bind(tenant_id)
-        .fetch_one(&self.pool)
+        .bind(invoice_id)
+        .fetch_optional(&self.pool)
         .await?;
-        Ok(count > 0)
+        Ok(state)
+    }
+
+    pub async fn get_invoice_manual_lightning_bolt11(
+        &self,
+        invoice_id: &str,
+    ) -> Result<Option<String>> {
+        let bolt11 = sqlx::query_scalar::<_, String>(
+            "SELECT bolt11 FROM invoice_manual_lightning_payment WHERE invoice_id = ?",
+        )
+        .bind(invoice_id)
+        .fetch_optional(&self.pool)
+        .await?;
+        Ok(bolt11)
     }
 
     pub async fn list_activity_for_relay(&self, relay_id: &str) -> Result<Vec<Activity>> {
@@ -156,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/.env.template

@@ -1,5 +1,5 @@
 # Backend API base URL
-VITE_API_URL=http://127.0.0.1:3000
+VITE_API_URL=http://127.0.0.1:2892
 
 # Platform display name shown in UI
 VITE_PLATFORM_NAME=Caravel

frontend/README.md

@@ -32,7 +32,7 @@ Environment variables (see `.env.template`):
 
 | Variable | Description | Default |
 |---|---|---|
-| `VITE_API_URL` | Backend API base URL | `http://127.0.0.1:3000` |
+| `VITE_API_URL` | Backend API base URL | `http://127.0.0.1:2892` |
 
 ## Running
 
@@ -51,8 +51,11 @@ npm run preview
 
 ## Authentication
 
-- Tenant requests use NIP-98 tokens derived from the logged-in user
-- Admin routes require a pubkey listed in `PLATFORM_ADMIN_PUBKEYS` on the backend
+- Tenant requests use an intentional session-style variant of NIP-98:
+  - The client signs one kind `27235` event with `u = VITE_API_URL`.
+  - The resulting `Authorization` header is cached for about 10 minutes to avoid repeated signer prompts.
+  - The backend validates signer identity + host affinity rather than exact URL/method binding per request.
+- Admin routes require a pubkey listed in `ADMINS` on the backend.
 
 ## Routes
 

frontend/src/assets/chachi-logo.svg

@@ -0,0 +1 @@
+<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="220" height="220" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0 32C0 14.3269 14.3269 0 32 0V0C49.6731 0 64 14.3269 64 32V32C64 49.6731 49.6731 64 32 64H8C3.58172 64 0 60.4183 0 56V32Z" fill="#6D29D9"></path><path fill-rule="evenodd" clip-rule="evenodd" d="M21 22C19.3431 22 18 23.3431 18 25C18 26.1046 17.1046 27 16 27C14.8954 27 14 26.1046 14 25C14 21.134 17.134 18 21 18C24.866 18 28 21.134 28 25C28 26.1046 27.1046 27 26 27C24.8954 27 24 26.1046 24 25C24 23.3431 22.6569 22 21 22ZM43 22C41.3431 22 40 23.3431 40 25C40 26.1046 39.1046 27 38 27C36.8954 27 36 26.1046 36 25C36 21.134 39.134 18 43 18C46.866 18 50 21.134 50 25C50 26.1046 49.1046 27 48 27C46.8954 27 46 26.1046 46 25C46 23.3431 44.6569 22 43 22Z" fill="#FFFFFF"></path><path d="M32 47C38.6985 47 44.2982 42.2956 45.6755 36.0106C45.9829 34.608 44.5 33.5552 43.1016 33.8813C40.0379 34.5957 35.7213 35.1538 32 35.1538C28.2787 35.1538 23.9621 34.5957 20.8984 33.8813C19.5 33.5552 18.0171 34.608 18.3245 36.0106C19.7018 42.2956 25.3015 47 32 47Z" fill="#FFFFFF"></path></svg>

frontend/src/assets/nostord-logo.svg

@@ -0,0 +1,21 @@
+<svg xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" width="66.145837" height="66.145837" viewBox="0 0 66.145837 66.145837" version="1.1" id="svg1" inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)" sodipodi:docname="nostrord.svg">
+  <sodipodi:namedview id="namedview1" pagecolor="#ffffff" bordercolor="#000000" borderopacity="0.25" inkscape:showpageshadow="2" inkscape:pageopacity="0.0" inkscape:pagecheckerboard="0" inkscape:deskcolor="#d1d1d1" inkscape:document-units="mm" inkscape:zoom="2.1971895" inkscape:cx="172.94822" inkscape:cy="184.78151" inkscape:window-width="2048" inkscape:window-height="1083" inkscape:window-x="0" inkscape:window-y="0" inkscape:window-maximized="1" inkscape:current-layer="layer1"/>
+  <defs id="defs1"/>
+  <g inkscape:label="Layer 1" inkscape:groupmode="layer" id="layer1" transform="translate(-80.278336,-100.91589)">
+    <rect x="80.278336" y="100.91589" width="66.145836" height="66.145836" rx="15.434029" fill="#0a0a0a" id="rect1-6-9-7-7-9-8-6" style="stroke-width:1.10243"/>
+    <g id="g32" transform="matrix(0.56473291,0,0,0.56473291,-434.56644,229.88942)">
+      <path d="m 941.12408,-145.50974 c 0,7.28807 10.93211,10.93211 29.15233,10.93211 18.2201,0 29.1523,-3.64404 29.1523,-10.93211 v -32.79632 c 0,-14.57615 -10.9322,-25.50826 -29.1523,-25.50826 -18.22022,0 -29.15233,10.93211 -29.15233,25.50826 z" fill="#fafafa" id="path3-6-2-5-9-7-4-1" style="stroke-width:1.82202"/>
+      <path d="m 948.41215,-171.01799 c 0,-7.28807 10.93211,-10.93211 21.86426,-10.93211 10.9321,0 21.8642,3.64404 21.8642,10.93211 v 7.28807 c 0,7.28807 -10.9321,10.9321 -21.8642,10.9321 -10.93215,0 -21.86426,-3.64403 -21.86426,-10.9321 z" fill="#0a0a0a" id="path4-1-3-6-2-3-5-5" style="stroke-width:1.82202"/>
+      <ellipse cx="959.34424" cy="-167.37396" rx="5.4660549" ry="7.2880735" fill="#fafafa" id="ellipse4-5-7-2-0-6-0-5" style="stroke-width:1.82202"/>
+      <ellipse cx="981.2085" cy="-167.37396" rx="5.4660549" ry="7.2880735" fill="#fafafa" id="ellipse5-5-5-9-2-1-3-4" style="stroke-width:1.82202"/>
+      <g id="g12-2-3-2-6-7" transform="matrix(1.3286857,0,0,1.3286857,15.786725,-131.79559)">
+        <path d="m 740.53601,-40.469391 14,-14 q 3,-2 1,2 l -11,14 q -2,2 -4,1 z" fill="#fafafa" id="path3-9-7-7-9-1-6"/>
+        <path d="m 738.53601,-34.469391 10,-10 q 2,-2 1,1 l -8,11 q -2,2 -3,1 z" fill="#fafafa" id="path4-73-0-5-3-0-5"/>
+      </g>
+      <g id="g12-2-2-9-1-6-6" transform="matrix(-1.3286857,0,0,1.3286857,1924.6621,-131.79559)">
+        <path d="m 740.53601,-40.469391 14,-14 q 3,-2 1,2 l -11,14 q -2,2 -4,1 z" fill="#fafafa" id="path3-9-7-6-2-9-3-9"/>
+        <path d="m 738.53601,-34.469391 10,-10 q 2,-2 1,1 l -8,11 q -2,2 -3,1 z" fill="#fafafa" id="path4-73-0-1-2-4-2-3"/>
+      </g>
+    </g>
+  </g>
+</svg>

frontend/src/components/ConfirmDialog.tsx

@@ -0,0 +1,151 @@
+import { For, Show, createEffect, createSignal } from "solid-js"
+import Modal from "@/components/Modal"
+
+type ConfirmDialogProps = {
+  open: boolean
+  title: string
+  description: string
+  /** Optional bullet points shown in a warning box below the description */
+  details?: string[]
+  confirmLabel: string
+  busyLabel?: string
+  busy?: boolean
+  tone?: "danger" | "primary"
+  onConfirm: () => void | Promise<void>
+  onClose: () => void
+}
+
+const TONE_STYLES: Record<NonNullable<ConfirmDialogProps["tone"]>, string> = {
+  danger: "bg-red-600 text-white hover:bg-red-700",
+  primary: "bg-blue-600 text-white hover:bg-blue-700",
+}
+
+const DETAIL_BOX_STYLES: Record<NonNullable<ConfirmDialogProps["tone"]>, string> = {
+  danger: "border-amber-200 bg-amber-50 text-amber-800",
+  primary: "border-blue-200 bg-blue-50 text-blue-800",
+}
+
+type ConfirmDialogSnapshot = {
+  title: string
+  description: string
+  details?: string[]
+  confirmLabel: string
+  busyLabel?: string
+  busy: boolean
+  tone: NonNullable<ConfirmDialogProps["tone"]>
+}
+
+export default function ConfirmDialog(props: ConfirmDialogProps) {
+  const [snapshot, setSnapshot] = createSignal<ConfirmDialogSnapshot>({
+    title: props.title,
+    description: props.description,
+    details: props.details ? [...props.details] : undefined,
+    confirmLabel: props.confirmLabel,
+    busyLabel: props.busyLabel,
+    busy: props.busy ?? false,
+    tone: props.tone ?? "primary",
+  })
+
+  createEffect(() => {
+    if (!props.open) return
+
+    setSnapshot({
+      title: props.title,
+      description: props.description,
+      details: props.details ? [...props.details] : undefined,
+      confirmLabel: props.confirmLabel,
+      busyLabel: props.busyLabel,
+      busy: props.busy ?? false,
+      tone: props.tone ?? "primary",
+    })
+  })
+
+  const content = () => props.open
+    ? {
+        title: props.title,
+        description: props.description,
+        details: props.details,
+        confirmLabel: props.confirmLabel,
+        busyLabel: props.busyLabel,
+        busy: props.busy ?? false,
+        tone: props.tone ?? "primary",
+      }
+    : snapshot()
+  const tone = () => content().tone
+  const confirmText = () => content().busy ? (content().busyLabel ?? content().confirmLabel) : content().confirmLabel
+
+  function handleClose() {
+    if (props.busy) return
+    props.onClose()
+  }
+
+  function handleConfirm() {
+    if (props.busy) return
+    void props.onConfirm()
+  }
+
+  return (
+    <Modal
+      open={props.open}
+      onClose={handleClose}
+      wrapperClass="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
+      panelClass="w-full max-w-md rounded-2xl bg-white shadow-xl overflow-hidden"
+    >
+      <div class="px-6 pt-6 pb-4 border-b border-gray-100">
+        <div class="flex items-start justify-between gap-3">
+          <div>
+            <h2 class="text-lg font-semibold text-gray-900">{content().title}</h2>
+          </div>
+          <button
+            type="button"
+            onClick={handleClose}
+            disabled={content().busy}
+            class="shrink-0 rounded p-1 text-gray-400 hover:bg-gray-100 hover:text-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+            aria-label="Close"
+          >
+            <svg class="w-5 h-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M18 6L6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      </div>
+
+      <div class="px-6 py-4">
+        <div class="space-y-3 text-left">
+          <p class="text-sm text-gray-600">{content().description}</p>
+          <Show when={content().details && content().details!.length > 0}>
+            <ul class={`w-full rounded-lg border px-4 py-3 space-y-1.5 ${DETAIL_BOX_STYLES[tone()]}`}>
+              <For each={content().details}>
+                {(item) => (
+                  <li class="flex items-start gap-2 text-sm">
+                    <span class="mt-0.5 shrink-0 select-none">•</span>
+                    <span>{item}</span>
+                  </li>
+                )}
+              </For>
+            </ul>
+          </Show>
+        </div>
+      </div>
+
+      <div class="px-6 py-4 flex justify-end gap-3 border-t border-gray-100">
+        <button
+          type="button"
+          onClick={handleClose}
+          disabled={content().busy}
+          class="rounded-lg border border-gray-300 px-4 py-2 text-sm text-gray-700 transition-colors hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          onClick={handleConfirm}
+          disabled={content().busy}
+          class={`rounded-lg px-4 py-2 text-sm font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50 ${TONE_STYLES[tone()]}`}
+        >
+          {confirmText()}
+        </button>
+      </div>
+    </Modal>
+  )
+}

frontend/src/components/PaymentDialog.tsx

@@ -3,7 +3,6 @@ import QRCode from "qrcode"
 import Modal from "@/components/Modal"
 import PaymentSetup from "@/components/PaymentSetup"
 import { getInvoice, getInvoiceBolt11 } from "@/lib/api"
-import { tenantNeedsPaymentSetup } from "@/lib/hooks"
 
 type PayStatus = "idle" | "loading" | "success" | "error"
 type Bolt11Status = "idle" | "loading" | "ready" | "error"
@@ -26,8 +25,8 @@ export default function PaymentDialog(props: PaymentDialogProps) {
   const [bolt11Error, setBolt11Error] = createSignal("")
   const [payStatus, setPayStatus] = createSignal<PayStatus>("idle")
   const [payError, setPayError] = createSignal("")
-  const [showSetup, setShowSetup] = createSignal(false)
   const [showPaymentSetup, setShowPaymentSetup] = createSignal(false)
+  const [setupSaved, setSetupSaved] = createSignal(false)
 
   async function loadBolt11() {
     if (!props.invoice.id) return
@@ -63,7 +62,6 @@ export default function PaymentDialog(props: PaymentDialogProps) {
       const invoice = await getInvoice(props.invoice.id)
       if (invoice.status === "paid") {
         setPayStatus("success")
-        tenantNeedsPaymentSetup().then(needs => setShowSetup(needs)).catch(() => {})
       } else {
         setPayStatus("error")
         setPayError("Payment not yet confirmed. Please try again after sending.")
@@ -81,7 +79,6 @@ export default function PaymentDialog(props: PaymentDialogProps) {
     setBolt11Error("")
     setBolt11("")
     setQrDataUrl("")
-    setShowSetup(false)
     props.onClose()
   }
 
@@ -160,6 +157,15 @@ export default function PaymentDialog(props: PaymentDialogProps) {
                     </button>
                   </div>
                 </Show>
+                <div class="text-center pt-1">
+                  <button
+                    type="button"
+                    onClick={() => setShowPaymentSetup(true)}
+                    class="text-sm text-blue-600 hover:text-blue-700"
+                  >
+                    Set up payment method instead
+                  </button>
+                </div>
               </Show>
             </div>
           }
@@ -172,15 +178,13 @@ export default function PaymentDialog(props: PaymentDialogProps) {
             </div>
             <p class="text-sm font-medium text-gray-900">Payment confirmed!</p>
             <p class="text-xs text-gray-500">Thank you. Your account is up to date.</p>
-            <Show when={showSetup()}>
-              <button
-                type="button"
-                onClick={() => setShowPaymentSetup(true)}
-                class="mt-2 text-sm font-medium text-blue-600 hover:text-blue-700"
-              >
-                Set up automatic payments
-              </button>
-            </Show>
+            <button
+              type="button"
+              onClick={() => setShowPaymentSetup(true)}
+              class="mt-2 text-sm font-medium text-blue-600 hover:text-blue-700"
+            >
+              Set up automatic payments
+            </button>
           </div>
         </Show>
       </div>
@@ -228,7 +232,14 @@ export default function PaymentDialog(props: PaymentDialogProps) {
     </Modal>
     <PaymentSetup
       open={showPaymentSetup()}
-      onClose={() => setShowPaymentSetup(false)}
+      onClose={() => {
+        setShowPaymentSetup(false)
+        if (setupSaved()) {
+          setSetupSaved(false)
+          props.onClose()
+        }
+      }}
+      onSaved={() => setSetupSaved(true)}
     />
     </>
   )

frontend/src/components/PaymentSetup.tsx

@@ -9,6 +9,7 @@ type Tab = "nwc" | "card"
 type PaymentSetupProps = {
   open: boolean
   onClose: () => void
+  onSaved?: () => void
 }
 
 export default function PaymentSetup(props: PaymentSetupProps) {
@@ -27,6 +28,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
     try {
       await updateActiveTenant({ nwc_url: url })
       setSaved(true)
+      props.onSaved?.()
     } catch (e) {
       setError(e instanceof Error ? e.message : "Failed to save wallet connection")
     } finally {
@@ -38,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")
@@ -64,7 +66,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
         <div class="flex items-start justify-between gap-3">
           <div>
             <h2 class="text-lg font-semibold text-gray-900">Set Up Payments</h2>
-            <p class="text-sm text-gray-500 mt-1">Choose how you'd like to pay for your relay.</p>
+            <p class="text-sm text-gray-500 mt-1">Choose how you'd like to pay once invoices are issued for your relay.</p>
           </div>
           <button
             type="button"
@@ -144,7 +146,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
                 <line x1="1" y1="10" x2="23" y2="10" />
               </svg>
             </div>
-            <p class="text-sm text-gray-600">Add a payment card via Stripe to enable automatic billing.</p>
+            <p class="text-sm text-gray-600">Add a payment card via Stripe to enable automatic billing. If an invoice is currently due, we will retry collection after card setup.</p>
             <button
               type="button"
               onClick={openPortal}

frontend/src/components/RelayDetailCard.tsx

@@ -2,6 +2,7 @@ import { A } from "@solidjs/router"
 import { Show, createEffect, createSignal, onCleanup } from "solid-js"
 import type { Relay, PlanId } from "@/lib/api"
 import menuDotsIcon from "@/assets/menu-dots-2.svg"
+import ConfirmDialog from "@/components/ConfirmDialog"
 import Field from "@/components/Field"
 import PricingTable from "@/components/PricingTable"
 import ToggleButton from "@/components/ToggleButton"
@@ -51,8 +52,8 @@ type RelayDetailCardProps = {
   currentMembers?: number
   showTenant?: boolean
   editHref?: string
-  onDeactivate?: () => void
-  onReactivate?: () => void
+  onDeactivate?: () => void | Promise<void>
+  onReactivate?: () => void | Promise<void>
   deactivating?: boolean
   reactivating?: boolean
   onTogglePublicJoin?: () => void
@@ -76,6 +77,7 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
   }
   const [menuOpen, setMenuOpen] = createSignal(false)
   const [plan, setPlan] = createSignal<PlanId>(props.relay.plan)
+  const [pendingAction, setPendingAction] = createSignal<"deactivate" | "reactivate" | null>(null)
 
   let menuContainerRef: HTMLDivElement | undefined
 
@@ -86,6 +88,24 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
   }
   const planLimited = () => (props.enforcePlanLimits ?? true) && r().plan === "free"
   const showPlanActions = () => props.showPlanActions ?? true
+  const actionBusy = () => pendingAction() === "deactivate" ? !!props.deactivating : pendingAction() === "reactivate" ? !!props.reactivating : false
+  const relayLabel = () => r().info_name || r().subdomain
+  const confirmTitle = () => pendingAction() === "deactivate" ? "Deactivate relay?" : "Reactivate relay?"
+  const confirmDescription = () => pendingAction() === "deactivate"
+    ? `${relayLabel()} will be taken offline immediately.`
+    : `${relayLabel()} will come back online and start accepting connections.`
+  const confirmDetails = () => pendingAction() === "deactivate"
+    ? [
+        "All client connections will be dropped immediately.",
+        "Members will be unable to read from or publish to the relay.",
+        "Scheduled and automated tasks (billing, syncing) will be paused.",
+        "All relay data, settings, and members are preserved, nothing is deleted.",
+        "You can reactivate at any time from this page.",
+      ]
+    : undefined
+  const confirmLabel = () => pendingAction() === "deactivate" ? "Yes, deactivate" : "Yes, reactivate"
+  const confirmBusyLabel = () => pendingAction() === "deactivate" ? "Deactivating..." : "Reactivating..."
+  const confirmTone = () => pendingAction() === "deactivate" ? "danger" : "primary"
 
   async function changePlan(plan: PlanId) {
     setPlan(plan)
@@ -97,6 +117,29 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
     }
   }
 
+  function openActionDialog(action: "deactivate" | "reactivate") {
+    setMenuOpen(false)
+    setPendingAction(action)
+  }
+
+  function closeActionDialog() {
+    if (actionBusy()) return
+    setPendingAction(null)
+  }
+
+  async function confirmAction() {
+    const action = pendingAction()
+    if (!action) return
+
+    if (action === "deactivate") {
+      await props.onDeactivate?.()
+    } else {
+      await props.onReactivate?.()
+    }
+
+    setPendingAction(null)
+  }
+
   createEffect(() => {
     if (!menuOpen()) return
 
@@ -128,7 +171,7 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
       <div class="flex items-start justify-between gap-4">
         <div class="flex items-start gap-4 min-w-0">
           <Show when={r().info_icon}>
-            <img src={r().info_icon} alt="" class="w-14 h-14 rounded-xl object-cover flex-shrink-0 border border-gray-200" />
+            <img src={r().info_icon} alt="" class="w-14 h-14 rounded-xl object-cover shrink-0 border border-gray-200" />
           </Show>
           <div class="min-w-0">
             <div class="flex items-center gap-3 flex-wrap">
@@ -148,7 +191,7 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
         </div>
 
         <Show when={props.editHref && (props.onDeactivate || props.onReactivate)}>
-          <div class="relative flex-shrink-0" ref={menuContainerRef}>
+          <div class="relative shrink-0" ref={menuContainerRef}>
             <button
               type="button"
               class="inline-flex h-9 w-9 items-center justify-center rounded-lg border border-gray-200 hover:bg-gray-50"
@@ -177,8 +220,7 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
                   type="button"
                   class="block w-full text-left px-3 py-2 text-sm text-red-600 hover:bg-red-50 disabled:opacity-50"
                   onClick={() => {
-                    setMenuOpen(false)
-                    props.onDeactivate?.()
+                    openActionDialog("deactivate")
                   }}
                   disabled={props.deactivating}
                 >
@@ -190,8 +232,7 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
                   type="button"
                   class="block w-full text-left px-3 py-2 text-sm text-blue-600 hover:bg-blue-50 disabled:opacity-50"
                   onClick={() => {
-                    setMenuOpen(false)
-                    props.onReactivate?.()
+                    openActionDialog("reactivate")
                   }}
                   disabled={props.reactivating}
                 >
@@ -203,6 +244,13 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
         </Show>
       </div>
 
+      <Show when={r().sync_error}>
+        <div class="rounded-lg border border-red-200 bg-red-50 px-4 py-3">
+          <p class="text-sm font-semibold text-red-800">Provisioning error</p>
+          <p class="mt-1 text-sm text-red-700 font-mono break-all">{r().sync_error}</p>
+        </div>
+      </Show>
+
       <hr class="border-gray-200" />
 
       <DetailSection title="Policy">
@@ -339,6 +387,19 @@ export default function RelayDetailCard(props: RelayDetailCardProps) {
           </Show>
         </DetailSection>
       </Show>
+
+      <ConfirmDialog
+        open={pendingAction() !== null}
+        title={confirmTitle()}
+        description={confirmDescription()}
+        details={confirmDetails()}
+        confirmLabel={confirmLabel()}
+        busyLabel={confirmBusyLabel()}
+        busy={actionBusy()}
+        tone={confirmTone()}
+        onConfirm={confirmAction}
+        onClose={closeActionDialog}
+      />
     </div>
   )
 }

frontend/src/components/RelayForm.tsx

@@ -1,6 +1,7 @@
 import { createEffect, createMemo, createSignal, For } from "solid-js"
 import type { Relay } from "@/lib/hooks"
 import { slugify } from "@/lib/slugify"
+import { validateSubdomainLabel } from "@/lib/subdomain"
 import { setToastMessage } from "@/components/Toast"
 import { plans } from "@/lib/state"
 
@@ -31,6 +32,12 @@ export default function RelayForm(props: RelayFormProps) {
       return
     }
 
+    const subdomainError = validateSubdomainLabel(subdomain())
+    if (subdomainError) {
+      setToastMessage(subdomainError)
+      return
+    }
+
     setToastMessage("")
     setSubmitting(true)
 

frontend/src/components/RelayListItem.tsx

@@ -1,4 +1,5 @@
 import { A } from "@solidjs/router"
+import { Show } from "solid-js"
 import type { Relay } from "@/lib/api"
 
 type RelayListItemProps = {
@@ -19,7 +20,17 @@ export default function RelayListItem(props: RelayListItemProps) {
               <p class="text-xs text-gray-500 break-all mt-1">Tenant: {props.relay.tenant}</p>
             )}
           </div>
-          <p class="text-xs uppercase tracking-wide text-gray-500">{props.relay.status}</p>
+          <Show
+            when={props.relay.sync_error}
+            fallback={<p class="text-xs uppercase tracking-wide text-gray-500">{props.relay.status}</p>}
+          >
+            <span
+              class="inline-flex items-center rounded-full border border-red-200 bg-red-50 px-2.5 py-0.5 text-xs font-medium text-red-700 max-w-56 truncate"
+              title={props.relay.sync_error}
+            >
+              {props.relay.sync_error}
+            </span>
+          </Show>
         </div>
       </A>
     </li>

frontend/src/lib/api.ts

@@ -145,6 +145,8 @@ export async function makeAuth(): Promise<string | undefined> {
     kind: 27235,
     content: "",
     created_at: Math.floor(now / 1000),
+    // Intentional session-style auth: sign the API base URL once, then reuse
+    // the header briefly to avoid prompting the signer on every request.
     tags: [["u", API_URL]],
   })
 
@@ -203,6 +205,10 @@ export function getIdentity() {
   return callApi<undefined, Identity>("GET", "/identity")
 }
 
+export function createTenant() {
+  return callApi<undefined, Tenant>("POST", "/tenants")
+}
+
 export function getPlan(id: string) {
   return callApi<undefined, Plan>("GET", `/plans/${id}`)
 }
@@ -235,6 +241,10 @@ export function getRelay(id: string) {
   return callApi<undefined, Relay>("GET", `/relays/${id}`)
 }
 
+export function listRelayMembers(id: string) {
+  return callApi<undefined, { members: string[] }>("GET", `/relays/${id}/members`)
+}
+
 export function listRelayActivity(id: string) {
   return callApi<undefined, { activity: Activity[] }>("GET", `/relays/${id}/activity`)
 }
@@ -243,8 +253,9 @@ export function reactivateRelay(id: string) {
   return callApi<undefined, void>("POST", `/relays/${id}/reactivate`)
 }
 
-export function createPortalSession(pubkey: string) {
-  return callApi<undefined, { url: string }>("GET", `/tenants/${pubkey}/stripe/session`)
+export function createPortalSession(pubkey: string, returnUrl?: string) {
+  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/hooks.ts

@@ -2,7 +2,6 @@ import { createEffect, createResource, createSignal, onCleanup } from "solid-js"
 import { getProfilePicture } from "applesauce-core/helpers/profile"
 import { createOutboxMap, selectOptimalRelays, setFallbackRelays } from "applesauce-core/helpers/relay-selection"
 import { includeMailboxes } from "applesauce-core/observable"
-import { Relay as NostrRelay, RelayManagement } from "applesauce-relay"
 import { map, of } from "rxjs"
 import {
   createRelay,
@@ -12,12 +11,14 @@ import {
   getTenant,
   listRelayActivity,
   listRelays,
+  listTenantInvoices,
   listTenantRelays,
   listTenants,
   updateRelay,
   updateTenant,
   type Activity,
   type CreateRelayInput,
+  type Invoice,
   type Relay,
   type Tenant,
   type UpdateRelayInput,
@@ -137,14 +138,12 @@ export async function tenantNeedsPaymentSetup(): Promise<boolean> {
   return !tenant.nwc_url && !tenant.stripe_subscription_id
 }
 
-export async function getRelayMembers(url: string) {
-  const management = new RelayManagement(new NostrRelay(url), account()!.signer)
-
-  try {
-    return await management.listAllowedPubkeys()
-  } catch {
-    return []
-  }
+export async function getLatestOpenInvoice(): Promise<Invoice | null> {
+  const invoices = await listTenantInvoices(account()!.pubkey)
+  const open = invoices
+    .filter(inv => inv.status === "open" && inv.amount_due > 0)
+    .sort((a, b) => b.period_start - a.period_start)
+  return open[0] ?? null
 }
 
-export type { Activity, Relay, Tenant }
+export type { Activity, Invoice, Relay, Tenant }

frontend/src/lib/subdomain.ts

@@ -0,0 +1,22 @@
+const SUBDOMAIN_LABEL_MAX_LEN = 63
+const RESERVED_SUBDOMAIN_LABELS = new Set(["api", "admin"])
+
+export function validateSubdomainLabel(subdomain: string): string | null {
+  if (subdomain.length === 0) {
+    return "subdomain is required"
+  }
+  if (subdomain.length > SUBDOMAIN_LABEL_MAX_LEN) {
+    return "subdomain must be 63 characters or fewer"
+  }
+  if (subdomain.startsWith("-") || subdomain.endsWith("-")) {
+    return "subdomain cannot start or end with a hyphen"
+  }
+  if (RESERVED_SUBDOMAIN_LABELS.has(subdomain)) {
+    return "subdomain is reserved"
+  }
+  if (!/^[a-z0-9-]+$/.test(subdomain)) {
+    return "subdomain may only contain lowercase letters, numbers, and hyphens"
+  }
+
+  return null
+}

frontend/src/lib/useRelayToggles.ts

@@ -1,7 +1,7 @@
 import { createSignal } from "solid-js"
-import { updateRelayById, deactivateRelayById, reactivateRelayById, tenantNeedsPaymentSetup, type Relay } from "@/lib/hooks"
+import { updateRelayById, deactivateRelayById, reactivateRelayById, getLatestOpenInvoice, tenantNeedsPaymentSetup, type Relay } from "@/lib/hooks"
 import { setToastMessage } from "@/components/Toast"
-import type { PlanId } from "@/lib/api"
+import type { Invoice, PlanId } from "@/lib/api"
 
 function toBool(value: number | undefined, fallback: boolean): boolean {
   if (value === 0) return false
@@ -30,7 +30,8 @@ export default function useRelayToggles(
   { refetch, mutate }: RelayActions,
 ) {
   const [busy, setBusy] = createSignal(false)
-  const [needsPaymentSetup, setNeedsPaymentSetup] = 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 needs = await tenantNeedsPaymentSetup()
-      if (needs) setNeedsPaymentSetup(true)
+      const needsSetup = await tenantNeedsPaymentSetup()
+      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, needsPaymentSetup, clearNeedsPaymentSetup: () => setNeedsPaymentSetup(false), 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/Home.tsx

@@ -8,6 +8,9 @@ import Modal from "@/components/Modal"
 import Login from "@/views/Login"
 import { createRelayForActiveTenant } from "@/lib/hooks"
 import { account } from "@/lib/state"
+import FlotillaLogo from "@/assets/flotilla-logo.svg"
+import ChachiLogo from "@/assets/chachi-logo.svg"
+import NostordLogo from "@/assets/nostord-logo.svg"
 
 export default function Home() {
   const navigate = useNavigate()
@@ -213,7 +216,7 @@ export default function Home() {
           </p>
         </div>
 
-        <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
           {/* Flotilla */}
           <a
             href="https://flotilla.social"
@@ -223,9 +226,7 @@ export default function Home() {
           >
             <div class="flex items-start justify-between gap-4">
               <div class="flex items-center gap-3">
-                <div class="w-12 h-12 rounded-2xl bg-gradient-to-br from-blue-500 to-indigo-600 flex items-center justify-center text-white font-bold text-xl shadow-md shadow-blue-200">
-                  F
-                </div>
+                <img src={FlotillaLogo} alt="Flotilla" class="w-12 h-12 rounded-2xl shadow-md shadow-blue-200" />
                 <div>
                   <h3 class="text-lg font-bold text-gray-900 group-hover:text-blue-600 transition-colors">Flotilla</h3>
                   <p class="text-xs text-gray-400">flotilla.social</p>
@@ -263,9 +264,7 @@ export default function Home() {
           >
             <div class="flex items-start justify-between gap-4">
               <div class="flex items-center gap-3">
-                <div class="w-12 h-12 rounded-2xl bg-gradient-to-br from-purple-500 to-pink-500 flex items-center justify-center text-white font-bold text-xl shadow-md shadow-purple-200">
-                  C
-                </div>
+                <img src={ChachiLogo} alt="Chachi" class="w-12 h-12 rounded-2xl shadow-md shadow-purple-200" />
                 <div>
                   <h3 class="text-lg font-bold text-gray-900 group-hover:text-purple-600 transition-colors">Chachi</h3>
                   <p class="text-xs text-gray-400">chachi.chat</p>
@@ -293,6 +292,45 @@ export default function Home() {
               </span>
             </div>
           </a>
+
+          {/* Nostrord */}
+          <a
+            href="https://nostrord.com/"
+            target="_blank"
+            rel="noopener noreferrer"
+            class="group flex flex-col gap-5 rounded-2xl border border-gray-200 bg-white p-8 hover:border-amber-300 hover:shadow-md transition-all"
+          >
+            <div class="flex items-start justify-between gap-4">
+              <div class="flex items-center gap-3">
+                <img src={NostordLogo} alt="Nostrord" class="w-12 h-12 rounded-2xl shadow-md shadow-amber-200" />
+                <div>
+                  <h3 class="text-lg font-bold text-gray-900 group-hover:text-amber-600 transition-colors">Nostrord</h3>
+                  <p class="text-xs text-gray-400">nostrord.com</p>
+                </div>
+              </div>
+              <span class="text-gray-300 group-hover:text-amber-400 transition-colors mt-1">
+                <ExternalLinkIcon />
+              </span>
+            </div>
+            <p class="text-sm text-gray-600 leading-relaxed">
+              A NIP-29 client built for decentralized group chat on Nostr. Create
+              censorship-resistant communities with admin roles, moderation, and access
+              control—all powered by your relay.
+            </p>
+            <div class="space-y-2">
+              {["Decentralized group chat with NIP-29", "Censorship-resistant communities", "Admin roles & moderation"].map(f => (
+                <div class="flex items-start gap-2 text-sm text-gray-600">
+                  <CheckIcon />
+                  {f}
+                </div>
+              ))}
+            </div>
+            <div class="mt-auto pt-2">
+              <span class="inline-flex items-center gap-1.5 text-sm font-semibold text-amber-600">
+                Visit nostrord.com <ExternalLinkIcon />
+              </span>
+            </div>
+          </a>
         </div>
       </section>
 
@@ -338,6 +376,7 @@ export default function Home() {
           <div class="flex gap-4">
             <a href="https://flotilla.social" target="_blank" rel="noopener noreferrer" class="hover:text-gray-600 transition-colors">Flotilla</a>
             <a href="https://chachi.chat" target="_blank" rel="noopener noreferrer" class="hover:text-gray-600 transition-colors">Chachi</a>
+            <a href="https://nostrord.com/" target="_blank" rel="noopener noreferrer" class="hover:text-gray-600 transition-colors">Nostrord</a>
           </div>
         </div>
       </footer>

frontend/src/pages/admin/AdminRelayDetail.tsx

@@ -1,11 +1,12 @@
 import { useParams } from "@solidjs/router"
-import { Show } from "solid-js"
+import { createResource, Show } from "solid-js"
 import BackLink from "@/components/BackLink"
 import PageContainer from "@/components/PageContainer"
 import RelayDetailCard from "@/components/RelayDetailCard"
 import ResourceState from "@/components/ResourceState"
 import useMinLoading from "@/components/useMinLoading"
 import ActivityFeed from "@/components/ActivityFeed"
+import { listRelayMembers } from "@/lib/api"
 import { useRelay, useRelayActivity } from "@/lib/hooks"
 import useRelayToggles from "@/lib/useRelayToggles"
 
@@ -13,6 +14,15 @@ export default function AdminRelayDetail() {
   const params = useParams()
   const relayId = () => params.id ?? ""
   const [relay, { refetch, mutate }] = useRelay(relayId)
+  const [members] = createResource(relayId, async (id) => {
+    if (!id) return []
+
+    try {
+      return (await listRelayMembers(id)).members
+    } catch {
+      return []
+    }
+  })
   const loading = useMinLoading(() => relay.loading && !relay())
   const [activity] = useRelayActivity(relayId)
   const { busy, handleDeactivate, handleReactivate, toggles } = useRelayToggles(relayId, relay, { refetch, mutate })
@@ -26,6 +36,7 @@ export default function AdminRelayDetail() {
           <div class="space-y-6 mb-6">
             <RelayDetailCard
               relay={r()}
+              currentMembers={members()?.length}
               showTenant
               editHref={`/admin/relays/${params.id}/edit`}
               onDeactivate={handleDeactivate}

frontend/src/pages/relays/RelayDetail.tsx

@@ -1,27 +1,66 @@
 import { useParams } from "@solidjs/router"
-import { createMemo, createResource, 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"
 import PaymentSetup from "@/components/PaymentSetup"
 import RelayDetailCard from "@/components/RelayDetailCard"
 import ResourceState from "@/components/ResourceState"
 import useMinLoading from "@/components/useMinLoading"
 import ActivityFeed from "@/components/ActivityFeed"
-import { getRelayMembers, useRelay, useRelayActivity } from "@/lib/hooks"
+import { listRelayMembers } from "@/lib/api"
+import { getLatestOpenInvoice, useRelay, useRelayActivity, useTenant } from "@/lib/hooks"
 import useRelayToggles from "@/lib/useRelayToggles"
+import { plans } from "@/lib/state"
 
 export default function RelayDetail() {
   const params = useParams()
   const relayId = () => params.id ?? ""
   const [relay, { refetch, mutate }] = useRelay(relayId)
-  const relayUrl = createMemo(() => {
-    const subdomain = relay()?.subdomain
-    return subdomain ? `wss://${subdomain}.spaces.coracle.social` : undefined
+  const [members] = createResource(relayId, async (id) => {
+    if (!id) return []
+
+    try {
+      return (await listRelayMembers(id)).members
+    } catch {
+      return []
+    }
   })
-  const [members] = createResource(relayUrl, getRelayMembers)
   const loading = useMinLoading(() => relay.loading && !relay())
   const [activity] = useRelayActivity(relayId)
-  const { busy, handleDeactivate, handleReactivate, handleUpdatePlan, needsPaymentSetup, clearNeedsPaymentSetup, 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
+    const plan = plans().find(p => p.id === r.plan)
+    return !!(plan && plan.amount > 0)
+  })
+
+  const [openInvoice, { refetch: refetchOpenInvoice }] = createResource(
+    isPaidRelay,
+    async (paid) => paid ? getLatestOpenInvoice() : null
+  )
+
+  const showPaymentNudge = createMemo(() => {
+    if (paymentBannerDismissed()) return false
+    if (!isPaidRelay()) return false
+    const t = tenant()
+    if (!t) return false
+    return !t.nwc_url
+  })
 
   return (
     <PageContainer>
@@ -30,9 +69,47 @@ export default function RelayDetail() {
       <Show when={!loading() && relay()}>
         {(r) => (
           <div class="space-y-6 mb-6">
+            <Show when={showPaymentNudge()}>
+              <div class="rounded-lg border border-amber-200 bg-amber-50 p-4 flex items-start justify-between gap-4">
+                <div class="min-w-0">
+                  <p class="text-sm font-medium text-amber-800">Payment setup recommended</p>
+                  <p class="text-sm text-amber-700 mt-1">
+                    This relay is on a paid plan. Invoices are due when your subscription starts. Set up NWC or Stripe for automatic payments, or pay open invoices via Lightning.
+                  </p>
+                </div>
+                <div class="flex items-center gap-3 shrink-0">
+                  <Show when={openInvoice()}>
+                    <button
+                      type="button"
+                      onClick={() => setInvoiceDialogOpen(true)}
+                      class="text-sm font-medium text-amber-800 underline hover:text-amber-900 whitespace-nowrap"
+                    >
+                      Pay invoice
+                    </button>
+                  </Show>
+                  <button
+                    type="button"
+                    onClick={() => setPaymentSetupOpen(true)}
+                    class="text-sm font-medium text-amber-800 underline hover:text-amber-900 whitespace-nowrap"
+                  >
+                    Set up payments
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => setPaymentBannerDismissed(true)}
+                    aria-label="Dismiss"
+                    class="text-amber-500 hover:text-amber-800 shrink-0"
+                  >
+                    <svg class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                      <path d="M18 6L6 18M6 6l12 12" />
+                    </svg>
+                  </button>
+                </div>
+              </div>
+            </Show>
             <RelayDetailCard
               relay={r()}
-              currentMembers={members.length}
+              currentMembers={members()?.length}
               editHref={`/relays/${params.id}/edit`}
               onDeactivate={handleDeactivate}
               onReactivate={handleReactivate}
@@ -45,9 +122,37 @@ export default function RelayDetail() {
           </div>
         )}
       </Show>
+      <Show when={pendingInvoice()}>
+        {(inv) => (
+          <PaymentDialog
+            invoice={inv()}
+            open={true}
+            onClose={() => {
+              clearPendingInvoice()
+              void refetchTenant()
+              void refetchOpenInvoice()
+            }}
+          />
+        )}
+      </Show>
+      <Show when={openInvoice()}>
+        {(inv) => (
+          <PaymentDialog
+            invoice={inv()!}
+            open={invoiceDialogOpen()}
+            onClose={() => {
+              setInvoiceDialogOpen(false)
+              void refetchOpenInvoice()
+            }}
+          />
+        )}
+      </Show>
       <PaymentSetup
-        open={needsPaymentSetup()}
-        onClose={clearNeedsPaymentSetup}
+        open={paymentSetupOpen()}
+        onClose={() => {
+          setPaymentSetupOpen(false)
+          void refetchTenant()
+        }}
       />
     </PageContainer>
   )

frontend/src/pages/relays/RelayEdit.tsx

@@ -1,7 +1,6 @@
 import { useNavigate, useParams } from "@solidjs/router"
 import { Show } from "solid-js"
 import RelayForm, { type RelayFormValues } from "@/components/RelayForm"
-import { slugify } from "@/lib/slugify"
 import BackLink from "@/components/BackLink"
 import PageContainer from "@/components/PageContainer"
 import ResourceState from "@/components/ResourceState"
@@ -18,7 +17,7 @@ export default function RelayEdit(props: { basePath?: string; title?: string })
 
   async function handleSubmit(values: RelayFormValues) {
     await updateRelayById(relayId(), {
-      subdomain: slugify(values.subdomain),
+      subdomain: values.subdomain,
       info_name: values.info_name.trim(),
       info_icon: values.info_icon.trim(),
       info_description: values.info_description.trim(),

frontend/src/pages/relays/RelayNew.tsx

@@ -1,14 +1,17 @@
-import { createSignal } from "solid-js"
+import { createSignal, Show } from "solid-js"
 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, tenantNeedsPaymentSetup } from "@/lib/hooks"
+import { createRelayForActiveTenant, getLatestOpenInvoice, tenantNeedsPaymentSetup } from "@/lib/hooks"
+import type { Invoice } from "@/lib/api"
 
 export default function RelayNew() {
   const navigate = useNavigate()
-  const [showPaymentSetup, setShowPaymentSetup] = createSignal(false)
+  const [pendingInvoice, setPendingInvoice] = createSignal<Invoice | undefined>()
+  const [paymentSetupOpen, setPaymentSetupOpen] = createSignal(false)
   let createdRelayId = ""
 
   async function handleSubmit(values: RelayFormValues) {
@@ -16,9 +19,14 @@ export default function RelayNew() {
     createdRelayId = relay.id
 
     if (values.plan !== "free") {
-      const needs = await tenantNeedsPaymentSetup()
-      if (needs) {
-        setShowPaymentSetup(true)
+      const needsSetup = await tenantNeedsPaymentSetup()
+      if (needsSetup) {
+        const invoice = await getLatestOpenInvoice()
+        if (invoice) {
+          setPendingInvoice(invoice)
+          return
+        }
+        setPaymentSetupOpen(true)
         return
       }
     }
@@ -26,8 +34,13 @@ export default function RelayNew() {
     navigate(`/relays/${relay.id}`)
   }
 
-  function handleDialogClose() {
-    setShowPaymentSetup(false)
+  function handleInvoiceClose() {
+    setPendingInvoice(undefined)
+    setPaymentSetupOpen(true)
+  }
+
+  function handleSetupClose() {
+    setPaymentSetupOpen(false)
     navigate(`/relays/${createdRelayId}`)
   }
 
@@ -41,9 +54,18 @@ export default function RelayNew() {
         submitLabel="Create Relay"
         submittingLabel="Creating..."
       />
+      <Show when={pendingInvoice()}>
+        {(inv) => (
+          <PaymentDialog
+            invoice={inv()}
+            open={true}
+            onClose={handleInvoiceClose}
+          />
+        )}
+      </Show>
       <PaymentSetup
-        open={showPaymentSetup()}
-        onClose={handleDialogClose}
+        open={paymentSetupOpen()}
+        onClose={handleSetupClose}
       />
     </PageContainer>
   )

frontend/src/views/Login.tsx

@@ -5,6 +5,7 @@ import { PasswordSigner } from "applesauce-signers"
 import QrScanner from "qr-scanner"
 import QRCode from "qrcode"
 import { accountManager, identity, PLATFORM_NAME } from "@/lib/state"
+import { createTenant } from "@/lib/api"
 import useMinLoading from "@/components/useMinLoading"
 
 const NIP46_RELAYS = ['wss://bucket.coracle.social', 'wss://ephemeral.snowflare.cc']
@@ -69,6 +70,12 @@ export default function Login(props: LoginPageProps = {}) {
   async function completeLogin(account: ExtensionAccount | NostrConnectAccount | PrivateKeyAccount | PasswordAccount) {
     accountManager.addAccount(account)
     accountManager.setActive(account)
+    try {
+      await createTenant()
+    } catch (e) {
+      accountManager.removeAccount(account)
+      throw e
+    }
     await props.onAuthenticated?.()
   }
 

frontend/vite.config.ts

@@ -1,13 +1,20 @@
-import { defineConfig } from 'vite'
+import { defineConfig, loadEnv } from 'vite'
 import solid from 'vite-plugin-solid'
 import tailwindcss from '@tailwindcss/vite'
 import { fileURLToPath, URL } from 'node:url'
 
-export default defineConfig({
-  plugins: [tailwindcss(), solid()],
-  resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url)),
+export default defineConfig(({mode}) => {
+  const env = loadEnv(mode, process.cwd(), '')
+
+  return {
+    plugins: [tailwindcss(), solid()],
+    resolve: {
+      alias: {
+        '@': fileURLToPath(new URL('./src', import.meta.url)),
+      },
     },
-  },
+    server: {
+      port: Number(env.VITE_PORT) || 5173,
+    },
+  }
 })

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