Skip to content

Commit 8fa62b1

Browse files
CodeShellDevCodeShellDev
committed
refresh docs branch
0 parents  commit 8fa62b1

Some content is hidden

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

59 files changed

+23910
-0
lines changed

‎.github/templates/README.template.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
<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/banner.png" />
2+
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+
token-based authentication,
7+
endpoint restrictions, placeholders, 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
17+
src="https://img.shields.io/github/v/release/codeshelldev/secured-signal-api?sort=semver&logo=github&label=Release"
18+
alt="GitHub release"
19+
>
20+
</a>
21+
<a href="https://github.com/codeshelldev/secured-signal-api/stargazers">
22+
<img
23+
src="https://img.shields.io/github/stars/codeshelldev/secured-signal-api?style=flat&logo=github&label=Stars"
24+
alt="GitHub stars"
25+
>
26+
</a>
27+
<a href="https://github.com/codeshelldev/secured-signal-api/pkgs/container/secured-signal-api">
28+
<img
29+
src="https://ghcr-badge.egpl.dev/codeshelldev/secured-signal-api/size?color=%2344cc11&tag=latest&label=Image+Size&trim="
30+
alt="Docker image size"
31+
>
32+
</a>
33+
<a href="https://github.com/codeshelldev/secured-signal-api/pkgs/container/secured-signal-api">
34+
<img
35+
src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr-badge.elias.eu.org%2Fapi%2Fcodeshelldev%2Fsecured-signal-api%2Fsecured-signal-api&query=downloadCount&label=Downloads&color=2344cc11"
36+
alt="Docker image Pulls"
37+
>
38+
</a>
39+
<a href="./LICENSE">
40+
<img
41+
src="https://img.shields.io/badge/License-MIT-green.svg"
42+
alt="License: MIT"
43+
>
44+
</a>
45+
</div>
46+
47+
## Contents
48+
49+
- [Documentation](https://codeshelldev.github.io/secured-signal-api/docs)
50+
- [Getting Started](#getting-started)
51+
- [Setup](#setup)
52+
- [Usage](#usage)
53+
- [Configuration](#configuration)
54+
- [Endpoints](#endpoints)
55+
- [Variables](#variables)
56+
- [Data Aliases](#data-aliases)
57+
- [Message Templates](#message-templates)
58+
- [Contributing](#contributing)
59+
- [Support](#support)
60+
- [Help](#help)
61+
- [License](#license)
62+
63+
## Getting Started
64+
65+
> **Prerequisites**: You need Docker and Docker Compose installed.
66+
67+
Get the latest version of the `docker-compose.yaml` file:
68+
69+
```yaml
70+
{{{ #://docs-src/getting-started/examples/docker-compose.yaml }}}
71+
```
72+
73+
And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens).
74+
75+
> [!IMPORTANT]
76+
> In this documentation, we use `sec-signal-api:8880` as the host for simplicity.
77+
> Replace it with your actual container/host IP, port, or hostname.
78+
79+
## Setup
80+
81+
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)
82+
83+
1. **Register** or **link** a Signal account with `signal-cli-rest-api`
84+
85+
2. Deploy `secured-signal-api` with at least one API token
86+
87+
3. Confirm you can send a test message (see [Usage](#usage))
88+
89+
> [!TIP]
90+
> Run setup directly with Signal rAPI.
91+
> Setup requests via Secured Signal API are blocked. See [Blocked Endpoints](#endpoints).
92+
93+
## Usage
94+
95+
Secured Signal API provides 3 Ways to Authenticate
96+
97+
### Auth
98+
99+
| Method | Example |
100+
| :---------- | :--------------------------------------------------------- |
101+
| Bearer Auth | Add `Authorization: Bearer API_TOKEN` to headers |
102+
| Basic Auth | Add `Authorization: Basic BASE64_STRING` (`api:API_TOKEN`) |
103+
| Query Auth | Append `@authorization=API_TOKEN` to request URL |
104+
105+
### Example
106+
107+
To send a message to `+123400002`:
108+
109+
```bash
110+
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"message": "Hello World!", "recipients": ["+123400002"]}' http://sec-signal-api:8880/v2/send
111+
```
112+
113+
### Advanced
114+
115+
#### Placeholders
116+
117+
If you are not comfortable / don't want to hardcode your Number for example and/or Recipients in you, may use **Placeholders** in your Request.
118+
119+
**How to use:**
120+
121+
| Type | Example | Note |
122+
| :--------------------- | :------------------ | :--------------- |
123+
| Body | `{{@data.key}}` | |
124+
| Header | `{{#Content_Type}}` | `-` becomes `_` |
125+
| [Variable](#variables) | `{{.VAR}}` | always uppercase |
126+
127+
**Where to use:**
128+
129+
| Type | Example |
130+
| :---- | :--------------------------------------------------------------- |
131+
| Body | `{"number": "{{ .NUMBER }}", "recipients": "{{ .RECIPIENTS }}"}` |
132+
| Query | `http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}` |
133+
| Path | `http://sec-signal-api:8880/v1/receive/{{.NUMBER}}` |
134+
135+
You can also combine them:
136+
137+
```json
138+
{
139+
"content": "{{.NUMBER}} -> {{.RECIPIENTS}}"
140+
}
141+
```
142+
143+
#### KeyValue Pair Injection
144+
145+
In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query:
146+
147+
`http://sec-signal-api:8880/?@key=value`
148+
149+
In order to differentiate Injection Queries and _regular_ Queries
150+
you have to add `@` in front of any KeyValue Pair assignment.
151+
152+
Supported types include **strings**, **ints**, **arrays** and **json dictionaries**. See [Formatting](https://codeshelldev.github.io/secured-signal-api/docs/usage/formatting).
153+
154+
## Configuration
155+
156+
There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
157+
158+
### Config Files
159+
160+
Config files allow **YML** formatting and also `${ENV}` to get Environment Variables.
161+
162+
To change the internal config file location set `CONFIG_PATH` in your **Environment** to an absolute path including the filename.extension. (default: `/config/config.yml`)
163+
164+
This example config shows all of the individual settings that can be applied:
165+
166+
```yaml
167+
{{{ #://docs-src/configuration/examples/config.yml }}}
168+
```
169+
170+
#### Token Configs
171+
172+
You can also override the `config.yml` file for each individual token by adding configs under `TOKENS_PATH` (default: `config/tokens/`)
173+
174+
This way you can permission tokens by further restricting or adding [Endpoints](#endpoints), [Placeholders](#variables), etc.
175+
176+
Here is an example:
177+
178+
```yaml
179+
{{{ #://docs-src/configuration/examples/token.yml }}}
180+
```
181+
182+
### Templating
183+
184+
Secured Signal API uses Golang's [Standard Templating Library](https://pkg.go.dev/text/template).
185+
This means that any valid Go template string will also work in Secured Signal API.
186+
187+
Go's templating library is used in the following features:
188+
189+
- [Message Templates](#message-templates)
190+
- [Placeholders](#placeholders)
191+
192+
This makes advanced [Message Templates](#message-templates) like this one possible:
193+
194+
```yaml
195+
{{{ #://docs-src/configuration/examples/message-template.yml }}}
196+
```
197+
198+
### API Tokens
199+
200+
During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.
201+
202+
```yaml
203+
api:
204+
tokens: [token1, token2, token3]
205+
```
206+
207+
> [!IMPORTANT]
208+
> Using API Tokens is highly recommended, but not mandatory.
209+
> Some important Security Features won't be available (like default Blocked Endpoints).
210+
211+
> [!NOTE]
212+
> Blocked Endpoints can be reactivated by manually configuring them
213+
214+
### Endpoints
215+
216+
Since Secured Signal API is just a Proxy you can use all of the [Signal REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) endpoints except for...
217+
218+
| Endpoint | |
219+
| :-------------------- | ------------------ |
220+
| **/v1/about** | **/v1/unregister** |
221+
| **/v1/configuration** | **/v1/qrcodelink** |
222+
| **/v1/devices** | **/v1/contacts** |
223+
| **/v1/register** | **/v1/accounts** |
224+
225+
These Endpoints are blocked by default due to Security Risks.
226+
227+
> [!NOTE]
228+
> Matching works by checking if the requested Endpoints starts with a Blocked or an Allowed Endpoint
229+
230+
You can modify Blocked Endpoints by configuring `blockedEndpoints` in your config:
231+
232+
```yaml
233+
settings:
234+
blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
235+
```
236+
237+
You can also override Blocked Endpoints by adding Allowed Endpoints to `allowedEndpoints`.
238+
239+
```yaml
240+
settings:
241+
allowedEndpoints: [/v2/send]
242+
```
243+
244+
| Config (Allow) | (Block) | Result | | | |
245+
| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- |
246+
| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
247+
| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 |
248+
| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |
249+
250+
### Variables
251+
252+
Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
253+
See [Placeholders](#placeholders).
254+
255+
> [!NOTE]
256+
> Every Placeholder Key will be converted into an Uppercase String.
257+
> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
258+
259+
```yaml
260+
settings:
261+
variables:
262+
number: "+123400001",
263+
recipients: ["+123400002", "group.id", "user.id"]
264+
```
265+
266+
### Message Templates
267+
268+
To customize the `message` attribute you can use **Message Templates** to build your message by using other Body Keys and Variables.
269+
Use `messageTemplate` to configure:
270+
271+
```yaml
272+
settings:
273+
messageTemplate: |
274+
Your Message:
275+
{{@message}}.
276+
Sent with Secured Signal API.
277+
```
278+
279+
Message Templates support [Standard Golang Templating](#templating).
280+
Use `@data.key` to reference Body Keys, `#Content_Type` for Headers and `.KEY` for Variables.
281+
282+
### Data Aliases
283+
284+
To improve compatibility with other services Secured Signal API provides **Data Aliases** and a built-in `message` Alias.
285+
286+
<details>
287+
<summary><strong>Default `message` Aliases</strong></summary>
288+
289+
| Alias | Score | Alias | Score |
290+
| ------------ | ----- | ---------------- | ----- |
291+
| msg | 100 | data.content | 9 |
292+
| content | 99 | data.description | 8 |
293+
| description | 98 | data.text | 7 |
294+
| text | 20 | data.summary | 6 |
295+
| summary | 15 | data.details | 5 |
296+
| details | 14 | body | 2 |
297+
| data.message | 10 | data | 1 |
298+
299+
</details>
300+
301+
Secured Signal API will pick the best scoring Data Alias (if available) to extract set the Key to the correct Value from the Request Body.
302+
303+
Data Aliases can be added by setting `dataAliases` in your config:
304+
305+
```yaml
306+
settings:
307+
dataAliases:
308+
"@message":
309+
[
310+
{ alias: "msg", score: 80 },
311+
{ alias: "data.message", score: 79 },
312+
{ alias: "array[0].message", score: 78 },
313+
]
314+
".NUMBER": [{ alias: "phone_number", score: 100 }]
315+
```
316+
317+
Use `@` for aliasing Body Keys and `.` for aliasing Variables.
318+
319+
## Contributing
320+
321+
Found a bug? Want to change or add something?
322+
Feel free to open up an [Issue](https://github.com/codeshelldev/secured-signal-api/issues) or create a [Pull Request](https://github.com/codeshelldev/secured-signal-api/pulls)!
323+
324+
## Support
325+
326+
Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project.
327+
328+
:)
329+
330+
## Help
331+
332+
**Are you having Problems setting up Secured Signal API?**<br>
333+
No worries check out the [Discussions](https://github.com/codeshelldev/secured-signal-api/discussions) Tab and ask for help.
334+
335+
**We are all Volunteers**, so please be friendly and patient.
336+
337+
## License
338+
339+
[MIT](https://choosealicense.com/licenses/mit/)
340+
341+
## Legal
342+
343+
Logo designed by [@CodeShellDev](https://github.com/codeshelldev), All Rights Reserved.
344+
345+
This Project is not affiliated with the Signal Foundation.

‎.github/workflows/docs-deploy.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- docs-build
7+
paths:
8+
- docs/**
9+
- src/**
10+
workflow_dispatch:
11+
12+
jobs:
13+
docs:
14+
uses: codeshelldev/gh-actions/.github/workflows/docs-deploy.yml@main
15+
name: Deploy
16+
with:
17+
branch: docs-build
18+
secrets:
19+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/docs-update.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Update Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- docs
7+
paths:
8+
- docs/**
9+
workflow_dispatch:
10+
11+
jobs:
12+
docs:
13+
uses: codeshelldev/gh-actions/.github/workflows/docs-update.yml@main
14+
name: Template Docs
15+
with:
16+
template-path: docs/
17+
output-path: docs/
18+
secrets:
19+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

0 commit comments

Comments
 (0)