# `pub struct Api` Api owns the HTTP interface: the shared application state, the router, NIP-98 authentication, and the authorization helpers. The route handlers themselves live in `crate::routes` (`routes/identity.rs`, `plans.rs`, `tenants.rs`, `relays.rs`, `invoices.rs`, `stripe.rs`) and use the response helpers in `spec/web.md`. Members: - `env: Env` - configuration (see `spec/env.md`); supplies the NIP-98 host check, admin pubkeys, encryption, etc. - `query: Query` - `command: Command` - `billing: Billing` - `stripe: Stripe` - `robot: Robot` - `infra: Infra` Notes: - Authentication is done using NIP-98, comparing the event's `u` tag to `env.server_host`, not the incoming request URL. - The shared `Api` is wrapped in an `Arc` and handed to every handler as `State>`. - A handler that requires an authenticated caller takes an `AuthedPubkey` extractor; handlers that omit it are anonymous. - Each handler is responsible for authorization using `require_admin` or `require_admin_or_tenant`. - Successful responses are `{ data, code: "ok" }`; error responses are `{ error, code }`, both with an appropriate HTTP status (see `spec/web.md`). ## `pub fn new(query, command, billing, stripe, robot, infra, env: &Env) -> Self` - Stores the services and a clone of `env` ## `pub fn router(self) -> Router` - Wraps `self` in an `Arc` and returns an `axum::Router` with the routes below as state-bearing routes ## `pub fn is_admin(&self, pubkey: &str) -> bool` - Whether `pubkey` is in `env.server_admin_pubkeys` ## `pub fn require_admin(&self, authorized_pubkey: &str) -> Result<(), ApiError>` - `Ok` if `authorized_pubkey` is an admin, otherwise a `403` ## `pub fn require_admin_or_tenant(&self, authorized_pubkey: &str, tenant_pubkey: &str) -> Result<(), ApiError>` - `Ok` if `authorized_pubkey` is an admin or equals `tenant_pubkey`, otherwise a `403` ## `pub async fn get_tenant_or_404(&self, pubkey: &str) -> Result` - Looks up a tenant, returning `404` `not-found` if missing and `500` on a query error ## `pub async fn get_relay_or_404(&self, id: &str) -> Result` - Looks up a relay, returning `404` `not-found` if missing and `500` on a query error # Authentication ## `pub struct AuthedPubkey(pub String)` An axum extractor (`FromRequestParts`) that authenticates a request via NIP-98 and yields the signer's pubkey. Adding it to a handler signature is what enforces "must be authenticated"; on failure the request is rejected with a `401`. ## `fn extract_auth_pubkey(&self, headers: &HeaderMap) -> Result` / `fn decode_nip98_pubkey(&self, headers) -> Result` - Parses the `Authorization` header, which must use the `Nostr ` scheme followed by a base64-encoded NIP-98 event - Decodes and parses the event, requires kind `27235` (`HttpAuth`), and verifies its signature - Requires the event's `u` tag to contain `env.server_host` (skipped when `server_host` is empty) - Intentionally does **not** enforce exact request URL/method/query matching, and does **not** validate the `payload` tag/hash, `created_at` freshness window, or a replay nonce/cache - This is a deliberate session-style tradeoff to reduce repeated signer prompts in the client - Returns the signer pubkey (hex) when all checks pass; any failure surfaces as a `401` Refer to https://github.com/nostr-protocol/nips/blob/master/98.md for details. Uses `nostr_sdk` functionality where possible. # Routes Handlers take `State>`, an optional `AuthedPubkey`, then path/query/body extractors, and return `ApiResult`. --- Identity ## `get_identity` — `GET /identity` - Authenticated (any signer) - Side-effect-free: returns `{ pubkey, is_admin }` - Clients must call `POST /tenants` before any tenant-scoped write --- Plans ## `list_plans` — `GET /plans` - No authentication required - `data` is the list of plans from `query.list_plans` ## `get_plan` — `GET /plans/:id` - No authentication required - `data` is the plan matching `id`; `404` `not-found` if it doesn't exist --- Tenants ## `list_tenants` — `GET /tenants` - Admin only - `data` is a list of `TenantResponse` (exposes `nwc_is_set: bool` instead of `nwc_url`) ## `create_tenant` — `POST /tenants` - Authenticated (any signer); the target pubkey is the auth pubkey, no request body - Idempotent: if a tenant already exists for the auth pubkey, return it without calling Stripe or writing to the DB - Otherwise resolve a display name via `robot.fetch_nostr_name` (falling back to the first 8 chars of the pubkey), create a Stripe customer via `stripe.create_customer`, and create the tenant. No subscription is created yet — that happens when the first paid relay is added. - On a unique-constraint race (`pubkey-exists`), re-fetch and return the existing tenant - Always returns `200`; `data` is a `TenantResponse` ## `get_tenant` — `GET /tenants/:pubkey` - Admin or matching tenant - `data` is a `TenantResponse` ## `update_tenant` — `PUT /tenants/:pubkey` - Admin or matching tenant - Accepts an optional `nwc_url`: an empty string clears it, otherwise it is encrypted at rest via `env.encrypt` - Updates the tenant via `command.update_tenant` - `data` is the updated `TenantResponse` ## `list_tenant_relays` — `GET /tenants/:pubkey/relays` - Admin or matching tenant - `data` is the tenant's relays from `query.list_relays_for_tenant` --- Relays ## `list_relays` — `GET /relays` - Admin only - `data` is all relays from `query.list_relays` ## `get_relay` — `GET /relays/:id` - `404` `not-found` if the relay doesn't exist; then admin or relay owner - `data` is the relay ## `list_relay_members` — `GET /relays/:id/members` - Admin or relay owner - For unsynced relays (`synced = 0`), returns an empty member list without calling zooid - For synced relays, proxies the member list from zooid via `infra.list_relay_members` - `data` is `{ members }` ## `create_relay` — `POST /relays` - Admin or the `tenant` pubkey in the request body - Generates the relay `id`/`schema`, validates and normalizes the relay via `prepare_relay`, and creates it via `command.create_relay` - Duplicate subdomain → `422` `subdomain-exists` - `data` is the relay; HTTP `201` ## `update_relay` — `PUT /relays/:id` - `404` if missing; then admin or relay owner - Applies the provided optional fields, then validates/normalizes via `prepare_relay` - If the plan changes to one with a finite member limit and the current member count exceeds it, return `422` `member-limit-exceeded` - Updates via `command.update_relay`; duplicate subdomain → `422` `subdomain-exists` - `data` is the relay ## `list_relay_activity` — `GET /relays/:id/activity` - `404` if missing; then admin or relay owner - `data` is `{ activity }` from `query.list_activity_for_resource` ## `deactivate_relay` — `POST /relays/:id/deactivate` - `404` if missing; then admin or relay owner - If status is `delinquent`, return `400` `relay-is-delinquent`; if already `inactive`, return `400` `relay-is-inactive` - Otherwise `command.deactivate_relay`; `data` is empty ## `reactivate_relay` — `POST /relays/:id/reactivate` - `404` if missing; then admin or relay owner - If status is `delinquent`, return `400` `relay-is-delinquent` (a delinquent relay must be resolved through payment, not reactivated by the user); if already `active`, return `400` `relay-is-active` - Otherwise `command.activate_relay`; `data` is empty --- Invoices ## `list_tenant_invoices` — `GET /tenants/:pubkey/invoices` - Admin or matching tenant - Looks up the tenant, then lists invoices from Stripe by `stripe_customer_id` - `data` is a list of `StripeInvoice` objects: `{ id, customer, status, amount_due, currency }` ## `get_invoice` — `GET /invoices/:id` - Fetches the invoice from Stripe (`404` `not-found` if it doesn't exist) - Looks up the tenant by the invoice's `customer` (`404` if none), then authorizes admin or matching tenant - Runs `billing.reconcile_invoice` (marks it paid if its bolt11 already settled out of band) - `data` is the (possibly refreshed) `StripeInvoice` ## `get_lightning_invoice` — `GET /invoices/:id/bolt11` - Fetches the invoice from Stripe (`404` if it doesn't exist) and the tenant by `customer` (`404` if none), then authorizes admin or matching tenant - Runs `billing.reconcile_invoice`, then `billing.ensure_lightning_invoice` to get or (re)issue the bolt11 for the invoice's `amount_due`/`currency` - `data` is the `LightningInvoice` (including its `bolt11`) --- Stripe portal ## `create_stripe_session` — `GET /tenants/:pubkey/stripe/session` - Admin or matching tenant; accepts an optional `return_url` query parameter - Looks up the tenant and creates a Stripe Customer Portal session for its `stripe_customer_id` - `data` is `{ url }` — the portal session URL --- Stripe webhook ## `stripe_webhook` — `POST /stripe/webhook` - No NIP-98 authentication — verified via the `Stripe-Signature` header over the raw body - Reads the raw body and signature, verifies/parses the event via `stripe.get_webhook_event`, and dispatches to the handlers below - Returns `200` on success, `400` (`webhook-error`) on verification/parse failure # Webhook event handlers Implemented in `routes/stripe.rs`. They translate verified Stripe events into domain actions, looking the tenant up by `stripe_customer_id` and ignoring events whose customer doesn't map to a tenant. Unknown event types are ignored. ## `invoice.created` Attempts to pay a new subscription invoice (Stripe is pay-in-advance, so this fires immediately when a paid relay is added or a plan is upgraded). Skips `amount_due` of 0. Ensures a `LightningInvoice` exists, then in priority order: 1. **NWC auto-pay**: if the tenant has a `nwc_url`, run `billing.pay_invoice_nwc`. On success, done. On failure, record the error via `command.set_tenant_nwc_error`, log it, summarize it for the eventual DM, and fall through. 2. **Card on file**: if `stripe.has_payment_method`, do nothing — Stripe charges automatically for this attempt. 3. **Manual payment**: send a DM via `robot.send_dm` telling the tenant payment is due (including the summarized NWC error, if any), with a link to the app for manual Lightning payment. ## `invoice.paid` - If the tenant has `past_due_at` set, clear it (`command.clear_tenant_past_due`) and reactivate each `delinquent` relay on a paid plan via `command.activate_relay` ## `invoice.payment_failed` - If the tenant doesn't already have `past_due_at` set, set it (`command.set_tenant_past_due`) and DM the tenant that payment failed and their relays may be deactivated if unresolved ## `invoice.overdue` - Mark every `active` relay on a paid plan `delinquent` (`command.mark_relay_delinquent`) and DM the tenant that their paid relays were deactivated for non-payment ## `customer.subscription.updated` - If the subscription status is `canceled` or `unpaid`, clear `stripe_subscription_id` (`command.clear_tenant_subscription`) and mark every `active` paid relay `delinquent` ## `customer.subscription.deleted` - Clear `stripe_subscription_id` (`command.clear_tenant_subscription`) ## `payment_method.attached` - Retry Stripe collection (`stripe.pay_invoice`) for every `open` invoice with `amount_due > 0`, so invoices that were due before the card was added are charged immediately # Helpers ## `prepare_relay(api: &Api, relay: Relay) -> Result` - Validates `subdomain` against the allowed pattern and a reserved list (`api`, `admin`, `internal`) → `422` `invalid-subdomain` - Validates that `plan` matches a known plan → `422` `invalid-plan` - If the relay enables `blossom`/`livekit` but the selected plan doesn't include it → `422` `premium-feature` - Normalizes the boolean relay flags to sane defaults # `TenantResponse` The tenant shape returned by tenant endpoints. Same as `Tenant` but replaces `nwc_url` with `nwc_is_set: bool` (true when a `nwc_url` is stored) and never exposes the stored URL: `{ pubkey, nwc_is_set, nwc_error, created_at, stripe_customer_id, stripe_subscription_id, past_due_at }`.