Skip to content

Commit be1f159

Browse files
CodeShellDevCodeShellDev
authored
Merge branch 'main' into dev
2 parents 2408310 + 8e64a6f commit be1f159

File tree

2 files changed

+175
-84
lines changed

2 files changed

+175
-84
lines changed

‎.github/workflows/image-cleanup.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
name: Cleanup Untagged Images
2+
3+
on:
4+
workflow_dispatch:
5+
release:
6+
types: [published]
7+
8+
jobs:
9+
update:
10+
uses: codeshelldev/gh-actions/.github/workflows/image-cleanup.yml@main
11+
with:
12+
registry: ghcr.io
13+
secrets:
14+
GH_PCKG_TOKEN: ${{ secrets.GH_PCKG_TOKEN }}

‎README.md‎

Lines changed: 161 additions & 84 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" ]'
68-
NUMBER: 123456789
69-
API_TOKEN: LOOOOOONG_STRING
66+
API__URL: http://signal-api:8080
67+
VARIABLES__RECIPIENTS: '[000,001,002]'
68+
VARIABLES__NUMBER: 123456789
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,48 +178,122 @@ 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+
allowedEndpoints:
219+
- /v2/send
220+
```
221+
222+
#### Token Configs
223+
224+
You can also override the `config.yml` file for each individual token by adding configs under `TOKENS_PATH` (default: `config/tokens/`)
225+
226+
This way you can permission tokens by further restricting or adding [Endpoints](#blocked-endpoints), [Placeholders](#variables), etc.
227+
228+
Here is an example:
229+
230+
```yaml
231+
tokens: [LOOOONG_STRING]
232+
233+
overrides:
234+
variables: # Disable Placeholder
235+
blockedEndpoints: # Disable Sending
236+
- /v2/send
237+
messageAliases: # Disable Aliases
238+
```
239+
240+
### Environment
241+
242+
Suppose you want to set a new [Placeholder](#placeholders) `NUMBER` in your Environment...
243+
244+
```yaml
245+
environment:
246+
VARIABLES__NUMBER: "000"
247+
```
248+
249+
This would internally be converted into `variables.number` matching the config formatting.
250+
251+
> [!IMPORTANT]
252+
> Underscores `_` are removed during Conversion, Double Underscores `__` on the other hand convert the Variable into a nested Object (`__` replaced by `.`)
253+
254+
### String To Type
255+
256+
> [!TIP]
257+
> This formatting applies to almost every situation where the only (allowed) Input Type is a string and other Output Types are needed.
258+
259+
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...
260+
261+
| type | example |
262+
| :--------- | :---------------- |
263+
| string | abc |
264+
| string | +123 |
265+
| int | 123 |
266+
| int | -123 |
267+
| json | {"a":"b","c":"d"} |
268+
| array(int) | [1,2,3] |
269+
| array(str) | [a,b,c] |
270+
271+
> [!NOTE]
272+
> 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**.
273+
> **Double Backslashes** do exist but you could just leave them out completly.
274+
> An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**.
201275

202276
### API Token(s)
203277

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

207280
```yaml
208-
environment:
209-
API_TOKEN: "token1, token2, token3"
210-
API_TOKENS: "token1, token2, token3"
281+
api:
282+
tokens: [token1, token2, token3]
211283
```
212284

213285
> [!IMPORTANT]
214-
> It is highly recommended to set this Environment Variable
286+
> It is highly recommended use API Tokens
215287

216288
> _What if I just don't?_
217289

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

221293
> [!NOTE]
222-
> Blocked Endpoints can be reactivated by manually setting them in the Environment
294+
> Blocked Endpoints can be reactivated by manually configuring them
223295

224-
### Blocked Endpoints
296+
### Endpoints
225297

226298
Because 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...
227299

@@ -236,53 +308,42 @@ Because Secured Signal API is just a Proxy you can use all of the [Signal REST A
236308
| **/v1/accounts** |
237309
| **/v1/contacts** |
238310

239-
These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a Comma seperated List:
311+
> [!NOTE]
312+
> Matching works by checking if the requested Endpoints startswith a Blocked or Allowed Endpoint
313+
314+
These Endpoints are blocked by default due to Security Risks, but can be modified by setting `blockedEndpoints` in your config:
240315

241316
```yaml
242-
environment:
243-
BLOCKED_ENDPOINTS: |
244-
/v1/register,
245-
/v1/unregister,
246-
/v1/qrcodelink,
247-
/v1/contacts,
317+
blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
248318
```
249319

250-
#### Variables
251-
252-
By default Secured Signal API provides the following Placeholders:
320+
Override Blocked Endpoints by explicitly allowing endpoints in `allowedEndpoints`.
253321

254-
- **NUMBER** = _ENV_: `NUMBER`
255-
- **RECIPIENTS** = _ENV_: `RECIPIENTS`
256-
257-
### Customization
258-
259-
Placeholders can be added by setting `VARIABLES` inside your Environment.
322+
| Config (Allow) | (Block) | Result | | | |
323+
| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- |
324+
| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
325+
| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 |
326+
| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |
260327

261328
```yaml
262-
environment:
263-
VARIABLES: |
264-
"NUMBER2": "002",
265-
"GROUP_CHAT_1": [
266-
"user.id", "000", "001", "group.id"
267-
]
329+
allowedEndpoints: [/v2/send]
268330
```
269331

270-
### Recipients
332+
### Variables
271333

272-
Set this Environment Variable to automatically provide default Recipients:
273-
274-
```yaml
275-
environment:
276-
RECIPIENTS: |
277-
user.id, 000, 001, group.id,
278-
```
334+
Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
335+
See [Placeholders](#placeholders).
279336

280-
example:
337+
> [!NOTE]
338+
> Every Placeholder Key will be converted into an Uppercase String.
339+
> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
281340

282-
```json
283-
{
284-
"recipients": "{{.RECIPIENTS}}"
285-
}
341+
```yaml
342+
variables:
343+
number: "001",
344+
recipients: [
345+
"user.id", "000", "001", "group.id"
346+
]
286347
```
287348

288349
### Message Aliases
@@ -303,18 +364,34 @@ To improve compatibility with other services Secured Signal API provides aliases
303364

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

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):
367+
Message Aliases can be added by setting `messageAliases` in your config:
307368

308369
```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-
]
370+
messageAliases:
371+
[
372+
{ alias: "msg", score: 80 },
373+
{ alias: "data.message", score: 79 },
374+
{ alias: "array[0].message", score: 78 },
375+
]
316376
```
317377

378+
### Port
379+
380+
To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)
381+
382+
### Log Level
383+
384+
To change the Log Level set `logLevel` to: (default: `info`)
385+
386+
| Level |
387+
| ------- |
388+
| `info` |
389+
| `debug` |
390+
| `warn` |
391+
| `error` |
392+
| `fatal` |
393+
| `dev` |
394+
318395
## Contributing
319396

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

0 commit comments

Comments
 (0)