Skip to content

Commit 0d5e641

Browse files
github-actions[bot]github-actions[bot]
committed
Update README.md
1 parent 3da1e52 commit 0d5e641

File tree

1 file changed

+146
-86
lines changed

1 file changed

+146
-86
lines changed

‎README.md‎

Lines changed: 146 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,11 @@
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 REST API</a></h5>
3+
<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal Messenger REST API</a></h5>
44

5-
## Installation
5+
## Getting Started
66

77
Get the latest version of the `docker-compose.yaml` file:
88

9-
And add secure Token(s) to `API_TOKEN` / `API_TOKENS`. See [API_TOKEN(s)](#api-tokens)
10-
11-
> [!IMPORTANT]
12-
> This Documentation will be using `sec-signal-api:8880` as the service host,
13-
> this **won't work**, instead use your containers IP + Port.
14-
> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
15-
169
```yaml
1710
services:
1811
signal-api:
@@ -36,10 +29,10 @@ services:
3629
aliases:
3730
- secured-signal-api
3831
environment:
39-
SIGNAL_API_URL: http://signal-api:8080
40-
DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]'
41-
NUMBER: 123456789
42-
API_TOKEN: LOOOOOONG_STRING
32+
API__URL: http://signal-api:8080
33+
VARIABLES__RECIPIENTS: 000,001,002
34+
VARIABLES__NUMBER: 123456789
35+
API__TOKENS: LOOOOOONG_STRING
4336
ports:
4437
- "8880:8880"
4538
restart: unless-stopped
@@ -48,6 +41,13 @@ networks:
4841
backend:
4942
```
5043
44+
And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens).
45+
46+
> [!IMPORTANT]
47+
> This Documentation will be using `sec-signal-api:8880` as the service host,
48+
> this **is just for simplicty**, instead use your containers or hosts IP + Port.
49+
> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
50+
5151
### Reverse proxy
5252

5353
Take a look at the [traefik](https://github.com/traefik/traefik) implementation:
@@ -63,10 +63,10 @@ services:
6363
aliases:
6464
- secured-signal-api
6565
environment:
66-
SIGNAL_API_URL: http://signal-api:8080
67-
DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]'
66+
API__URL: http://signal-api:8080
67+
DEFAULT_RECIPIENTS: 000,001,002
6868
NUMBER: 123456789
69-
API_TOKEN: LOOOOOONG_STRING
69+
API__TOKENS: LOOOOOONG_STRING
7070
labels:
7171
- traefik.enable=true
7272
- traefik.http.routers.signal-api.rule=Host(`signal-api.mydomain.com`)
@@ -135,7 +135,7 @@ Here is a simple example:
135135
curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN
136136
```
137137

138-
Notice the `@` infront of `authorization`. See [Formatting](#format).
138+
Notice the `@` infront of `authorization`. See [KeyValue Pair Injection](#keyvalue-pair-injection).
139139

140140
### Example
141141

@@ -149,9 +149,7 @@ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_T
149149

150150
#### Placeholders
151151

152-
If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request.
153-
154-
Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}`
152+
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. See [Custom Variables](#variables).
155153

156154
These Placeholders can be used in the Request Query or the Body of a Request like so:
157155

@@ -180,46 +178,118 @@ http://sec-signal-api:8880/v1/receive/{{.NUMBER}}
180178
181179
In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query:
182180
183-
Supported types include **strings**, **ints** and **arrays**
184-
185181
`http://sec-signal-api:8880/?@key=value`
186182
187-
| type | example |
188-
| :--------- | :------ |
189-
| string | abc |
190-
| int | 123 |
191-
| array | [1,2,3] |
192-
| array(int) | 1,2,3 |
193-
| array(str) | a,b,c |
194-
195-
##### Format
196-
197183
In order to differentiate Injection Queries and _regular_ Queries
198184
you have to add `@` in front of any KeyValue Pair assignment.
199185
200-
## Environment Variables
186+
Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type).
187+
188+
## Configuration
189+
190+
There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
191+
192+
### Config Files
193+
194+
Config files allow **YML** formatting and also `${ENV}` to get Environment Variables.
195+
196+
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`)
197+
198+
This example config shows all of the individual settings that can be applied:
199+
200+
```yaml
201+
# Example Config (all configurations shown)
202+
203+
api:
204+
port: 8880
205+
url: http://signal-api:8080
206+
tokens: [token1, token2]
207+
208+
logLevel: INFO
209+
210+
variables:
211+
number: "000"
212+
recipients: ["001", "group.id", "user.id"]
213+
214+
messageAliases: [{ alias: "msg", score: 100 }]
215+
216+
blockedEndpoints:
217+
- /v1/about
218+
```
219+
220+
#### Token Configs
221+
222+
You can also override the `config.yml` file for each individual token by adding configs under `TOKENS_PATH` (default: `config/tokens/`)
223+
224+
This way you can permission tokens by further restricting or adding [Endpoints](#blocked-endpoints), [Placeholders](#variables), etc.
225+
226+
Here is an example:
227+
228+
```yaml
229+
token: LOOOONG_STRING
230+
231+
overrides:
232+
variables: # Disable Placeholder
233+
blockedEndpoints: # Disable Sending
234+
- /v2/send
235+
messageAliases: # Disable Aliases
236+
```
237+
238+
### Environment
239+
240+
Suppose you want to set a new [Placeholder](#placeholders) `NUMBER` in your Environment...
241+
242+
```yaml
243+
environment:
244+
VARIABLES__NUMBER: "000"
245+
```
246+
247+
This would internally be converted into `variables.number` matching the config formatting.
248+
249+
> [!IMPORTANT]
250+
> Underscores `_` are removed during Conversion, Double Underscores `__` on the other hand convert the Variable into a nested Object (`__` replaced by `.`)
251+
252+
### String To Type
253+
254+
> [!TIP]
255+
> This formatting applies to almost every situation where the only (allowed) Input Type is a string and other Output Types are needed.
256+
257+
If you are using Environment Variables as an example you won't be able to specify an Array or a Dictionary of items, in that case you can provide a specifically formatted string which will be translated into the correct type...
258+
259+
| type | example |
260+
| :--------- | :---------------- |
261+
| string | abc |
262+
| string | +123 |
263+
| int | 123 |
264+
| int | -123 |
265+
| json | {"a":"b","c":"d"} |
266+
| array(int) | [1,2,3] |
267+
| array(str) | [a,b,c] |
268+
269+
> [!NOTE]
270+
> 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**.
271+
> **Double Backslashes** do exist but you could just leave them out completly.
272+
> An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**.
201273

202274
### API Token(s)
203275

204-
Both `API_TOKEN` and `API_TOKENS` support multiple Tokens seperated by a `,` **Comma**.
205276
During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.
206277

207278
```yaml
208-
environment:
209-
API_TOKEN: "token1, token2, token3"
210-
API_TOKENS: "token1, token2, token3"
279+
api:
280+
tokens: [token1, token2, token3]
211281
```
212282

213283
> [!IMPORTANT]
214-
> It is highly recommended to set this Environment Variable
284+
> It is highly recommended use API Tokens
215285

216286
> _What if I just don't?_
217287

218288
Secured Signal API will still work, but important Security Features won't be available
219289
like Blocked Endpoints and any sort of Auth.
220290

221291
> [!NOTE]
222-
> Blocked Endpoints can be reactivated by manually setting them in the Environment
292+
> Blocked Endpoints can be reactivated by manually configuring them
223293

224294
### Blocked Endpoints
225295

@@ -236,53 +306,27 @@ Because Secured Signal API is just a Proxy you can use all of the [Signal REST A
236306
| **/v1/accounts** |
237307
| **/v1/contacts** |
238308

239-
These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a Comma seperated List:
309+
These Endpoints are blocked by default due to Security Risks, but can be modified by setting `blockedEndpoints` in your config:
240310

241311
```yaml
242-
environment:
243-
BLOCKED_ENDPOINTS: |
244-
/v1/register,
245-
/v1/unregister,
246-
/v1/qrcodelink,
247-
/v1/contacts,
312+
blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
248313
```
249314

250-
#### Variables
251-
252-
By default Secured Signal API provides the following Placeholders:
253-
254-
- **NUMBER** = _ENV_: `NUMBER`
255-
- **RECIPIENTS** = _ENV_: `RECIPIENTS`
315+
### Variables
256316

257-
### Customization
317+
Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
318+
See [Placeholders](#placeholders).
258319

259-
Placeholders can be added by setting `VARIABLES` inside your Environment.
260-
261-
```yaml
262-
environment:
263-
VARIABLES: |
264-
"NUMBER2": "002",
265-
"GROUP_CHAT_1": [
266-
"user.id", "000", "001", "group.id"
267-
]
268-
```
269-
270-
### Recipients
271-
272-
Set this Environment Variable to automatically provide default Recipients:
320+
> [!NOTE]
321+
> Every Placeholder Key will be converted into an Uppercase String.
322+
> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
273323

274324
```yaml
275-
environment:
276-
RECIPIENTS: |
277-
user.id, 000, 001, group.id,
278-
```
279-
280-
example:
281-
282-
```json
283-
{
284-
"recipients": "{{.RECIPIENTS}}"
285-
}
325+
variables:
326+
number: "001",
327+
recipients: [
328+
"user.id", "000", "001", "group.id"
329+
]
286330
```
287331

288332
### Message Aliases
@@ -303,18 +347,34 @@ To improve compatibility with other services Secured Signal API provides aliases
303347

304348
Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
305349

306-
Message Aliases can be added by setting `MESSAGE_ALIASES` to a valid json array containing dictionaries of `alias`, the json key to be used for lookup (use `.` dots for using values from a nested dictionary and `[i]` to get values from an array):
350+
Message Aliases can be added by setting `messageAliases` in your config:
307351

308352
```yaml
309-
environment:
310-
MESSAGE_ALIASES: |
311-
[
312-
{ "alias": "msg", "score": 80 },
313-
{ "alias": "data.message", "score": 79 },
314-
{ "alias": "array[0].message", "score": 78 },
315-
]
353+
messageAliases:
354+
[
355+
{ alias: "msg", score: 80 },
356+
{ alias: "data.message", score: 79 },
357+
{ alias: "array[0].message", score: 78 },
358+
]
316359
```
317360

361+
### Port
362+
363+
To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)
364+
365+
### Log Level
366+
367+
To change the Log Level set `logLevel` to: (default: `info`)
368+
369+
| Level |
370+
| ------- |
371+
| `info` |
372+
| `debug` |
373+
| `warn` |
374+
| `error` |
375+
| `fatal` |
376+
| `dev` |
377+
318378
## Contributing
319379

320380
Found a bug? Want to change or add something?

0 commit comments

Comments
 (0)