Skip to content

Commit 4260690

Browse files
github-actions[bot]github-actions[bot]
committed
Update README.md
1 parent c15e20b commit 4260690

File tree

1 file changed

+73
-43
lines changed

1 file changed

+73
-43
lines changed

‎README.md‎

Lines changed: 73 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,48 @@
11
<img align="center" width="1048" height="512" alt="Secure Proxy for Signal REST API" src="https://github.com/CodeShellDev/secured-signal-api/raw/refs/heads/main/logo/landscape" />
22

3-
<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal Messenger REST API</a></h5>
3+
<h3 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal Messenger REST API</a></h3>
4+
5+
<p align="center">
6+
adding token-based authentication,
7+
endpoint restrictions, placeholders, and flexible configuration.
8+
</p>
9+
10+
<p align="center">
11+
⭐️ Secure · 🔒 Configurable · 🚀 Easy to Deploy with Docker
12+
</p>
13+
14+
<div align="center">
15+
<a href="https://github.com/codeshelldev/secured-signal-api/releases">
16+
<img src="https://img.shields.io/github/v/release/codeshelldev/secured-signal-api?sort=semver&logo=github" alt="GitHub release">
17+
</a>
18+
<a href="https://github.com/codeshelldev/secured-signal-api/pkgs/container/secured-signal-api">
19+
<img src="https://ghcr-badge.egpl.dev/codeshelldev/secured-signal-api/size?color=%2344cc11&tag=latest&label=image+size&trim=" alt="GHCR pulls">
20+
</a>
21+
<a href="./LICENSE">
22+
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
23+
</a>
24+
<a href="https://github.com/codeshelldev/secured-signal-api/stargazers">
25+
<img src="https://img.shields.io/github/stars/codeshelldev/secured-signal-api?style=social" alt="GitHub stars">
26+
</a>
27+
</div>
28+
29+
## Contents
30+
31+
- [Getting Started](#getting-started)
32+
- [Setup](#setup)
33+
- [Usage](#usage)
34+
- [Best Practices](#security-best-practices)
35+
- [Configuration](#configuration)
36+
- [Endpoints](#endpoints)
37+
- [Variables](#variables)
38+
- [Contributing](#contributing)
39+
- [Support](#support)
40+
- [License](#license)
441

542
## Getting Started
643

44+
> **Prerequisites**: You need Docker and Docker Compose installed.
45+
746
Get the latest version of the `docker-compose.yaml` file:
847

948
```yaml
@@ -45,11 +84,10 @@ networks:
4584
And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens).
4685

4786
> [!IMPORTANT]
48-
> This Documentation will be using `sec-signal-api:8880` as the service host,
49-
> this **is just for simplicty**, instead use your containers or hosts IP + Port.
50-
> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
87+
> In this documentation, we use `sec-signal-api:8880` as the host for simplicity.
88+
> Replace it with your actual container/host IP, port, or hostname.
5189

52-
### Reverse proxy
90+
### Reverse Proxy
5391

5492
Take a look at the [traefik](https://github.com/traefik/traefik) implementation:
5593

@@ -88,7 +126,7 @@ networks:
88126
89127
## Setup
90128
91-
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)
129+
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)
92130
93131
To be able to use the API you have to either:
94132
@@ -98,46 +136,27 @@ OR
98136
99137
- **link Signal API to an already registered Signal Device**
100138
101-
> [!TIP]
102-
> It is advised to do Setup directly with Signal rAPI
103-
> if you try to Setup with Secured Signal API you will be blocked from doing so. See [Blocked Endpoints](#blocked-endpoints).
104-
105-
## Usage
106-
107-
Secured Signal API provides 3 Ways to Authenticate
108-
109-
### Bearer
110-
111-
To Authenticate add `Authorization: Bearer API_TOKEN` to your request Headers
112-
113-
### Basic Auth
114-
115-
To use Basic Auth as Authorization Method add `Authorization: Basic BASE64_STRING` to your Headers
116-
117-
User is `api` (LOWERCASE)
118-
119-
Formatting for `BASE64_STRING` = `user:API_TOKEN`.
139+
1. **Register** or **link** a Signal account with `signal-cli-rest-api`
120140

121-
example:
141+
2. Deploy `secured-signal-api` with at least one API token
122142

123-
```bash
124-
echo "api:API_TOKEN" | base64
125-
```
126-
127-
=> `YXBpOkFQSV9LRVkK`
143+
3. Confirm you can send a test message (see [Usage](#usage))
128144

129-
### Query Auth
145+
> [!TIP]
146+
> Run setup directly with Signal rAPI.
147+
> Setup requests via Secured Signal API are blocked. See [Blocked Endpoints](#blocked-endpoints).
130148

131-
If you are working with a limited Application you may **not** be able to modify Headers or the Request Body
132-
in this case you can use **Query Auth**.
149+
## Usage
133150

134-
Here is a simple example:
151+
Secured Signal API provides 3 Ways to Authenticate
135152

136-
```bash
137-
curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN
138-
```
153+
### Auth
139154

140-
Notice the `@` infront of `authorization`. See [KeyValue Pair Injection](#keyvalue-pair-injection).
155+
| Method | Example |
156+
| :---------- | :--------------------------------------------------------- |
157+
| Bearer Auth | Add `Authorization: Bearer API_TOKEN` to headers |
158+
| Basic Auth | Add `Authorization: Basic BASE64_STRING` (`api:API_TOKEN`) |
159+
| Query Auth | Append `@authorization=API_TOKEN` to request URL |
141160

142161
### Example
143162

@@ -187,6 +206,13 @@ you have to add `@` in front of any KeyValue Pair assignment.
187206
188207
Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type).
189208
209+
## Security: Best Practices
210+
211+
- Always use API tokens in production
212+
- Run behind a TLS-enabled [Reverse Proxy](#reverse-proxy) (Traefik, Nginx, Caddy)
213+
- Be cautious when overriding Blocked Endpoints
214+
- Use per-token overrides to enforce least privilege
215+
190216
## Configuration
191217
192218
There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
@@ -272,8 +298,7 @@ If you are using Environment Variables as an example you won't be able to specif
272298
| array(str) | [a,b,c] |
273299

274300
> [!NOTE]
275-
> 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**.
276-
> **Double Backslashes** do exist but you could just leave them out completly.
301+
> 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).
277302
> An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**.
278303

279304
### API Token(s)
@@ -300,7 +325,7 @@ Since Secured Signal API is just a Proxy you can use all of the [Signal REST API
300325
| :-------------------- | ------------------ |
301326
| **/v1/about** | **/v1/unregister** |
302327
| **/v1/configuration** | **/v1/qrcodelink** |
303-
| **/v1/devives** | **/v1/contacts** |
328+
| **/v1/devices** | **/v1/contacts** |
304329
| **/v1/register** | **/v1/accounts** |
305330

306331
These Endpoints are blocked by default due to Security Risks.
@@ -346,7 +371,10 @@ settings:
346371

347372
### Message Aliases
348373

349-
To improve compatibility with other services Secured Signal API provides aliases for the `message` attribute by default:
374+
To improve compatibility with other services Secured Signal API provides **Message Aliases** for the `message` attribute.
375+
376+
<details>
377+
<summary><strong>Default Message Aliases</strong></summary>
350378

351379
| Alias | Score | Alias | Score |
352380
| ------------ | ----- | ---------------- | ----- |
@@ -358,6 +386,8 @@ To improve compatibility with other services Secured Signal API provides aliases
358386
| details | 14 | body | 2 |
359387
| data.message | 10 | data | 1 |
360388

389+
</details>
390+
361391
Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
362392

363393
Message Aliases can be added by setting `messageAliases` in your config:

0 commit comments

Comments
 (0)