v1.2.0

Update Main for New Release

Author: CodeShellDev

.dockerignore

@@ -3,3 +3,4 @@
 .github
 *.yaml
 *.md
+!config/*.yml

.github/templates/README.template.md

@@ -1,22 +1,22 @@
 <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" />
 
-<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal REST API</a></h5>
+<h5 align="center">Secure Proxy for <a href="https://github.com/bbernhard/signal-cli-rest-api">Signal Messenger REST API</a></h5>
 
-## Installation
+## Getting Started
 
 Get the latest version of the `docker-compose.yaml` file:
 
-And add secure Token(s) to `API_TOKEN` / `API_TOKENS`. See [API_TOKEN(s)](#api-tokens)
+```yaml
+{ { file.docker-compose.yaml } }
+```
+
+And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens).
 
 > [!IMPORTANT]
 > This Documentation will be using `sec-signal-api:8880` as the service host,
-> this **won't work**, instead use your containers IP + Port.
+> this **is just for simplicty**, instead use your containers or hosts IP + Port.
 > Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
 
-```yaml
-{ { file.docker-compose.yaml } }
-```
-
 ### Reverse proxy
 
 Take a look at the [traefik](https://github.com/traefik/traefik) implementation:
@@ -76,7 +76,7 @@ Here is a simple example:
 curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN
 ```
 
-Notice the `@` infront of `authorization`. See [Formatting](#format).
+Notice the `@` infront of `authorization`. See [KeyValue Pair Injection](#keyvalue-pair-injection).
 
 ### Example
 
@@ -90,9 +90,7 @@ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_T
 
 #### Placeholders
 
-If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request.
-
-Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}`
+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).
 
 These Placeholders can be used in the Request Query or the Body of a Request like so:
 
@@ -121,46 +119,96 @@ http://sec-signal-api:8880/v1/receive/{{.NUMBER}}
 
 In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query:
 
-Supported types include **strings**, **ints** and **arrays**
-
 `http://sec-signal-api:8880/?@key=value`
 
-| type       | example |
-| :--------- | :------ |
-| string     | abc     |
-| int        | 123     |
-| array      | [1,2,3] |
-| array(int) | 1,2,3   |
-| array(str) | a,b,c   |
-
-##### Format
-
 In order to differentiate Injection Queries and _regular_ Queries
 you have to add `@` in front of any KeyValue Pair assignment.
 
-## Environment Variables
+Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type).
+
+## Configuration
+
+There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
+
+### Config Files
+
+Config files allow **YML** formatting and also `${ENV}` to get Environment Variables.
+
+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`)
+
+This example config shows all of the individual settings that can be applied:
+
+```yaml
+{ { file.examples/config.yml } }
+```
+
+#### Token Configs
+
+You can also override the `config.yml` file for each individual token by adding configs under `TOKENS_PATH` (default: `config/tokens/`)
+
+This way you can permission tokens by further restricting or adding [Endpoints](#blocked-endpoints), [Placeholders](#variables), etc.
+
+Here is an example:
+
+```yaml
+{ { file.examples/token.yml } }
+```
+
+### Environment
+
+Suppose you want to set a new [Placeholder](#placeholders) `NUMBER` in your Environment...
+
+```yaml
+environment:
+  VARIABLES__NUMBER: "000"
+```
+
+This would internally be converted into `variables.number` matching the config formatting.
+
+> [!IMPORTANT]
+> Underscores `_` are removed during Conversion, Double Underscores `__` on the other hand convert the Variable into a nested Object (`__` replaced by `.`)
+
+### String To Type
+
+> [!TIP]
+> This formatting applies to almost every situation where the only (allowed) Input Type is a string and other Output Types are needed.
+
+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...
+
+| type       | example           |
+| :--------- | :---------------- |
+| string     | abc               |
+| string     | +123              |
+| int        | 123               |
+| int        | -123              |
+| json       | {"a":"b","c":"d"} |
+| array(int) | [1,2,3]           |
+| array(str) | [a,b,c]           |
+
+> [!NOTE]
+> 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**.
+> **Double Backslashes** do exist but you could just leave them out completly.
+> An **Odd** number of **Backslashes** **escape** the character in front of them and an **Even** number leave the character **as-is**.
 
 ### API Token(s)
 
-Both `API_TOKEN` and `API_TOKENS` support multiple Tokens seperated by a `,` **Comma**.
 During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.
 
 ```yaml
-environment:
-  API_TOKEN: "token1, token2, token3"
-  API_TOKENS: "token1, token2, token3"
+api:
+  tokens: [token1, token2, token3]
 ```
 
 > [!IMPORTANT]
-> It is highly recommended to set this Environment Variable
+> It is highly recommended use API Tokens
 
 > _What if I just don't?_
 
 Secured Signal API will still work, but important Security Features won't be available
 like Blocked Endpoints and any sort of Auth.
 
 > [!NOTE]
-> Blocked Endpoints can be reactivated by manually setting them in the Environment
+> Blocked Endpoints can be reactivated by manually configuring them
 
 ### Blocked Endpoints
 
@@ -177,53 +225,27 @@ Because Secured Signal API is just a Proxy you can use all of the [Signal REST A
 | **/v1/accounts**      |
 | **/v1/contacts**      |
 
-These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a Comma seperated List:
+These Endpoints are blocked by default due to Security Risks, but can be modified by setting `blockedEndpoints` in your config:
 
 ```yaml
-environment:
-  BLOCKED_ENDPOINTS: |
-    /v1/register,
-    /v1/unregister,
-    /v1/qrcodelink,
-    /v1/contacts,
+blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
 ```
 
-#### Variables
-
-By default Secured Signal API provides the following Placeholders:
-
-- **NUMBER** = _ENV_: `NUMBER`
-- **RECIPIENTS** = _ENV_: `RECIPIENTS`
-
-### Customization
-
-Placeholders can be added by setting `VARIABLES` inside your Environment.
-
-```yaml
-environment:
-  VARIABLES: |
-    "NUMBER2": "002",
-    "GROUP_CHAT_1": [
-      "user.id", "000", "001", "group.id"
-    ]
-```
+### Variables
 
-### Recipients
+Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
+See [Placeholders](#placeholders).
 
-Set this Environment Variable to automatically provide default Recipients:
+> [!NOTE]
+> Every Placeholder Key will be converted into an Uppercase String.
+> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
 
 ```yaml
-environment:
-  RECIPIENTS: |
-    user.id, 000, 001, group.id,
-```
-
-example:
-
-```json
-{
-	"recipients": "{{.RECIPIENTS}}"
-}
+variables:
+  number: "001",
+  recipients: [
+    "user.id", "000", "001", "group.id"
+  ]
 ```
 
 ### Message Aliases
@@ -244,18 +266,34 @@ To improve compatibility with other services Secured Signal API provides aliases
 
 Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
 
-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):
+Message Aliases can be added by setting `messageAliases` in your config:
 
 ```yaml
-environment:
-  MESSAGE_ALIASES: |
-    [
-      { "alias": "msg", "score": 80 }, 
-      { "alias": "data.message", "score": 79 },
-      { "alias": "array[0].message", "score": 78 },
-    ]
+messageAliases:
+  [
+    { alias: "msg", score: 80 },
+    { alias: "data.message", score: 79 },
+    { alias: "array[0].message", score: 78 },
+  ]
 ```
 
+### Port
+
+To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)
+
+### Log Level
+
+To change the Log Level set `logLevel` to: (default: `info`)
+
+| Level   |
+| ------- |
+| `info`  |
+| `debug` |
+| `warn`  |
+| `error` |
+| `fatal` |
+| `dev`   |
+
 ## Contributing
 
 Found a bug? Want to change or add something?

Dockerfile

@@ -1,15 +1,22 @@
 FROM alpine:latest
 RUN apk --no-cache add ca-certificates
 
-ENV PORT=8880
+ENV SERVER__PORT=8880
+
+ENV DEFAULTS_PATH=/app/config/defaults.yml
+
+ENV CONFIG_PATH=/config/config.yml
+ENV TOKENS_DIR=/config/tokens
 
 ARG TARGETOS
 ARG TARGETARCH
 
 WORKDIR /app
 
+COPY . .
+
 COPY dist/${TARGETOS}/${TARGETARCH}/app .
 
 RUN ls
 
-CMD ["./app"]
+CMD ["./app"]

config/defaults.yml

@@ -0,0 +1,39 @@
+server:
+  port: 8880
+
+logLevel: INFO
+
+messageAliases:
+  [
+    { alias: msg, score: 100 },
+    { alias: content, score: 99 },
+    { alias: description, score: 98 },
+    { alias: text, score: 20 },
+    { alias: summary, score: 15 },
+    { alias: details, score: 14 },
+
+    { alias: data.message, score: 10 },
+    { alias: data.content, score: 9 },
+    { alias: data.description, score: 8 },
+    { alias: data.text, score: 7 },
+    { alias: data.summary, score: 6 },
+    { alias: data.details, score: 5 },
+
+    { alias: payload, score: 3 },
+    { alias: body, score: 2 },
+    { alias: data, score: 1 },
+  ]
+
+variables:
+  recipients: ${RECIPIENTS}
+  number: ${NUMBER}
+
+blockedEndpoints:
+  - /v1/about
+  - /v1/configuration
+  - /v1/devices
+  - /v1/register
+  - /v1/unregister
+  - /v1/qrcodelink
+  - /v1/accounts
+  - /v1/contacts

docker-compose.yaml

@@ -20,10 +20,10 @@ services:
         aliases:
           - secured-signal-api
     environment:
-      SIGNAL_API_URL: http://signal-api:8080
-      DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]'
-      NUMBER: 123456789
-      API_TOKEN: LOOOOOONG_STRING
+      API__URL: http://signal-api:8080
+      VARIABLES__RECIPIENTS: 000,001,002
+      VARIABLES__NUMBER: 123456789
+      API__TOKENS: LOOOOOONG_STRING
     ports:
       - "8880:8880"
     restart: unless-stopped

examples/config.yml

@@ -0,0 +1,17 @@
+# Example Config (all configurations shown)
+
+api:
+  port: 8880
+  url: http://signal-api:8080
+  tokens: [token1, token2]
+
+logLevel: INFO
+
+variables:
+  number: "000"
+  recipients: ["001", "group.id", "user.id"]
+
+messageAliases: [{ alias: "msg", score: 100 }]
+
+blockedEndpoints:
+  - /v1/about

examples/token.yml

@@ -0,0 +1,7 @@
+token: LOOOONG_STRING
+
+overrides:
+  variables: # Disable Placeholder
+  blockedEndpoints: # Disable Sending
+    - /v2/send
+  messageAliases: # Disable Aliases