+
+
+ 
+
+
+ 
+
++adding token-based authentication, +endpoint restrictions, placeholders, and flexible configuration. +
+ ++⭐️ Secure · 🔒 Configurable · 🚀 Easy to Deploy with Docker +
+ + + +## Contents + +- [Getting Started](#getting-started) +- [Setup](#setup) +- [Usage](#usage) +- [Best Practices](#security-best-practices) +- [Configuration](#configuration) + - [Endpoints](#endpoints) + - [Variables](#variables) +- [Contributing](#contributing) +- [Support](#support) +- [License](#license) ## Getting Started +> **Prerequisites**: You need Docker and Docker Compose installed. + Get the latest version of the `docker-compose.yaml` file: ```yaml @@ -13,11 +52,10 @@ Get the latest version of the `docker-compose.yaml` file: And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens). > [!IMPORTANT] -> This Documentation will be using `sec-signal-api:8880` as the service host, -> this **is just for simplicty**, instead use your containers or hosts IP + Port. -> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy) +> In this documentation, we use `sec-signal-api:8880` as the host for simplicity. +> Replace it with your actual container/host IP, port, or hostname. -### Reverse proxy +### Reverse Proxy Take a look at the [traefik](https://github.com/traefik/traefik) implementation: @@ -27,7 +65,7 @@ Take a look at the [traefik](https://github.com/traefik/traefik) implementation: ## Setup -Before you can send messages via Secured Signal API you must first setup [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) +Before you can send messages via Secured Signal API you must first set up [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) To be able to use the API you have to either: @@ -37,46 +75,27 @@ OR - **link Signal API to an already registered Signal Device** -> [!TIP] -> It is advised to do Setup directly with Signal rAPI -> if you try to Setup with Secured Signal API you will be blocked from doing so. See [Blocked Endpoints](#blocked-endpoints). - -## Usage - -Secured Signal API provides 3 Ways to Authenticate - -### Bearer - -To Authenticate add `Authorization: Bearer API_TOKEN` to your request Headers - -### Basic Auth - -To use Basic Auth as Authorization Method add `Authorization: Basic BASE64_STRING` to your Headers - -User is `api` (LOWERCASE) - -Formatting for `BASE64_STRING` = `user:API_TOKEN`. +1. **Register** or **link** a Signal account with `signal-cli-rest-api` -example: +2. Deploy `secured-signal-api` with at least one API token -```bash -echo "api:API_TOKEN" | base64 -``` - -=> `YXBpOkFQSV9LRVkK` +3. Confirm you can send a test message (see [Usage](#usage)) -### Query Auth +> [!TIP] +> Run setup directly with Signal rAPI. +> Setup requests via Secured Signal API are blocked. See [Blocked Endpoints](#blocked-endpoints). -If you are working with a limited Application you may **not** be able to modify Headers or the Request Body -in this case you can use **Query Auth**. +## Usage -Here is a simple example: +Secured Signal API provides 3 Ways to Authenticate -```bash -curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN -``` +### Auth -Notice the `@` infront of `authorization`. See [KeyValue Pair Injection](#keyvalue-pair-injection). +| Method | Example | +| :---------- | :--------------------------------------------------------- | +| Bearer Auth | Add `Authorization: Bearer API_TOKEN` to headers | +| Basic Auth | Add `Authorization: Basic BASE64_STRING` (`api:API_TOKEN`) | +| Query Auth | Append `@authorization=API_TOKEN` to request URL | ### Example @@ -126,6 +145,13 @@ you have to add `@` in front of any KeyValue Pair assignment. Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type). +## Security: Best Practices + +- Always use API tokens in production +- Run behind a TLS-enabled [Reverse Proxy](#reverse-proxy) (Traefik, Nginx, Caddy) +- Be cautious when overriding Blocked Endpoints +- Use per-token overrides to enforce least privilege + ## Configuration There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config. @@ -186,8 +212,7 @@ If you are using Environment Variables as an example you won't be able to specif | array(str) | [a,b,c] | > [!NOTE] -> If you have a string that should not be turned into any other type, then you will need to escape all Type Denotations, `[]` or `{}` (also `-`) with a `\` **Backslash**. -> **Double Backslashes** do exist but you could just leave them out completly. +> If you have a string that should not be turned into any other type, then you will need to escape all Type Denotations, `[]` or `{}` (also `-`) with a `\` **Backslash** (or Double Backslash). > An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**. ### API Token(s) @@ -214,7 +239,7 @@ Since Secured Signal API is just a Proxy you can use all of the [Signal REST API | :-------------------- | ------------------ | | **/v1/about** | **/v1/unregister** | | **/v1/configuration** | **/v1/qrcodelink** | -| **/v1/devives** | **/v1/contacts** | +| **/v1/devices** | **/v1/contacts** | | **/v1/register** | **/v1/accounts** | These Endpoints are blocked by default due to Security Risks. @@ -260,7 +285,10 @@ settings: ### Message Aliases -To improve compatibility with other services Secured Signal API provides aliases for the `message` attribute by default: +To improve compatibility with other services Secured Signal API provides **Message Aliases** for the `message` attribute. + +