Merge pull request #13 from cross-seed/api-auth-docs

Api auth docs

docs/basics/daemon.md

@@ -15,7 +15,7 @@ and enabling the following features:
 - watching for new releases:
   - scanning RSS feeds periodically ([`rssCadence`](./options.md#rsscadence)) for matching content
   - listening for new release announces and snatching them if you already
-    have the data (e.g. [autobrr](https://autobrr.com/) -> [`announce`](../reference/api.md#post-apiannounce-experimental) API endpoint)
+    have the data (e.g. [autobrr](https://autobrr.com/) -> [`announce`](../reference/api.md#post-apiannounce) API endpoint)
 - Running batch searches on your full collection of torrents periodically ([`searchCadence`](./options.md#searchcadence))
 
 :::tip
@@ -35,9 +35,8 @@ finished downloading, and ways to watch for new releases.
 
 :::danger
 
-`cross-seed` does _not_ have API auth.
-
-**Do not expose its port to untrusted networks (such as the Internet).**
+`cross-seed` has an [`apiAuth` option](./options.md#apiauth) to require authorization on requests, but we still recommend
+that you **do not expose its port to untrusted networks (such as the Internet).**
 
 :::
 
@@ -177,10 +176,37 @@ cross-seeds as soon as a torrent finishes downloading. However, it requires some
 manual setup.
 
 :::info
-If you plan on utilizing the [`path`](../tutorials/data-based-matching.md) [`webhook`](../reference/api.md#post-apiwebhook)
+If you plan on using the [`path`](../tutorials/data-based-matching.md) [`webhook`](../reference/api.md#post-apiwebhook)
 API call, you will need to [**set up data-based matching**](../tutorials/data-based-matching.md#setup) in your config file.
 :::
 
+### Step 1: Find your API key
+
+If you have the `apiAuth` option enabled (which you should),
+you will need to supply an API key with your `curl` commands. API keys can be included with your requests in one of two ways:
+
+- an `X-Api-Key` HTTP header
+- an `apikey` query param
+
+In this doc we will use the query param version.
+
+:::tip Docker
+Start by shelling into your container:
+
+```shell
+docker exec -it cross-seed sh
+```
+
+:::
+
+You can find your API key with the following command:
+
+```shell
+cross-seed api-key
+```
+
+In the rest of this doc, we will refer to this as `YOUR_API_KEY`.
+
 ### rTorrent
 
 For rTorrent, you'll have to edit your `.rtorrent.rc` file.
@@ -192,9 +218,9 @@ For rTorrent, you'll have to edit your `.rtorrent.rc` file.
 
     ```shell
     #!/bin/sh
-    # curl -XPOST http://localhost:2468/api/webhook --data-urlencode "name=$1"
-    curl -XPOST http://localhost:2468/api/webhook --data-urlencode "infoHash=$2"
-    # curl -XPOST http://localhost:2468/api/webhook --data-urlencode "path=$3"
+    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "name=$1"
+    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$2"
+    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=$3"
     ```
 
     :::tip Docker
@@ -204,14 +230,15 @@ For rTorrent, you'll have to edit your `.rtorrent.rc` file.
     host's IP (e.g. 192.x or 10.x) if not using custom Docker networks.
 
     :::
+
     :::tip
-    You will need to pick a method of search, **infoHash is recommended** - but requires your session directory from `.rtorrent.rc` to
-    be mounted (Docker) and/or set to [`torrentDir`](./options.md#torrentdir) in the config or it will not function properly.
+    You will need to pick a method of search, **infoHash is recommended** - but requires your **session directory** from `.rtorrent.rc` to
+    be mounted (Docker) and set to [`torrentDir`](./options.md#torrentdir) in the config.
     :::
 
 3.  Uncomment/Comment the appropriate lines to decide how you wish to use search.
 
-    - The hastag/pound-sign `#` is used to "comment" the line - commented lines
+    - The hashtag/pound-sign `#` is used to "comment" the line - commented lines
       will not be executed.
 
 4.  Run the following command (this will give rTorrent permission to execute
@@ -242,19 +269,19 @@ For rTorrent, you'll have to edit your `.rtorrent.rc` file.
    **Name Based:**
 
    ```shell
-   curl -XPOST http://localhost:2468/api/webhook --data-urlencode "name=%N"
+   curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "name=%N"
    ```
 
    **InfoHash Based:**
 
    ```shell
-   curl -XPOST http://localhost:2468/api/webhook --data-urlencode "infoHash=%I"
+   curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=%I"
    ```
 
    [**Data Based:**](../tutorials/data-based-matching.md#setup)
 
    ```shell
-   curl -XPOST http://localhost:2468/api/webhook --data-urlencode "path=%F"
+   curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=%F"
    ```
 
 :::tip Docker
@@ -286,7 +313,7 @@ You can add infoHash searching using the following script:
 ```shell
     #!/bin/bash
     oldcommand ${1}
-    curl -XPOST http://localhost:2468/api/webhook --data-urlencode "infoHash=${2}"
+    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=${2}"
 ```
 
 Then add this in qBittorrent's settings to execute the script:
@@ -309,7 +336,7 @@ You may need to adjust the variables above that qBittorrent sends to the script.
 
     ```shell
     #!/bin/sh
-    curl -XPOST http://localhost:2468/api/webhook --data-urlencode "infoHash=$TR_TORRENT_HASH"
+    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$TR_TORRENT_HASH"
     ```
 
     :::tip Docker
@@ -347,9 +374,9 @@ You may need to adjust the variables above that qBittorrent sends to the script.
     torrentid=$1
     torrentname=$2
     torrentpath=$3
-    # curl -XPOST http://localhost:2468/api/webhook --data-urlencode "name=$torrentname"
-    curl -XPOST http://localhost:2468/api/webhook --data-urlencode "infoHash=$torrentid"
-    # curl -XPOST http://localhost:2468/api/webhook --data-urlencode "path=$torrentpath/$torrentname"
+    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "name=$torrentname"
+    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$torrentid"
+    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=$torrentpath/$torrentname"
     ```
 
     :::tip Docker

docs/basics/faq-troubleshooting.md

@@ -122,7 +122,7 @@ We try to reduce unnecessary snatches of .torrent files as much as possible, but
 
 ### How can I use [**autobrr**](https://autobrr.com/) with cross-seed?
 
-If you are using [**autobrr**](https://autobrr.com/) to cross-seed, you can use the [`/api/announce`](../reference/api#post-apiannounce-experimental) endpoint, rather than [`/api/webhook`](../reference/api#post-apiwebhook), to match against what cross-seed [already knows about your available media](../reference/architecture#prefiltering) (instead of searching your indexers every time).
+If you are using [**autobrr**](https://autobrr.com/) to cross-seed, you can use the [`/api/announce`](../reference/api#post-apiannounce) endpoint, rather than [`/api/webhook`](../reference/api#post-apiwebhook), to match against what cross-seed [already knows about your available media](../reference/architecture#prefiltering) (instead of searching your indexers every time).
 
 :::tip
 If you want to filter announces even further, consider setting up more specific filters or using [**omegabrr**](https://github.com/autobrr/omegabrr) (which filters based on monitored items in Arrs) to minimize calls to cross-seed.

docs/basics/options.md

@@ -121,6 +121,7 @@ The configuration file uses JavaScript syntax, which means:
 | [`port`](#port)                                     |              |
 | [`rssCadence`](#rssCadence)                         |              |
 | [`searchCadence`](#searchCadence)                   |              |
+| [`apiAuth`](#apiAuth)                               |              |
 
 ## All options
 
@@ -134,7 +135,7 @@ When running a search with `cross-seed search` or using `searchCadence` in
 daemon mode, the `delay` option lets you set how long you want `cross-seed` to
 sleep in between searching for each torrent. If you set it higher, it will
 smooth out load on your indexers, but if you set it lower, `cross-seed` will run
-faster. I don't recommend setting this lower than 2, as it could garner you
+faster. We don't recommend setting this lower than 2, as it could garner you
 unwanted attention from tracker staff.
 
 #### `delay` Examples (CLI)
@@ -948,3 +949,37 @@ searchCadence: "4 weeks",
 
 [pr]: https://github.com/cross-seed/cross-seed.org/tree/master/docs/basics/options.md
 [ms]: https://github.com/vercel/ms#examples
+
+### `apiAuth`
+
+| Config file name | CLI short form | CLI long form | Format    | Default |
+| ---------------- | -------------- | ------------- | --------- | ------- |
+| `apiAuth`        |                | `--api-auth`  | `boolean` | `false` |
+
+Set this to `true` to require an API key on all requests made to the
+[/api/announce](../reference/api.md#post-apiannounce) and
+[/api/webhook](../reference/api.md#post-apiwebhook) endpoints.
+
+To find your API key, run the `cross-seed api-key` command.
+The api key can be included with your requests in either of two ways:
+
+```shell
+# provide api key as a query param
+curl -XPOST localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode ...
+# provide api key as an HTTP header
+curl -XPOST localhost:2468/api/webhook -H "X-Api-Key: YOUR_API_KEY" --data-urlencode ...
+```
+
+#### `apiAuth` Examples (CLI)
+
+```shell
+cross-seed daemon --api-auth # will require auth on requests
+cross-seed daemon --no-api-auth # will allow any requests
+```
+
+#### `apiAuth` Examples (Config file)
+
+```js
+apiAuth: true,
+apiAuth: false,
+```

docs/reference/api.md

@@ -8,14 +8,26 @@ on port 2468 (configurable with the [`port`](../basics/options#port) option).
 You can easily configure your torrent client to [send search commands when a torrent finishes.](../basics/daemon#set-up-automatic-searches-for-finished-downloads)
 :::
 
-:::danger
-
-`cross-seed` does _not_ have API auth.
+## Authorization
 
-**Do not expose its port to untrusted networks (such as the Internet)**
+You can enable the
+[`apiAuth` option](../basics/options.md#apiauth) to require authorization
+on all HTTP requests made to the cross-seed daemon.
 
+:::danger
+Even with API auth enabled, we still recommend that you **do not expose its port to untrusted networks (such as the Internet).**
 :::
 
+To find your API key, run the `cross-seed api-key` command.
+The api key can be included with your requests in either of two ways:
+
+```shell
+# provide api key as a query param
+curl -XPOST localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode ...
+# provide api key as an HTTP header
+curl -XPOST localhost:2468/api/webhook -H "X-Api-Key: YOUR_API_KEY" --data-urlencode ...
+```
+
 ## POST `/api/webhook`
 
 This endpoint invokes a search, on all configured trackers, for a specific
@@ -64,7 +76,7 @@ curl -XPOST http://localhost:2468/api/webhook \
   --data '{"name":"<torrent name here>"}'
 ```
 
-## POST `/api/announce` (experimental)
+## POST `/api/announce`
 
 Use this endpoint to feed announces into cross-seed. For each `announce`,
 `cross-seed` will check if the provided search criteria match any torrents you already

website.iml

@@ -2,7 +2,11 @@
 <module version="4">
   <component name="NewModuleRootManager" inherit-compiler-output="true">
     <exclude-output />
-    <content url="file://$MODULE_DIR$" />
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.docusaurus" />
+      <excludeFolder url="file://$MODULE_DIR$/build" />
+      <excludeFolder url="file://$MODULE_DIR$/node_modules" />
+    </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>