Skip to content

Commit 0ea656a

Browse files
CodeShellDevCodeShellDev
authored
[v1.5.0] Docs Release (#233)
1 parent fb82725 commit 0ea656a

58 files changed

Lines changed: 1831 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎versioned_docs/version-v1.5/about.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
sidebar_position: 1
3+
title: About
4+
---
5+
6+
# About
7+
8+
**Secured Signal API** is a secure, configurable proxy for [Signal CLI REST API](https://github.com/bbernhard/signal-cli-rest-api).
9+
It does **not** replace or modify the original API — it sits in front of it, adding a layer of control, authentication, and flexibility for production use.
10+
11+
## What it Is
12+
13+
The [Signal CLI REST API](https://github.com/bbernhard/signal-cli-rest-api) provides a robust HTTP interface to the Signal Messenger service.
14+
**Secured Signal API** works as a **reverse proxy**, forwarding approved requests to your existing Signal CLI REST API instance, while managing access and configuration.
15+
16+
It's designed for developers who want to:
17+
18+
- **Restrict** or **log** certain API calls
19+
- Enforce **authentication**
20+
- Add **templating** or **request preprocessing**
21+
- And deploy everything neatly via **Docker**
22+
23+
## Key Features
24+
25+
- 🔒 **Access Control** — Protect your Signal API with [**token-based authentication**](./usage#auth), [**endpoint restrictions**](./features#endpoints) and [**IP filters**](./features#ip-filter).
26+
- 🧩 **Full Compatibility** — 100% protocol-compatible; all requests are still handled by your existing Signal CLI REST API.
27+
- ⚙️ **Configurable Proxy Behavior** — Define templates and limits via YAML or environment variables.
28+
- 🧠 **Message Templates** — Use [**variables**](./configuration/variables) and [**placeholders**](./features#placeholders) to standardize common message formats.
29+
- 🐳 **Docker-Ready** — Comes packaged for containerized environments, deployable in seconds.
30+
- [And much more…](./features)
31+
32+
## Architecture
33+
34+
Secured Signal API acts purely as a **gateway** — it never bypasses or replaces your existing Signal CLI REST API:
35+
36+
```mermaid
37+
flowchart TD
38+
A[Client App / Script]
39+
B[TLS Reverse Proxy]
40+
C[Secured Signal API]
41+
D[Signal CLI REST API]
42+
E[Signal Servers]
43+
44+
A -. HTTP Request .-> B
45+
B -. HTTPS .-> C
46+
C -- Forwarded Request --> D
47+
D -. Encrypted Signal .-> E
48+
49+
classDef gateway fill:#1e3a8a,stroke:#93c5fd,stroke-width:1.5px,color:#ffffff;
50+
class C gateway;
51+
52+
classDef external fill:#374151,stroke:#9ca3af,stroke-width:1.5px,color:#ffffff;
53+
class A,E external;
54+
```

‎versioned_docs/version-v1.5/best-practices/best-practices.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
sidebar_position: 5
3+
title: Best Practices
4+
---
5+
6+
# Best Practices
7+
8+
Here are some common best practices for running **Secured Signal API**, but these generally apply for any service.
9+
10+
## Usage
11+
12+
- Create **separate configs** for each service
13+
- Use [**placeholders**](./usage/advanced#placeholders) extensively
14+
- Always keep your stack **up-to-date**
15+
16+
## Security
17+
18+
- Always use **API tokens** in production
19+
- Run behind a [**tls-enabled reverse proxy**](./reverse-proxy)
20+
- Be cautious when overriding [**blocked endpoints**](./features#endpoints)
21+
- Use per-token overrides to **enforce least privilege**
22+
- Always allow the least possible [**endpoints**](./features#endpoints)
23+
- Only allow access from [**IPs**](./features#ip-filter) **you trust**

‎versioned_docs/version-v1.5/configuration/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Configuration",
3+
"position": 5
4+
}

‎versioned_docs/version-v1.5/configuration/api-tokens.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: API Tokens
3+
---
4+
5+
# API Tokens
6+
7+
> [!IMPORTANT]
8+
> Using API tokens is highly **recommended**, but not mandatory.
9+
> Some important Security Features won't be available (for example the default [blocked endpoints](./endpoints#default))
10+
11+
Define API tokens for accessing **Secured Signal API**.
12+
13+
```yaml
14+
api:
15+
tokens: [token1, token2, token3]
16+
```
17+
18+
See [Auth](./auth) for possible auth methods and how to activate additional ones.
19+
20+
> [!NOTE]
21+
> Blocked endpoints can be reactivated by manually configuring them

‎versioned_docs/version-v1.5/configuration/auth.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Auth
3+
---
4+
5+
# Auth
6+
7+
The `auth` setting under `api` is used for configuring auth methods and setting API tokens.
8+
(default methods: `bearer, basic, body`)
9+
10+
**Example:**
11+
12+
```yaml
13+
api:
14+
auth:
15+
methods: [query, path]
16+
tokens:
17+
- set: [token4, token5]
18+
methods: [body]
19+
```
20+
21+
In the example above **Query** and **Path** auth have been enabled in favor of **Bearer**, **Basic** and **Body** auth.
22+
This applies to any token defined in [`api.tokens`](./api-tokens), <br/>`token4` and `token5` on the other hand only allow for being used with **Body** auth.

‎versioned_docs/version-v1.5/configuration/endpoints.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Endpoints
3+
---
4+
5+
# Endpoints
6+
7+
Restrict access to your **Secured Signal API**.
8+
9+
## Default
10+
11+
Secured Signal API is just a proxy, which means any and all the **Signal CLI REST API** **endpoints are available**,
12+
because of security concerns the following endpoints are blocked:
13+
14+
| Endpoint | |
15+
| :-------------------- | ------------------ |
16+
| **/v1/configuration** | **/v1/unregister** |
17+
| **/v1/devices** | **/v1/contacts** |
18+
| **/v1/register** | **/v1/accounts** |
19+
| **/v1/qrcodelink** | |
20+
21+
## Customize
22+
23+
> [!IMPORTANT]
24+
>
25+
> 1. Matching uses [regex](https://regex101.com)
26+
> 2. On compile error exact match is used instead
27+
28+
You can modify endpoints by configuring `access.endpoints` in your config:
29+
30+
```yaml
31+
settings:
32+
access:
33+
endpoints:
34+
- "!/v1/register"
35+
- "!/v1/unregister"
36+
- "!/v1/qrcodelink"
37+
- "!/v1/contacts"
38+
- /v2/send
39+
```
40+
41+
By default, adding an endpoint explicitly allows access to it, use `!` to block it instead.
42+
43+
> [!NOTE]
44+
> When using `!` to block you must enclose the endpoint in quotes, like in the example above
45+
46+
## Behavior
47+
48+
| Allow | Block | Result |
49+
| ---------- | -------------- | ----------------------------------------- |
50+
| `/v2/send` | — | **Only** `/v2/send` allowed |
51+
| — | `!/v1/receive` | **All** allowed, **except** `/v1/receive` |
52+
| `/v2/send` | `!/v2/.*` | **Only** `/v2/send` allowed |
53+
54+
### Rules
55+
56+
- Default: **allow all**
57+
- Allow rules exist: default **block**
58+
- Only block rules exist: default **allow**
59+
- Explicit allow **overrides** block

‎versioned_docs/version-v1.5/configuration/examples/config.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Example Config (all configurations shown)
2+
service:
3+
logLevel: info
4+
port: 8880
5+
hostnames:
6+
- mydomain.com
7+
8+
api:
9+
url: http://signal-api:8080
10+
tokens: [token1, token2]
11+
auth:
12+
methods: [bearer, basic, body]
13+
tokens:
14+
- set: [pathToken1, pathToken2]
15+
methods: [path]
16+
- set: [queryAndBodyToken]
17+
methods: [body, query]
18+
19+
settings:
20+
message:
21+
template: |
22+
You've got a Notification:
23+
{{@message}}
24+
At {{@data.timestamp}} on {{@data.date}}.
25+
Send using {{.NUMBER}}.
26+
27+
variables:
28+
number: "+123400001"
29+
recipients: ["+123400002", "group.id", "user.id"]
30+
31+
fieldMappings:
32+
"@message": [{ field: "msg", score: 100 }]
33+
34+
access:
35+
trustedIPs:
36+
- 192.168.1.10
37+
38+
trustedProxies:
39+
- 172.20.0.100
40+
41+
ipFilter:
42+
- 192.168.1.10
43+
- 192.168.2.0/24
44+
- "!192.168.2.44"
45+
46+
endpoints:
47+
- "!/v1/about"
48+
- /v2/send
49+
50+
rateLimiting:
51+
limit: 100
52+
period: 1h
53+
54+
fieldPolicies:
55+
"@number":
56+
- value: "+123400003"
57+
action: block
58+
- value: "+123400004"
59+
action: block

‎versioned_docs/version-v1.5/configuration/examples/message-template.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
settings:
2+
message:
3+
template: |
4+
{{- $greeting := "Hello" -}}
5+
{{ $greeting }}, {{ @name }}!
6+
{{ if @age -}}
7+
You are {{ @age }} years old.
8+
{{- else -}}
9+
Age unknown.
10+
{{- end }}
11+
Your friends:
12+
{{- range @friends }}
13+
- {{ . }}
14+
{{- else }}
15+
You have no friends.
16+
{{- end }}
17+
Profile details:
18+
{{- range $key, $value := @profile }}
19+
- {{ $key }}: {{ $value }}
20+
{{- end }}
21+
{{ define "footer" -}}
22+
This is the footer for {{ @name }}.
23+
{{- end }}
24+
{{ template "footer" . -}}
25+
------------------------------------
26+
Content-Type: {{ #Content_Type }}
27+
Redacted Auth Header: {{ #Authorization }}

‎versioned_docs/version-v1.5/configuration/examples/token.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Example Token Config (overwrites)
2+
service:
3+
logLevel: info
4+
port: 8880
5+
hostnames:
6+
- mydomain.com
7+
8+
api:
9+
tokens: [token1, token2]
10+
auth:
11+
methods: [bearer, basic, body, path] # add path auth
12+
13+
settings:
14+
message:
15+
template: # disable
16+
variables: # overwrite main config variables
17+
number: "+123400010"
18+
recipients: ["+123400020", "group.id", "user.id"]
19+
20+
fieldMappings: # overwrite @message from main config
21+
"@message": [{ field: "msg", score: 100 }]
22+
23+
access:
24+
trustedIPs: # disable
25+
trustedProxies: # disable
26+
ipFilter: # disable
27+
28+
endpoints: # overwrite main config endpoints
29+
- "!/v1/about"
30+
- /v1/receive
31+
- /v2/send
32+
33+
rateLimiting:
34+
limit: 100
35+
period: 10h # overwrite main config period
36+
37+
fieldPolicies: # disable

‎versioned_docs/version-v1.5/configuration/field-mappings.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Field Mappings
3+
---
4+
5+
# Field Mappings
6+
7+
A compatibility layer for **Secured Signal API**.
8+
9+
To improve compatibility with other services Secured Signal API provides **Field Mappings** and even a built-in `message` mapping.
10+
11+
<details>
12+
<summary><strong>Default `message` mapping</strong></summary>
13+
14+
| Field | Score | Field | Score |
15+
| ------------ | ----- | ---------------- | ----- |
16+
| msg | 100 | data.content | 9 |
17+
| content | 99 | data.description | 8 |
18+
| description | 98 | data.text | 7 |
19+
| text | 20 | data.summary | 6 |
20+
| summary | 15 | data.details | 5 |
21+
| details | 14 | body | 2 |
22+
| data.message | 10 | data | 1 |
23+
24+
</details>
25+
26+
Secured Signal API will pick the highest scoring field (if available) to set the key to the correct value **using the request body**.
27+
28+
Field Mappings can be added by setting `message.fieldMappings` in your config:
29+
30+
```yaml
31+
settings:
32+
message:
33+
fieldMappings:
34+
"@message":
35+
[
36+
{ field: "msg", score: 80 },
37+
{ field: "data.message", score: 79 },
38+
{ field: "array[0].message", score: 78 },
39+
]
40+
".NUMBER": [{ field: "phone_number", score: 100 }]
41+
```
42+
43+
> [!NOTE]
44+
> Supported [placeholder types](../usage/advanced#placeholders):
45+
>
46+
> | `.` Variables | `@` Body | `#` Headers |
47+
> | ------------- | -------- | ----------- |
48+
> | ✅ | ✅ | ❌ |

0 commit comments

Comments
 (0)