caravel/backend/spec/api.md

# `pub struct Api`

Api manages the HTTP interface for the application

Members:

- `host: String` - the hostname of the service for checking NIP 98 auth, from `HOST`
- `port: u16` - a port to run the server on from `PORT`
- `admins: Vec<String>` - a list of admin pubkeys from `ADMINS`
- `origins: Vec<String>` - to be used in CORS headers, from `ALLOW_ORIGINS`
- `repo: Repo`

Notes:

- Authentication is done using NIP 98 comparing `u` to `self.host`, not the incoming request
- Each route is responsible for authorization using `self.is_admin(pubkey)` or `self.is_tenant(authorized_pubkey, tenant_pubkey)`
- Successful API responses should be of the form `{data, code: "ok"}` with an appropriate http status code.
- Unsuccessful API responses should be of the form `{error, code}` with an appropriate http status code. `code` is a short error code (e.g. `duplicate-subdomain`) and `error` is a human-readable error message.

## `pub fn new() -> Self`

- Reads environment and populates members

## `pub fn serve(&self) -> Result<()>`

- Initializes an `axum::Router`
- Adds CORS middleware based on `origins`
- Calls `axum::serve` with a listener

--- Plan routes

## `async fn list_plans(...) -> Response`

- Serves `GET /plans`
- Return `data` is a list of plan structs from `Repo::list_plans`

## `async fn get_plan(...) -> Response`

- Serves `GET /plans/:id`
- Return `data` is a single plan struct matching `id`
- If plan does not exist, return `404` with `code=not-found`

--- Tenant routes

## `async fn list_tenants(...) -> Response`

- Serves `GET /tenants`
- Authorizes admin only
- Return `data` is a list of tenant structs from `repo.list_tenants`

## `async fn get_tenant(...) -> Response`

- Serves `GET /tenants/:pubkey`
- Authorizes admin or matching tenant
- Return `data` is a single tenant struct from `repo.get_tenant`

## `async fn create_tenant(...) -> Response`

- Serves `POST /tenants`
- Authorizes anyone, but must be authorized
- Creates a new tenant using `repo.create_tenant` based on the authorized pubkey
- If tenant is a duplicate, return a `422` with `code=pubkey-exists`
- Return `data` is a single tenant struct. Use HTTP `201`.

## `async fn list_tenant_relays(...) -> Response`

- Serves `GET /tenants/:pubkey/relays`
- Authorizes admin or matching tenant
- Return `data` is a list of relay structs from `repo.list_relays_for_tenant`

## `async fn list_tenant_invoices(...) -> Response`

- Serves `GET /tenants/:pubkey/invoices`
- Authorizes admin or matching tenant
- Return `data` is a list of invoice structs from `repo.list_invoices_for_tenant`

## `async fn update_tenant_billing(...) -> Response`

- Serves `PUT /tenants/:pubkey/billing`
- Authorizes admin or matching tenant
- Updates tenant billing NWC URL using `repo.update_tenant_nwc_url`
- Return `data` is the submitted billing payload

--- Relay routes

## `async fn list_relays(...) -> Response`

- Serves `GET /relays`
- Authorizes admin only
- Return `data` is a list of relay structs from `repo.list_relays`

## `async fn get_relay(...) -> Response`

- Serves `GET /relays/:id`
- Authorizes admin or relay owner
- Return `data` is a single relay struct from `repo.get_relay`

## `async fn create_relay(...) -> Response`

- Serves `POST /relays`
- Authorizes admin or matching tenant pubkey in request body
- Validates/prepares the relay data to be saved using `prepare_relay`
- Creates a new relay using `repo.create_relay`
- If relay is a duplicate by subdomain, return a `422` with `code=subdomain-exists`
- Return `data` is a single relay struct. Use HTTP `201`.

## `async fn update_relay(...) -> Response`

- Serves `PUT /relays/:id`
- Authorizes admin or relay owner
- Validates/prepares the relay data to be saved using `prepare_relay`
- Updates the given relay using `repo.update_relay`
- If relay is a duplicate by subdomain, return a `422` with `code=subdomain-exists`
- Return `data` is a single relay struct.

## `async fn deactivate_relay(...) -> Response`

- Serves `POST /relays/:id/deactivate`
- Authorizes admin or relay owner
- Deactivates relay using `repo.deactivate_relay`
- Return `data` is empty

--- Invoice routes

## `async fn list_invoices(...) -> Response`

- Serves `GET /invoices`
- Authorizes admin only
- Return `data` is a list of invoice structs from `repo.list_invoices`

## `async fn get_invoice(...) -> Response`

- Serves `GET /invoices/:id`
- Authorizes admin or invoice owner
- Return `data` is a single invoice struct from `repo.get_invoice`

--- 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
- 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.

## `require_admin(&self, authorized_pubkey: &str)`

- Checks whether `authorized_pubkey` is in `self.admins`. If not, returns an forbidden error

## `require_admin_or_tenant(&self, authorized_pubkey: &str, tenant_pubkey: &str)`

- Checks whether `authorized_pubkey` is an admin or matches `tenant_pubkey`

## `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`
- Populate `schema` if not already set
- Populate missing fields using reasonable defaults