diff --git a/.github/templates/README.template.md b/.github/templates/README.template.md index 4ed7233..84eff81 100644 --- a/.github/templates/README.template.md +++ b/.github/templates/README.template.md @@ -1,12 +1,17 @@ -# Secured Signal Api +# Secured Signal API -Secured Signal Api acts as a secure proxy for signal-rest-api. +Secured Signal API acts as a secure proxy for [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api). ## Installation Get the latest version of the `docker-compose.yaml` file: -And set `API_TOKEN` to a long secure string +And set `API_TOKEN` to a long secure string. + +> [!IMPORTANT] +> This Documentation will be using `sec-signal-api:8880` as the service host, +> this **won't work**, instead use your containers IP + Port. +> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy) ```yaml { { file.docker-compose.yaml } } @@ -14,7 +19,7 @@ And set `API_TOKEN` to a long secure string ### Reverse proxy -Take a look at traefik implementation: +Take a look at the [traefik](https://github.com/traefik/traefik) implementation: ```yaml { { file.examples/traefik.docker-compose.yaml } } @@ -22,56 +27,74 @@ Take a look at traefik implementation: ## Setup -Before you can send messages via `secured-signal-api` you must first setup [`signal-api`](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md), +Before you can send messages via Secured Signal API you must first setup [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) -to send messages you have to either: +To be able to use the API you have to either: -- **register a Signal Account** +- **register with your Signal Account** OR - **link Signal API to an already registered Signal Device** +> [!TIP] +> It is advised to do Setup directly with Signal rAPI +> if you try to Setup with Secured Signal API you will be blocked from doing so. See [Blocked Endpoints](#blocked-endpoints). + ## Usage -Secured Signal API implements 3 Ways to Authenticate +Secured Signal API provides 3 Ways to Authenticate ### Bearer -To Authenticate with `secured-signal-api` add `Authorization: Bearer TOKEN` to your request Headers +To Authenticate add `Authorization: Bearer API_TOKEN` to your request Headers ### Basic Auth -To use Basic Auth as Authorization Method add `Authorization: Basic base64{user:pw}` to your Headers +To use Basic Auth as Authorization Method add `Authorization: Basic BASE64_STRING` to your Headers + +User is `api` (LOWERCASE) + +Formatting for `BASE64_STRING` = `user:API_KEY`. + +example: + +```bash +echo "api:API_KEY" | base64 +``` + +=> `YXBpOkFQSV9LRVkK` ### Query Auth If you are working with a limited Application you may **not** be able to modify Headers or the Request Body -in this case you should use **Query Auth**. +in this case you can use **Query Auth**. Here is a simple example: ```bash -curl -X POST http://signal-api:8880/v2/send?@authorization=TOKEN +curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN ``` +Notice the `@` infront of `authorization`. See [Formatting](#format) + ### Example -To send a message to `number`: `1234567`: +To send a message to 1234567: ```bash -curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://signal-api:8880/v2/send +curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://sec-signal-api:8880/v2/send ``` ### Advanced #### Placeholders -If you are not comfortable with hardcoding your Number and/or Recipients in you may use **Placeholders** in your request like: +If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request. -`{{ .NUMBER }}` or `{{ .RECIPIENTS }}` +Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}` -These _Placeholders_ can be used in the Query or the Body of a Request like so: +These Placeholders can be used in the Request Query or the Body of a Request like so: **Body** @@ -85,45 +108,46 @@ These _Placeholders_ can be used in the Query or the Body of a Request like so: **Query** ``` -http://.../?@number={{.NUMBER}} +http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}} ``` **Path** ``` -http://signal-api:8880/v1/receive/{{.NUMBER}} +http://sec-signal-api:8880/v1/receive/{{.NUMBER}} ``` #### KeyValue Pair Injection -In some cases you may not be able to access / modify the Request Body, if that is the case specify needed values in the Requests Query: +In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query: ``` -http://signal-api:8880/?@key=value +http://sec-signal-api:8880/?@key=value ``` -**Format** +##### Format + In order to differentiate Injection Queries and _regular_ Queries -you have to add `@` in front of any KeyValue Pair assignment +you have to add `@` in front of any KeyValue Pair assignment. ### Environment Variables #### API Token > [!IMPORTANT] -> It is highly recommended to set this Environment Variable to a long secure string +> It is highly recommended to set this Environment Variable -_What if I just don't?_ +> _What if I just don't?_ -Well Secured Signal API will still work, but important Security Features won't be available -like Blocked Endpoints and anyone with access to your Docker Container will be able to send Messages in your Name +Well, 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 setting them in the Environment #### Blocked Endpoints -Because Secured Signal API is just a secure Proxy you can use all of the [Signal REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) endpoints with an Exception of: +Because Secured Signal API is just a secure 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... - **/v1/about** @@ -141,7 +165,7 @@ Because Secured Signal API is just a secure Proxy you can use all of the [Signal - **/v1/contacts** -These Endpoints are blocked by default to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` in the environment variable to a valid json array string +These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a valid json array string ```yaml environment: @@ -150,46 +174,56 @@ environment: #### Variables -By default Secured Signal API provides the following **Placeholders**: +By default Secured Signal API provides the following Placeholders: + +- **NUMBER** = _ENV_: `NUMBER` +- **RECIPIENTS** = _ENV_: `RECIPIENTS` -- **NUMBER** = _ENV_: `SENDER` -- **RECIPIENTS** = _ENV_: `DEFAULT_RECIPIENTS` +#### Customization -If you are ever missing any **Placeholder** (that isn't built-in) you can add as many as you like to `VARIABLES` inside your environment +Placeholders can be added by setting `VARIABLES` inside your Environment. ```yaml environment: VARIABLES: ' "NUMBER2": "002", "GROUP_CHAT_1": [ "user.id", "000", "001", "group.id" ] ' ``` -#### Default Recipients +#### Recipients -Set this environment variable to automatically provide default Recipients: +Set this Environment Variable to automatically provide default Recipients: ```yaml environment: - DEFAULT_RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] ' + RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] ' +``` + +example: + +```json +{ + "recipients": "{{.RECIPIENTS}}" +} ``` #### Message Aliases To improve compatibility with other services Secured Signal API provides aliases for the `message` attribute by default: -| Alias | Priority | -| ----------- | ----------- | -| msg | 100 | -| content | 99 | -| description | 98 | -| text | 20 | -| body | 15 | -| summary | 10 | -| details | 9 | -| payload | 2 | -| data | 1 | +| Alias | Priority | +| ----------- | -------- | +| msg | 100 | +| content | 99 | +| description | 98 | +| text | 20 | +| body | 15 | +| summary | 10 | +| details | 9 | +| payload | 2 | +| data | 1 | -Secured Signal API will use the highest priority Message Alias to get the correct message from the Request Body. +Secured Signal API will use the highest priority Message Alias to extract the correct message from the Request Body. -If you are missing a Message Alias to have Secured Signal API integrated with a Service you can simply set `MESSAGE_ALIASES` in ENV: +Message Aliases can be added by setting `MESSAGE_ALIASES`: ```yaml environment: @@ -203,6 +237,12 @@ Feel free to open up an issue or create a Pull Request! _This is a small project so don't expect any huge changes in the future_ +## Support + +Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project. + +:) + ## License [MIT](https://choosealicense.com/licenses/mit/) diff --git a/README.md b/README.md index 7ad6a4c..1e331bf 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ -# Secured Signal Api +# Secured Signal API -Secured Signal Api acts as a secure proxy for signal-rest-api. +Secured Signal API acts as a secure proxy for [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api). ## Installation Get the latest version of the `docker-compose.yaml` file: -And set `API_TOKEN` to a long secure string +And set `API_TOKEN` to a long secure string. + +> [!IMPORTANT] +> This Documentation will be using `sec-signal-api:8880` as the service host, +> this **won't work**, instead use your containers IP + Port. +> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy) ```yaml --- @@ -34,7 +39,7 @@ services: environment: SIGNAL_API_URL: http://signal-api:8080 DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]' - SENDER: 123456789 + NUMBER: 123456789 API_TOKEN: LOOOOOONG_STRING ports: - "8880:8880" @@ -46,7 +51,7 @@ networks: ### Reverse proxy -Take a look at traefik implementation: +Take a look at the [traefik](https://github.com/traefik/traefik) implementation: ```yaml services: @@ -62,7 +67,7 @@ services: environment: SIGNAL_API_URL: http://signal-api:8080 DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]' - SENDER: 123456789 + NUMBER: 123456789 API_TOKEN: LOOOOOONG_STRING labels: - traefik.enable=true @@ -83,56 +88,74 @@ networks: ## Setup -Before you can send messages via `secured-signal-api` you must first setup [`signal-api`](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md), +Before you can send messages via Secured Signal API you must first setup [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) -to send messages you have to either: +To be able to use the API you have to either: -- **register a Signal Account** +- **register with your Signal Account** OR - **link Signal API to an already registered Signal Device** +> [!TIP] +> It is advised to do Setup directly with Signal rAPI +> if you try to Setup with Secured Signal API you will be blocked from doing so. See [Blocked Endpoints](#blocked-endpoints). + ## Usage -Secured Signal API implements 3 Ways to Authenticate +Secured Signal API provides 3 Ways to Authenticate ### Bearer -To Authenticate with `secured-signal-api` add `Authorization: Bearer TOKEN` to your request Headers +To Authenticate add `Authorization: Bearer API_TOKEN` to your request Headers ### Basic Auth -To use Basic Auth as Authorization Method add `Authorization: Basic base64{user:pw}` to your Headers +To use Basic Auth as Authorization Method add `Authorization: Basic BASE64_STRING` to your Headers + +User is `api` (LOWERCASE) + +Formatting for `BASE64_STRING` = `user:API_KEY`. + +example: + +```bash +echo "api:API_KEY" | base64 +``` + +=> `YXBpOkFQSV9LRVkK` ### Query Auth If you are working with a limited Application you may **not** be able to modify Headers or the Request Body -in this case you should use **Query Auth**. +in this case you can use **Query Auth**. Here is a simple example: ```bash -curl -X POST http://signal-api:8880/v2/send?@authorization=TOKEN +curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN ``` +Notice the `@` infront of `authorization`. See [Formatting](#format) + ### Example -To send a message to `number`: `1234567`: +To send a message to 1234567: ```bash -curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://signal-api:8880/v2/send +curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://sec-signal-api:8880/v2/send ``` ### Advanced #### Placeholders -If you are not comfortable with hardcoding your Number and/or Recipients in you may use **Placeholders** in your request like: +If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request. -`{{ .NUMBER }}` or `{{ .RECIPIENTS }}` +Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}` -These _Placeholders_ can be used in the Query or the Body of a Request like so: +These Placeholders can be used in the Request Query or the Body of a Request like so: **Body** @@ -146,45 +169,46 @@ These _Placeholders_ can be used in the Query or the Body of a Request like so: **Query** ``` -http://.../?@number={{.NUMBER}} +http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}} ``` **Path** ``` -http://signal-api:8880/v1/receive/{{.NUMBER}} +http://sec-signal-api:8880/v1/receive/{{.NUMBER}} ``` #### KeyValue Pair Injection -In some cases you may not be able to access / modify the Request Body, if that is the case specify needed values in the Requests Query: +In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query: ``` -http://signal-api:8880/?@key=value +http://sec-signal-api:8880/?@key=value ``` -**Format** +##### Format + In order to differentiate Injection Queries and _regular_ Queries -you have to add `@` in front of any KeyValue Pair assignment +you have to add `@` in front of any KeyValue Pair assignment. ### Environment Variables #### API Token > [!IMPORTANT] -> It is highly recommended to set this Environment Variable to a long secure string +> It is highly recommended to set this Environment Variable -_What if I just don't?_ +> _What if I just don't?_ -Well Secured Signal API will still work, but important Security Features won't be available -like Blocked Endpoints and anyone with access to your Docker Container will be able to send Messages in your Name +Well, 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 setting them in the Environment #### Blocked Endpoints -Because Secured Signal API is just a secure Proxy you can use all of the [Signal REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) endpoints with an Exception of: +Because Secured Signal API is just a secure 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... - **/v1/about** @@ -202,7 +226,7 @@ Because Secured Signal API is just a secure Proxy you can use all of the [Signal - **/v1/contacts** -These Endpoints are blocked by default to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` in the environment variable to a valid json array string +These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a valid json array string ```yaml environment: @@ -211,46 +235,56 @@ environment: #### Variables -By default Secured Signal API provides the following **Placeholders**: +By default Secured Signal API provides the following Placeholders: + +- **NUMBER** = _ENV_: `NUMBER` +- **RECIPIENTS** = _ENV_: `RECIPIENTS` -- **NUMBER** = _ENV_: `SENDER` -- **RECIPIENTS** = _ENV_: `DEFAULT_RECIPIENTS` +#### Customization -If you are ever missing any **Placeholder** (that isn't built-in) you can add as many as you like to `VARIABLES` inside your environment +Placeholders can be added by setting `VARIABLES` inside your Environment. ```yaml environment: VARIABLES: ' "NUMBER2": "002", "GROUP_CHAT_1": [ "user.id", "000", "001", "group.id" ] ' ``` -#### Default Recipients +#### Recipients -Set this environment variable to automatically provide default Recipients: +Set this Environment Variable to automatically provide default Recipients: ```yaml environment: - DEFAULT_RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] ' + RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] ' +``` + +example: + +```json +{ + "recipients": "{{.RECIPIENTS}}" +} ``` #### Message Aliases To improve compatibility with other services Secured Signal API provides aliases for the `message` attribute by default: -| Alias | Priority | -| ----------- | ----------- | -| msg | 100 | -| content | 99 | -| description | 98 | -| text | 20 | -| body | 15 | -| summary | 10 | -| details | 9 | -| payload | 2 | -| data | 1 | +| Alias | Priority | +| ----------- | -------- | +| msg | 100 | +| content | 99 | +| description | 98 | +| text | 20 | +| body | 15 | +| summary | 10 | +| details | 9 | +| payload | 2 | +| data | 1 | -Secured Signal API will use the highest priority Message Alias to get the correct message from the Request Body. +Secured Signal API will use the highest priority Message Alias to extract the correct message from the Request Body. -If you are missing a Message Alias to have Secured Signal API integrated with a Service you can simply set `MESSAGE_ALIASES` in ENV: +Message Aliases can be added by setting `MESSAGE_ALIASES`: ```yaml environment: @@ -264,6 +298,12 @@ Feel free to open up an issue or create a Pull Request! _This is a small project so don't expect any huge changes in the future_ +## Support + +Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project. + +:) + ## License [MIT](https://choosealicense.com/licenses/mit/) diff --git a/docker-compose.yaml b/docker-compose.yaml index af56be4..a329b20 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -23,7 +23,7 @@ services: environment: SIGNAL_API_URL: http://signal-api:8080 DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]' - SENDER: 123456789 + NUMBER: 123456789 API_TOKEN: LOOOOOONG_STRING ports: - "8880:8880" diff --git a/examples/traefik.docker-compose.yaml b/examples/traefik.docker-compose.yaml index 67f680a..c9f624b 100644 --- a/examples/traefik.docker-compose.yaml +++ b/examples/traefik.docker-compose.yaml @@ -11,7 +11,7 @@ services: environment: SIGNAL_API_URL: http://signal-api:8080 DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]' - SENDER: 123456789 + NUMBER: 123456789 API_TOKEN: LOOOOOONG_STRING labels: - traefik.enable=true diff --git a/utils/env/env.go b/utils/env/env.go index e6d4dc1..8350229 100644 --- a/utils/env/env.go +++ b/utils/env/env.go @@ -30,7 +30,7 @@ var ENV ENV_ = ENV_{ }, VARIABLES: map[string]any { "RECIPIENTS": []string{}, - "NUMBER": os.Getenv("SENDER"), + "NUMBER": os.Getenv("NUMBER"), }, MESSAGE_ALIASES: []middlewares.MessageAlias{ { @@ -79,7 +79,7 @@ func Load() { ENV.API_TOKEN = os.Getenv("API_TOKEN") blockedEndpointJSON := os.Getenv("BLOCKED_ENDPOINTS") - recipientsJSON := os.Getenv("DEFAULT_RECIPIENTS") + recipientsJSON := os.Getenv("RECIPIENTS") messageAliasesJSON := os.Getenv("MESSAGE_ALIASES") variablesJSON := os.Getenv("VARIABLES")