diff --git a/README.md b/README.md
index 2a031b63..e090f03b 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ endpoint restrictions, placeholders, flexible configuration
## Contents
-Check out the [**Official Documentation**](https://codeshelldev.github.io/secured-signal-api) for up-to-date Instructions and additional Content.
+Check out the [**Official Documentation**](https://codeshelldev.github.io/secured-signal-api) for up-to-date instructions and additional content!
- [Getting Started](#getting-started)
- [Setup](#setup)
@@ -104,29 +104,29 @@ networks:
backend:
```
-And add secure Token(s) to `api.tokens`. See [API TOKENs](#api-tokens).
+And add secure tokens to `api.tokens`. See [API Tokens](#api-tokens).
> [!IMPORTANT]
-> In this documentation, we use `sec-signal-api:8880` as the host for simplicity.
-> Replace it with your actual container/host IP, port, or hostname.
+> Here we'll use `sec-signal-api:8880` as the host,
+> but replace it with your actual container/host IP, port, or hostname
## Setup
-Before you can send messages via Secured Signal API you must first set up [Signal rAPI](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 set up [Signal CLI REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md)
1. **Register** or **link** a Signal account with `signal-cli-rest-api`
2. Deploy `secured-signal-api` with at least one API token
-3. Confirm you can send a test message (see [Usage](#usage))
+3. Confirm you can send a test message (See [Usage](#usage))
-> [!TIP]
-> Run setup directly with Signal rAPI.
-> Setup requests via Secured Signal API are blocked. See [Blocked Endpoints](#endpoints).
+> [!IMPORTANT]
+> Run setup directly with Signal CLI REST API.
+> Setup requests via Secured Signal API [are blocked by default](#endpoints)
## Usage
-Secured Signal API provides 3 Ways to Authenticate
+Secured Signal API provides 3 ways to authenticate
### Auth
@@ -148,11 +148,11 @@ 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 for example and/or Recipients in you, may use **Placeholders** in your Request.
+If you are not comfortable / don't want to hard-code your number for example and/or recipients in you, may use **placeholders** in your request.
**How to use:**
-| Type | Example | Note |
+| Scope | Example | Note |
| :--------------------- | :------------------ | :--------------- |
| Body | `{{@data.key}}` | |
| Header | `{{#Content_Type}}` | `-` becomes `_` |
@@ -160,7 +160,7 @@ If you are not comfortable / don't want to hardcode your Number for example and/
**Where to use:**
-| Type | Example |
+| Scope | Example |
| :---- | :--------------------------------------------------------------- |
| Body | `{"number": "{{ .NUMBER }}", "recipients": "{{ .RECIPIENTS }}"}` |
| Query | `http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}` |
@@ -174,28 +174,32 @@ You can also combine them:
}
```
-#### KeyValue Pair Injection
+#### Query-to-Body Injection
-In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request 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://sec-signal-api:8880/?@key=value`
-In order to differentiate Injection Queries and _regular_ Queries
-you have to add `@` in front of any KeyValue Pair assignment.
+> [!IMPORTANT]
+> To differentiate **injection queries** from _regular_ queries, **prefix the key with `@`**.
+> Only keys starting with `@` are injected into the request body
-Supported types include **strings**, **ints**, **arrays** and **json dictionaries**. See [Formatting](https://codeshelldev.github.io/secured-signal-api/docs/usage/formatting).
+> [!NOTE]
+>
+> - Supported value types include **strings**, **integers**, **arrays**, and **JSON objects**
+> - See [Formatting](https://codeshelldev.github.io/secured-signal-api/docs/usage/formatting) for details on supported structures and syntax
## Configuration
-There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` aswell as Environment Variables to override the config.
+There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` as well as environment variables to override the config.
### Config Files
-Config files allow **YAML** formatting and also `${ENV}` to get Environment Variables.
+Config files allow **YAML** formatting and `${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`)
+To change the internal config file location set `CONFIG_PATH` in your **environment**. (default: `/config/config.yml`)
-This example config shows all of the individual settings that can be applied:
+This example config shows all the individual settings that can be applied:
```yaml
# Example Config (all configurations shown)
@@ -239,8 +243,6 @@ settings:
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](#endpoints), [Placeholders](#variables), etc.
-
Here is an example:
```yaml
@@ -249,22 +251,23 @@ api:
settings:
message:
- fieldMappings: # Disable Mappings
- variables: # Disable Placeholder
+ fieldMappings: # Disable mappings
+ variables: # Disable variable placeholders
access:
- endpoints: # Disable Sending
+ endpoints: # Disable sending
- "!/v2/send"
```
### Templating
-Secured Signal API uses Golang's [Standard Templating Library](https://pkg.go.dev/text/template).
+Secured Signal API uses Go's [standard templating library](https://pkg.go.dev/text/template).
This means that any valid Go template string will also work in Secured Signal API.
Go's templating library is used in the following features:
- [Message Templates](#message-templates)
+- [Query-to-Body Injection](#query-to-body-injection)
- [Placeholders](#placeholders)
This makes advanced [Message Templates](#message-templates) like this one possible:
@@ -301,7 +304,7 @@ settings:
### API Tokens
-During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.
+During authentication Secured Signal API will try to match the given token against the list of tokens inside of the `api.tokens` attribute.
```yaml
api:
@@ -309,15 +312,15 @@ api:
```
> [!IMPORTANT]
-> Using API Tokens is highly recommended, but not mandatory.
-> Some important Security Features won't be available (like default Blocked Endpoints).
+> Using API tokens is highly recommended, but not mandatory.
+> Some important security features won't be available (for example the [default blocked endpoints](#endpoints))
> [!NOTE]
-> Blocked Endpoints can be reactivated by manually configuring them
+> Blocked endpoints can be reactivated by manually configuring them
### Endpoints
-Since 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...
+Since Secured Signal API is just a proxy you can use all the [Signal REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) endpoints except for…
| Endpoint | |
| :-------------------- | ------------------ |
@@ -326,10 +329,14 @@ Since Secured Signal API is just a Proxy you can use all of the [Signal REST API
| **/v1/register** | **/v1/accounts** |
| **/v1/qrcodelink** | |
-These Endpoints are blocked by default due to Security Risks.
+These endpoints are blocked by default due to security risks.
> [!NOTE]
-> Matching uses [glob-style patterns](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html): `*` matches any sequence of characters, `?` matches a single character and `[abc]` matches one of the characters in the brackets
+> Matching uses [glob-like patterns](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html):
+>
+> - `*` matches any sequence of characters
+> - `?` matches a single character
+> - `[abc]` matches one of the characters in the brackets
You can modify endpoints by configuring `access.endpoints` in your config:
@@ -344,10 +351,10 @@ settings:
- /v2/send
```
-By default adding an endpoint explictly allows access to it, use `!` to block it instead.
+By default adding an endpoint explicitly allows access to it, use `!` to block it instead.
> [!IMPORTANT]
-> When using `!` to block you must enclose the endpoint with quotes, like in the example above.
+> When using `!` to block you must enclose the endpoint with quotes, like in the example above
| Config (Allow) | (Block) | Result | | | |
| :------------- | :------------- | :--------: | --- | :---------------: | --- |
@@ -357,12 +364,12 @@ By default adding an endpoint explictly allows access to it, use `!` to block it
### Variables
-Placeholders can be added under `variables` and can then be referenced in the Body, Query or URL.
+Variables can be added under `variables` and can then be referenced in the body, query, or path.
See [Placeholders](#placeholders).
> [!NOTE]
-> Every Placeholder Key will be converted into an Uppercase String.
-> Example: `number` becomes `NUMBER` in `{{.NUMBER}}`
+> Variables are always converted into an **uppercase** string.
+> Example: `number` ⇒ `NUMBER` in `{{.NUMBER}}`
```yaml
settings:
@@ -374,7 +381,7 @@ settings:
### Message Templates
-To customize the `message` attribute you can use **Message Templates** to build your message by using other Body Keys and Variables.
+To customize the `message` attribute you can use **Message Templates** to build your message by using other body keys and variables.
Use `message.template` to configure:
```yaml
@@ -386,8 +393,12 @@ settings:
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.
+> [!NOTE]
+> Supported [placeholder types](#placeholders):
+>
+> | `.` Variables | `@` Body | `#` Headers |
+> | ------------- | -------- | ----------- |
+> | ✅ | ✅ | ✅ |
### Field Policies
@@ -404,14 +415,19 @@ settings:
Set the wanted action on encounter, available options are `block` and `allow`.
-Use `@` for Body Keys and `#` for Headers.
+> [!NOTE]
+> Supported [placeholder types](#placeholders):
+>
+> | `.` Variables | `@` Body | `#` Headers |
+> | ------------- | -------- | ----------- |
+> | ❌ | ✅ | ✅ |
### Field Mappings
-To improve compatibility with other services Secured Signal API provides **Field Mappings** and a built-in `message` Mapping.
+To improve compatibility with other services Secured Signal API provides **Field Mappings** and a built-in `message` mapping.
-Default `message` Mapping
+Default `message` mapping
| Field | Score | Field | Score |
| ------------ | ----- | ---------------- | ----- |
@@ -425,7 +441,7 @@ To improve compatibility with other services Secured Signal API provides **Field
-Secured Signal API will pick the best scoring Field (if available) to 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.
Field Mappings can be added by setting `message.fieldMappings` in your config:
@@ -442,12 +458,17 @@ settings:
".NUMBER": [{ field: "phone_number", score: 100 }]
```
-Use `@` for mapping to Body Keys and `.` for mapping to Variables.
+> [!NOTE]
+> Supported [placeholder types](#placeholders):
+>
+> | `.` Variables | `@` Body | `#` Headers |
+> | ------------- | -------- | ----------- |
+> | ✅ | ✅ | ❌ |
## Contributing
Found a bug? Want to change or add something?
-Feel free to open up an [Issue](https://github.com/codeshelldev/secured-signal-api/issues) or create a [Pull Request](https://github.com/codeshelldev/secured-signal-api/pulls)!
+Feel free to open up an [issue](https://github.com/codeshelldev/secured-signal-api/issues) or create a [pull request](https://github.com/codeshelldev/secured-signal-api/pulls)!
## Support
@@ -457,10 +478,10 @@ Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project
## Help
-**Are you having Problems setting up Secured Signal API?**
-No worries check out the [Discussions](https://github.com/codeshelldev/secured-signal-api/discussions) Tab and ask for help.
+**Are you having problems setting up Secured Signal API?**
+No worries check out the [discussions](https://github.com/codeshelldev/secured-signal-api/discussions) tab and ask for help.
-**We are all Volunteers**, so please be friendly and patient.
+**We are all volunteers**, so please be friendly and patient.
## License