diff --git a/README.md b/README.md index 21f91a28..d77279f9 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,8 @@ Check out the official [Documentation](https://codeshelldev.github.io/secured-si - [Configuration](#configuration) - [Endpoints](#endpoints) - [Variables](#variables) - - [Data Aliases](#data-aliases) + - [Field Policies](#field-policies) + - [Field Mappings](#field-mappings) - [Message Templates](#message-templates) - [Integrations](https://codeshelldev.github.io/secured-signal-api/docs/integrations/compatibility) - [Contributing](#contributing) @@ -88,10 +89,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 @@ -209,23 +209,24 @@ api: logLevel: info settings: - messageTemplate: | - You've got a Notification: - {{@message}} - At {{@data.timestamp}} on {{@data.date}}. - Send using {{.NUMBER}}. - - variables: - number: "+123400001" - recipients: ["+123400002", "group.id", "user.id"] - - dataAliases: - "@message": [{ alias: "msg", score: 100 }] - - blockedEndpoints: - - /v1/about - allowedEndpoints: - - /v2/send + 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"] + + fieldMappings: + "@message": [{ field: "msg", score: 100 }] + + access: + endpoints: + - !/v1/about + - /v2/send ``` #### Token Configs @@ -240,10 +241,13 @@ Here is an example: 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 ``` ### Templating @@ -260,31 +264,32 @@ This makes advanced [Message Templates](#message-templates) like this one possib ```yaml 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 }} + 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 }} ``` ### API Tokens @@ -319,25 +324,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 @@ -350,35 +356,54 @@ 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 Policies + +**Field Policies** allow for blocking or specifically allowing certain fields with set values from being used in the requests body or headers. + +Configure them by using `access.fieldPolicies` like so: + +```yaml +settings: + access: + fieldPolicies: + "@number": { value: "+123400002", action: block } +``` + +Set the wanted action on encounter, available options are `block` and `allow`. + +Use `@` for Body Keys and `#` for Headers. + +### 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 | @@ -390,23 +415,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