diff --git a/.github/templates/README.template.md b/.github/templates/README.template.md index e15587ac..084d5262 100644 --- a/.github/templates/README.template.md +++ b/.github/templates/README.template.md @@ -54,7 +54,7 @@ Check out the official [Documentation](https://codeshelldev.github.io/secured-si - [Configuration](#configuration) - [Endpoints](#endpoints) - [Variables](#variables) - - [Data Aliases](#data-aliases) + - [Field Mappings](#field-mappings) - [Message Templates](#message-templates) - [Integrations](https://codeshelldev.github.io/secured-signal-api/docs/integrations/compatibility) - [Contributing](#contributing) @@ -229,25 +229,26 @@ These Endpoints are blocked by default due to Security Risks. > [!NOTE] > Matching works by checking if the requested Endpoints starts with a Blocked or an Allowed Endpoint -You can modify Blocked Endpoints by configuring `blockedEndpoints` in your config: +You can modify endpoints by configuring `access.endpoints` in your config: ```yaml settings: - blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts] + access: + endpoints: + - !/v1/register + - !/v1/unregister + - !/v1/qrcodelink + - !/v1/contacts + - /v2/send ``` -You can also override Blocked Endpoints by adding Allowed Endpoints to `allowedEndpoints`. +By default adding an endpoint explictly allows access to it, use `!` to block it instead. -```yaml -settings: - allowedEndpoints: [/v2/send] -``` - -| Config (Allow) | (Block) | Result | | | | -| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- | -| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ | -| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 | -| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ | +| Config (Allow) | (Block) | Result | | | | +| :------------- | :------------- | :--------: | --- | :---------------: | --- | +| `/v2/send` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ | +| `unset` | `!/v1/receive` | **all** | ✅ | **`/v1/receive`** | 🛑 | +| `/v2` | `!/v2/send` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ | ### Variables @@ -260,35 +261,37 @@ See [Placeholders](#placeholders). ```yaml settings: - variables: - number: "+123400001", - recipients: ["+123400002", "group.id", "user.id"] + message: + variables: + number: "+123400001", + recipients: ["+123400002", "group.id", "user.id"] ``` ### Message Templates To customize the `message` attribute you can use **Message Templates** to build your message by using other Body Keys and Variables. -Use `messageTemplate` to configure: +Use `message.template` to configure: ```yaml settings: - messageTemplate: | - Your Message: - {{@message}}. - Sent with Secured Signal API. + message: + template: | + Your Message: + {{@message}}. + Sent with Secured Signal API. ``` Message Templates support [Standard Golang Templating](#templating). Use `@data.key` to reference Body Keys, `#Content_Type` for Headers and `.KEY` for Variables. -### Data Aliases +### Field Mappings -To improve compatibility with other services Secured Signal API provides **Data Aliases** and a built-in `message` Alias. +To improve compatibility with other services Secured Signal API provides **Field Mappings** and a built-in `message` Mapping.
-Default `message` Aliases +Default `message` Mapping -| Alias | Score | Alias | Score | +| Field | Score | Field | Score | | ------------ | ----- | ---------------- | ----- | | msg | 100 | data.content | 9 | | content | 99 | data.description | 8 | @@ -300,23 +303,24 @@ To improve compatibility with other services Secured Signal API provides **Data
-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. +Secured Signal API will pick the best scoring Field (if available) to set the Key to the correct Value from the Request Body. -Data Aliases can be added by setting `dataAliases` in your config: +Field Mappings can be added by setting `message.fieldMappings` in your config: ```yaml settings: - dataAliases: - "@message": - [ - { alias: "msg", score: 80 }, - { alias: "data.message", score: 79 }, - { alias: "array[0].message", score: 78 }, - ] - ".NUMBER": [{ alias: "phone_number", score: 100 }] + message: + fieldMappings: + "@message": + [ + { field: "msg", score: 80 }, + { field: "data.message", score: 79 }, + { field: "array[0].message", score: 78 }, + ] + ".NUMBER": [{ field: "phone_number", score: 100 }] ``` -Use `@` for aliasing Body Keys and `.` for aliasing Variables. +Use `@` for mapping to Body Keys and `.` for mapping to Variables. ## Contributing diff --git a/docs/configuration/data-aliases.md b/docs/configuration/data-aliases.md deleted file mode 100644 index d4ae421f..00000000 --- a/docs/configuration/data-aliases.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Data Aliases ---- - -# Data Aliases - -A Compatibility Layer for **Secured Signal API**. - -To improve compatibility with other services Secured Signal API provides **Data Aliases** and even a built-in `message` Alias. - -
-Default `message` Aliases - -| Alias | Score | Alias | Score | -| ------------ | ----- | ---------------- | ----- | -| msg | 100 | data.content | 9 | -| content | 99 | data.description | 8 | -| description | 98 | data.text | 7 | -| text | 20 | data.summary | 6 | -| summary | 15 | data.details | 5 | -| details | 14 | body | 2 | -| data.message | 10 | data | 1 | - -
- -Secured Signal API will pick the highest scoring **Data Alias** (if available) to set the key to the correct value **using the request body**. - -Data Aliases can be added by setting `dataAliases` in your config: - -```yaml -settings: - dataAliases: - "@message": - [ - { alias: "msg", score: 80 }, - { alias: "data.message", score: 79 }, - { alias: "array[0].message", score: 78 }, - ] - ".NUMBER": [{ alias: "phone_number", score: 100 }] -``` - -> [!IMPORTANT] -> Use `@` for aliasing Body Keys and `.` for aliasing Variables. diff --git a/docs/configuration/endpoints.md b/docs/configuration/endpoints.md index 89cd7f62..ee893b40 100644 --- a/docs/configuration/endpoints.md +++ b/docs/configuration/endpoints.md @@ -23,22 +23,23 @@ but by default the following endpoints are **blocked**, because of Security Conc > [!NOTE] > Matching works by checking if the requested Endpoints starts with a Blocked or an Allowed Endpoint -You can modify Blocked Endpoints by configuring `blockedEndpoints` in your config: +You can modify endpoints by configuring `access.endpoints` in your config: ```yaml settings: - blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts] + access: + endpoints: + - !/v1/register + - !/v1/unregister + - !/v1/qrcodelink + - !/v1/contacts + - /v2/send ``` -You can also override Blocked Endpoints by adding Allowed Endpoints to `allowedEndpoints`. +By default adding an endpoint explictly allows access to it, use `!` to block it instead. -```yaml -settings: - allowedEndpoints: [/v2/send] -``` - -| Config (Allow) | (Block) | Result | | | | -| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- | -| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ | -| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 | -| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ | +| Config (Allow) | (Block) | Result | | | | +| :------------- | :------------- | :--------: | --- | :---------------: | --- | +| `/v2/send` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ | +| `unset` | `!/v1/receive` | **all** | ✅ | **`/v1/receive`** | 🛑 | +| `/v2` | `!/v2/send` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ | diff --git a/docs/configuration/examples/config.yml b/docs/configuration/examples/config.yml index 20058922..3591048c 100644 --- a/docs/configuration/examples/config.yml +++ b/docs/configuration/examples/config.yml @@ -9,20 +9,21 @@ api: logLevel: info settings: - messageTemplate: | - You've got a Notification: - {{@message}} - At {{@data.timestamp}} on {{@data.date}}. - Send using {{.NUMBER}}. + message: + template: | + You've got a Notification: + {{@message}} + At {{@data.timestamp}} on {{@data.date}}. + Send using {{.NUMBER}}. - variables: - number: "+123400001" - recipients: ["+123400002", "group.id", "user.id"] + variables: + number: "+123400001" + recipients: ["+123400002", "group.id", "user.id"] - dataAliases: - "@message": [{ alias: "msg", score: 100 }] + fieldMappings: + "@message": [{ field: "msg", score: 100 }] - blockedEndpoints: - - /v1/about - allowedEndpoints: - - /v2/send + access: + endpoints: + - !/v1/about + - /v2/send diff --git a/docs/configuration/examples/message-template.yml b/docs/configuration/examples/message-template.yml index 2ffa9cd2..74f40e37 100644 --- a/docs/configuration/examples/message-template.yml +++ b/docs/configuration/examples/message-template.yml @@ -1,26 +1,27 @@ settings: - messageTemplate: | - {{- $greeting := "Hello" -}} - {{ $greeting }}, {{ @name }}! - {{ if @age -}} - You are {{ @age }} years old. - {{- else -}} - Age unknown. - {{- end }} - Your friends: - {{- range @friends }} - - {{ . }} - {{- else }} - You have no friends. - {{- end }} - Profile details: - {{- range $key, $value := @profile }} - - {{ $key }}: {{ $value }} - {{- end }} - {{ define "footer" -}} - This is the footer for {{ @name }}. - {{- end }} - {{ template "footer" . -}} - ------------------------------------ - Content-Type: {{ #Content_Type }} - Redacted Auth Header: {{ #Authorization }} \ No newline at end of file + message: + template: | + {{- $greeting := "Hello" -}} + {{ $greeting }}, {{ @name }}! + {{ if @age -}} + You are {{ @age }} years old. + {{- else -}} + Age unknown. + {{- end }} + Your friends: + {{- range @friends }} + - {{ . }} + {{- else }} + You have no friends. + {{- end }} + Profile details: + {{- range $key, $value := @profile }} + - {{ $key }}: {{ $value }} + {{- end }} + {{ define "footer" -}} + This is the footer for {{ @name }}. + {{- end }} + {{ template "footer" . -}} + ------------------------------------ + Content-Type: {{ #Content_Type }} + Redacted Auth Header: {{ #Authorization }} diff --git a/docs/configuration/examples/token.yml b/docs/configuration/examples/token.yml index b3723e21..27005cf9 100644 --- a/docs/configuration/examples/token.yml +++ b/docs/configuration/examples/token.yml @@ -1,7 +1,10 @@ tokens: [LOOOONG_STRING] overrides: - variables: # Disable Placeholder - blockedEndpoints: # Disable Sending - - /v2/send - dataAliases: # Disable Aliases + message: + fieldMappings: # Disable Mappings + variables: # Disable Placeholder + + access: + endpoints: # Disable Sending + - !/v2/send diff --git a/docs/configuration/field-mappings.md b/docs/configuration/field-mappings.md new file mode 100644 index 00000000..57cd9491 --- /dev/null +++ b/docs/configuration/field-mappings.md @@ -0,0 +1,44 @@ +--- +title: Field Mappings +--- + +# Field Mappings + +A Compatibility Layer for **Secured Signal API**. + +To improve compatibility with other services Secured Signal API provides **Field Mappings** and even a built-in `message` Mapping. + +
+Default `message` Mapping + +| Field | Score | Field | Score | +| ------------ | ----- | ---------------- | ----- | +| msg | 100 | data.content | 9 | +| content | 99 | data.description | 8 | +| description | 98 | data.text | 7 | +| text | 20 | data.summary | 6 | +| summary | 15 | data.details | 5 | +| details | 14 | body | 2 | +| data.message | 10 | data | 1 | + +
+ +Secured Signal API will pick the highest scoring **Field** (if available) to set the key to the correct value **using the request body**. + +Field Mappings can be added by setting `message.fieldMappings` in your config: + +```yaml +settings: + message: + fieldMappings: + "@message": + [ + { field: "msg", score: 80 }, + { field: "data.message", score: 79 }, + { field: "array[0].message", score: 78 }, + ] + ".NUMBER": [{ field: "phone_number", score: 100 }] +``` + +> [!IMPORTANT] +> Use `@` for mapping to Body Keys and `.` for mapping to Variables. diff --git a/docs/configuration/message-templates.md b/docs/configuration/message-template.md similarity index 56% rename from docs/configuration/message-templates.md rename to docs/configuration/message-template.md index 00dc998a..e227591d 100644 --- a/docs/configuration/message-templates.md +++ b/docs/configuration/message-template.md @@ -1,14 +1,14 @@ --- -title: Message Templates +title: Message Template --- -# Message Templates +# Message Template Message Templates are the best way to **structure** and **customize** your messages and also very useful for **compatiblity** between different services. -Configure them by using the `messageTemplates` attribute in you config. +Configure them by using the `message.template` attribute in you config. -These support Go Templates (See [Usage](../usage/advanced)) and work by templating the `message` attribute in the request's body. +These support Go Templates (See [Templates](../usage/formatting)) and work by templating the `message` attribute in the request's body. Here is an example: @@ -17,5 +17,8 @@ Here is an example: ``` > [!IMPORTANT] -> Message Templates support [Standard Golang Templating](../usage/advanced). +> Message Templates support [Standard Golang Templating](../usage/formatting). > Use `@data.key` to reference Body Keys, `#Content_Type` for Headers and `.KEY` for [Variables](./variables). + +> [!WARNING] +> Templating using the `Authorization` header results in a redacted string. diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md index b1ec1b93..371d04c9 100644 --- a/docs/configuration/overview.md +++ b/docs/configuration/overview.md @@ -15,10 +15,10 @@ Suppose you want to set a new [Placeholder](../usage/advanced) `NUMBER` in your ```yaml environment: - SETTINGS__VARIABLES__NUMBER: "+123400001" + SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001" ``` -This would internally be converted into `settings.variables.number` matching the config formatting. +This would internally be converted into `settings.message.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 `.`) diff --git a/docs/configuration/variables.md b/docs/configuration/variables.md index 35b1b89f..f2cf8f3d 100644 --- a/docs/configuration/variables.md +++ b/docs/configuration/variables.md @@ -5,7 +5,7 @@ title: Variables # Variables The most common type of [Placeholders](../usage/advanced) are **variables**. -Which can be set under `variables` in your config. +Which can be set under `message.variables` in your config. > [!IMPORTANT] > Every Placeholder Key will be converted into an **uppercase** string. @@ -15,7 +15,8 @@ Here is an example: ```yaml settings: - variables: - number: "+123400001", - recipients: ["+123400002", "group.id", "user.id"] + message: + variables: + number: "+123400001", + recipients: ["+123400002", "group.id", "user.id"] ``` diff --git a/docs/features/features.md b/docs/features/features.md index 65b17c8e..f843c9ab 100644 --- a/docs/features/features.md +++ b/docs/features/features.md @@ -9,7 +9,7 @@ Here are some of the highlights of using **Secured Signal API** --- -## Message Templates +## Message Template > _Incredible fun and useful_ @@ -20,10 +20,10 @@ Look at this complex template for example: {{{ #://configuration/examples/message-template.yml }}} ``` -It can extract needed data from the body and even the headers ([exceptions](./usage/advanced)) and then process them using Go's Templating Library +It can extract needed data from the body and even the headers ([exceptions](./configuration/message-template)) and then process them using Go's Templating Library and finally output a message packed with so much information. -Head to [Configuration](./configuration/message-templates) to see how-to use. +Head to [Configuration](./configuration/message-template) to see how-to use. --- @@ -38,14 +38,14 @@ Take a look at the [Usage](./usage/advanced). --- -## Data Aliases +## Field Mappings > _Boring, but sooo definetly needed_ -**Data Aliases** are also very useful for when your favorite service does not officially support **Secured Signal API** (or Signal CLI REST API). +**Field Mappings** are also very useful for when your favorite service does not officially support **Secured Signal API** (or Signal CLI REST API). With this feature you have the power to do it yourself, just extract what's needed and then integrate with any of the other features. -Interested? [Take a look](./configuration/data-aliases). +Interested? [Take a look](./configuration/field-mappings). --- @@ -59,6 +59,6 @@ Interested? [Take a look](./configuration/data-aliases). - [**Blocked Endpoints**](./configuration/endpoints) Go hand in hand for restricting unauthorized access and for ensuring least privilege. -[Time to go blocking...](./configuration/endpoints) +[Let's start blocking then!](./configuration/endpoints) --- diff --git a/docs/getting-started/examples/docker-compose.yaml b/docs/getting-started/examples/docker-compose.yaml index 422da2e1..2605bc1f 100644 --- a/docs/getting-started/examples/docker-compose.yaml +++ b/docs/getting-started/examples/docker-compose.yaml @@ -17,10 +17,9 @@ services: container_name: secured-signal environment: API__URL: http://signal-api:8080 - SETTINGS__VARIABLES__RECIPIENTS: - '[+123400002, +123400003, +123400004]' - SETTINGS__VARIABLES__NUMBER: "+123400001" - API__TOKENS: '[LOOOOOONG_STRING]' + SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: "[+123400002, +123400003, +123400004]" + SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001" + API__TOKENS: "[LOOOOOONG_STRING]" ports: - "8880:8880" restart: unless-stopped diff --git a/docs/integrations/compatibility.md b/docs/integrations/compatibility.md index a8f2883b..793022b9 100644 --- a/docs/integrations/compatibility.md +++ b/docs/integrations/compatibility.md @@ -17,7 +17,7 @@ But with one flaw: > _manual configuration_ -In order for Secured Signal API to be compatible and integratable with a service you still need to manually define [**Data Aliases**](../configuration/data-aliases) +In order for Secured Signal API to be compatible and integratable with a service you still need to manually define [**Field Mappings**](../configuration/field-mappings) and [**Message Templates**](../configuration/message-templates), which is quite easy, provided you know what the services is using as payload (try sending a request to some debugging endpoint). diff --git a/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml b/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml index 5ca852ed..d3493f78 100644 --- a/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml +++ b/docs/reverse-proxy/caddy/examples/caddy.docker-compose.yaml @@ -4,8 +4,8 @@ services: container_name: secured-signal-api environment: API__URL: http://signal-api:8080 - SETTINGS__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" - SETTINGS__VARIABLES__NUMBER: "+123400001" + SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" + SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001" API__TOKENS: "[LOOOOOONG_STRING]" restart: unless-stopped networks: diff --git a/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml b/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml index a138c798..05c6500a 100644 --- a/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml +++ b/docs/reverse-proxy/nginx/examples/nginx.docker-compose.yaml @@ -4,8 +4,8 @@ services: container_name: secured-signal-api environment: API__URL: http://signal-api:8080 - SETTINGS__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" - SETTINGS__VARIABLES__NUMBER: "+123400001" + SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" + SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001" API__TOKENS: "[LOOOOOONG_STRING]" restart: unless-stopped networks: diff --git a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml index 3ba6fd38..2f00b320 100644 --- a/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml +++ b/docs/reverse-proxy/traefik/examples/traefik.docker-compose.yaml @@ -4,8 +4,8 @@ services: container_name: secured-signal environment: API__URL: http://signal-api:8080 - SETTINGS__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" - SETTINGS__VARIABLES__NUMBER: "+123400001" + SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]" + SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001" API__TOKENS: "[LOOOOOONG_STRING]" labels: - traefik.enable=true diff --git a/docs/usage/formatting.md b/docs/usage/formatting.md index 1fa054b5..562d45d2 100644 --- a/docs/usage/formatting.md +++ b/docs/usage/formatting.md @@ -14,7 +14,7 @@ Which means that any valid Go template string will also work in Secured Signal A > [!NOTE] > Go's templating library is used in the following features: ->
- [Message Templates](./advanced)
- [Placeholders](./advanced) +>
- [Message Templates](../configuration/message-template)
- [Placeholders](./advanced) But you will mostly be using `{{.VAR}}`.