Skip to content

Commit 7275629

Browse files
CodeShellDevCodeShellDev
authored
Docs v1.6.0 (#284)
1 parent 13c5994 commit 7275629

1 file changed

Lines changed: 15 additions & 303 deletions

File tree

‎.github/templates/README.template.md‎

Lines changed: 15 additions & 303 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,14 @@ endpoint restrictions, placeholders, flexible configuration
5353
> We are slowly moving away from this README and instead are trying to make the [**Official Documentation**](https://codeshelldev.github.io/secured-signal-api) the only source of truth
5454
5555
- [Getting Started](#getting-started)
56-
- [Setup](#setup)
5756
- [Usage](#usage)
58-
- [Features](https://codeshelldev.github.io/secured-signal-api/docs/features)
57+
- [Features](#features)
5958
- [Configuration](#configuration)
60-
- [Endpoints](#endpoints)
61-
- [Variables](#variables)
62-
- [Field Policies](#field-policies)
63-
- [Field Mappings](#field-mappings)
64-
- [Message Templates](#message-templates)
59+
- [Endpoints Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/endpoints)
60+
- [Placeholder Variables](https://codeshelldev.github.io/secured-signal-api/docs/configuration/variables)
61+
- [Field Policies](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-policies)
62+
- [Field Mappings](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-mappings)
63+
- [Message Template](https://codeshelldev.github.io/secured-signal-api/docs/configuration/message-template)
6564
- [Port Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/port)
6665
- [Hostname Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/hostnames)
6766
- [IP Filter](https://codeshelldev.github.io/secured-signal-api/docs/configuration/ip-filter)
@@ -71,7 +70,7 @@ endpoint restrictions, placeholders, flexible configuration
7170
- [Log Level](https://codeshelldev.github.io/secured-signal-api/docs/configuration/log-level)
7271
- [Port](https://codeshelldev.github.io/secured-signal-api/docs/configuration/port)
7372
- [Hostnames](https://codeshelldev.github.io/secured-signal-api/docs/configuration/hostnames)
74-
- [Auth(-methods)](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)
73+
- [Auth Methods](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)
7574
- [Reverse Proxy](https://codeshelldev.github.io/secured-signal-api/docs/reverse-proxy)
7675
- [Integrations](https://codeshelldev.github.io/secured-signal-api/docs/integrations)
7776
- [Contributing](#contributing)
@@ -82,312 +81,25 @@ endpoint restrictions, placeholders, flexible configuration
8281

8382
## Getting Started
8483

85-
> **Prerequisites**: You need Docker and Docker Compose installed.
84+
### Installation
8685

87-
Get the latest version of the `docker-compose.yaml` file:
86+
{{{ #://docs/getting-started/installation.md }}}
8887

89-
```yaml
90-
{{{ #://../../docs/getting-started/examples/docker-compose.yaml }}}
91-
```
88+
### Setup
9289

93-
And add secure tokens to `api.tokens`. See [API Tokens](#api-tokens).
94-
95-
> [!IMPORTANT]
96-
> Here we'll use `sec-signal-api:8880` as the host,
97-
> but replace it with your actual container/host IP, port, or hostname
98-
99-
## Setup
100-
101-
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)
102-
103-
1. **Register** or **link** a Signal account with `signal-cli-rest-api`
104-
105-
2. Deploy `secured-signal-api` with at least one API token
106-
107-
3. Confirm you can send a test message (See [Usage](#usage))
108-
109-
> [!IMPORTANT]
110-
> Run setup directly with Signal CLI REST API.
111-
> Setup requests via Secured Signal API [are blocked by default](#endpoints)
90+
Once you have installed **Secured Signal API** you can [register or link a signal account](https://codeshelldev.github.io/secured-signal-api/docs/getting-started/setup).
11291

11392
## Usage
11493

115-
Secured Signal API provides 5 ways to authenticate
116-
117-
### Auth
118-
119-
| Method | Example |
120-
| :---------- | :----------------------------------------------------------------------------------------------------------- |
121-
| Bearer Auth | `Authorization: Bearer API_TOKEN` (header) |
122-
| Basic Auth | `Authorization: Basic base64(api:API_TOKEN)` (header)<br/>`http://api:API_TOKEN@host:port` (client specific) |
123-
| Query Auth | `http://host:port/abc?@auth=API_TOKEN` (query parameter) |
124-
| Path Auth | `http://host:port/@auth=API_TOKEN/abc` (path parameter) |
125-
| Body Auth | `auth: "API_TOKEN"` (request body field) |
126-
127-
> [!WARNING]
128-
> **Query** and **Path** auth are disabled by default and [must be enabled in the config](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)
129-
130-
### Example
131-
132-
To send a message to `+123400002`:
133-
134-
```bash
135-
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"message": "Hello World!", "recipients": ["+123400002"]}' http://sec-signal-api:8880/v2/send
136-
```
137-
138-
### Advanced
139-
140-
#### Placeholders
141-
142-
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.
143-
144-
**How to use:**
94+
{{{ #://docs/usage/index.md }}}
14595

146-
| Scope | Example | Note |
147-
| :--------------------- | :------------------ | :--------------- |
148-
| Body | `{{@data.key}}` | |
149-
| Header | `{{#Content_Type}}` | `-` becomes `_` |
150-
| [Variable](#variables) | `{{.VAR}}` | always uppercase |
96+
## Features
15197

152-
**Where to use:**
153-
154-
| Scope | Example |
155-
| :---- | :--------------------------------------------------------------- |
156-
| Body | `{"number": "{{ .NUMBER }}", "recipients": "{{ .RECIPIENTS }}"}` |
157-
| Query | `http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}` |
158-
| Path | `http://sec-signal-api:8880/v1/receive/{{.NUMBER}}` |
159-
160-
You can also combine them:
161-
162-
```json
163-
{
164-
"content": "{{.NUMBER}} -> {{.RECIPIENTS}}"
165-
}
166-
```
167-
168-
#### URL-to-Body Injection
169-
170-
In some cases you may not be able to access / modify the request body, in that case specify needed values in the request query or path:
171-
172-
`http://sec-signal-api:8880/@key2=value2/?@key=value`
173-
174-
> [!IMPORTANT]
175-
> To differentiate **injection queries** from _regular_ queries, **prefix the key with `@`**.
176-
> Only keys starting with `@` are injected into the request body.
177-
178-
> [!NOTE]
179-
>
180-
> - Supported value types include **strings**, **integers**, **arrays**, and **JSON objects**
181-
> - See [Formatting](https://codeshelldev.github.io/secured-signal-api/docs/usage/formatting) for details on supported structures and syntax
182-
183-
Supported [placeholder types](#placeholders):
184-
185-
| `.` Variables | `@` Body | `#` Headers |
186-
| ------------- | -------- | ----------- |
187-
| ❌ | ✅ | ❌ |
98+
{{{ #://docs/features/features.md }}}
18899

189100
## Configuration
190101

191-
There are multiple ways to configure Secured Signal API, you can optionally use `config.yml` as well as environment variables to override the config.
192-
193-
### Config Files
194-
195-
Config files allow **YAML** formatting and `${ENV}` to get environment variables.
196-
197-
To change the internal config file location set `CONFIG_PATH` in your **environment**. (default: `/config/config.yml`)
198-
199-
This example config shows all the individual settings that can be applied:
200-
201-
```yaml
202-
{{{ #://docs/configuration/examples/config.yml }}}
203-
```
204-
205-
#### Token Configs
206-
207-
You can also override the `config.yml` file for each individual token by adding configs under `TOKENS_PATH` (default: `config/tokens/`)
208-
209-
Here is an example:
210-
211-
```yaml
212-
{{{ #://docs/configuration/examples/token.yml }}}
213-
```
214-
215-
### API Tokens
216-
217-
During authentication Secured Signal API will try to match the given token against the list of tokens inside of the `api.tokens` (or [`api.auth.tokens`](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)) attribute.
218-
219-
```yaml
220-
api:
221-
tokens: [token1, token2, token3]
222-
```
223-
224-
> [!IMPORTANT]
225-
> Using API tokens is highly recommended, but not mandatory.
226-
> Some important security features won't be available (for example the [default blocked endpoints](#endpoints))
227-
228-
> [!NOTE]
229-
> Blocked endpoints can be reactivated by manually configuring them
230-
231-
### Endpoints
232-
233-
Because Secured Signal API also acts as a proxy you can use all the [Signal CLI REST API](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md) endpoints except for…
234-
235-
| Endpoint | |
236-
| :-------------------- | ------------------ |
237-
| **/v1/configuration** | **/v1/unregister** |
238-
| **/v1/devices** | **/v1/contacts** |
239-
| **/v1/register** | **/v1/accounts** |
240-
| **/v1/qrcodelink** | |
241-
242-
These endpoints are blocked by default due to security risks.
243-
244-
> [!IMPORTANT]
245-
>
246-
> 1. Matching uses [regex](https://regex101.com)
247-
> 2. On compile error exact match is used instead
248-
249-
> [!WARNING]
250-
> Remember that some symbols have special meanings in regex, a good rule of thumb is:
251-
>
252-
> - If it is a special character, it probably needs to be escaped (`/`) if you are not looking to use regex
253-
> - Otherwise test your pattern on a [regex testing site](https://regex101.com)
254-
255-
You can modify endpoints by configuring `access.endpoints` in your config:
256-
257-
```yaml
258-
settings:
259-
access:
260-
endpoints:
261-
- "!/v1/receive"
262-
- /v2/send
263-
```
264-
265-
By default adding an endpoint explicitly allows access to it, use `!` to block it instead.
266-
267-
> [!IMPORTANT]
268-
> When using `!` to block you must enclose the endpoint with quotes, like in the example above
269-
270-
| Allow | Block | Result |
271-
| ---------- | -------------- | ----------------------------------------- |
272-
| `/v2/send` | — | **Only** `/v2/send` allowed |
273-
| — | `!/v1/receive` | **All** allowed, **except** `/v1/receive` |
274-
| `/v2/send` | `!/v2/.*` | **Only** `/v2/send` allowed |
275-
276-
### Variables
277-
278-
Variables can be added under `variables` and can then be referenced in the body, query, or path.
279-
See [Placeholders](#placeholders).
280-
281-
> [!NOTE]
282-
> Variables are always converted into an **uppercase** string.
283-
> Example: `number` ⇒ `NUMBER` in `{{.NUMBER}}`
284-
285-
```yaml
286-
settings:
287-
message:
288-
variables:
289-
number: "+123400001",
290-
recipients: ["+123400002", "group.id", "user.id"]
291-
```
292-
293-
### Message Templates
294-
295-
To customize the `message` attribute you can use **Message Templates** to build your message by using other body keys and variables.
296-
Use `message.template` to configure:
297-
298-
```yaml
299-
settings:
300-
message:
301-
template: |
302-
Your Message:
303-
{{@message}}.
304-
Sent with Secured Signal API.
305-
```
306-
307-
Supported [placeholder types](#placeholders):
308-
309-
| `.` Variables | `@` Body | `#` Headers |
310-
| ------------- | -------- | ----------- |
311-
| ✅ | ✅ | ✅ |
312-
313-
### Field Policies
314-
315-
**Field Policies** allow for blocking or specifically allowing certain fields with set values from being used in the requests body or headers.
316-
317-
Configure them by using `access.fieldPolicies` like so:
318-
319-
```yaml
320-
settings:
321-
access:
322-
fieldPolicies:
323-
"@number":
324-
- value: "+123400002"
325-
action: block
326-
- value: "+123400003"
327-
action: block
328-
```
329-
330-
Set the wanted action on encounter, available options are `block` and `allow`.
331-
332-
> [!IMPORTANT]
333-
> String fields always try to use
334-
>
335-
> 1. [Regex matching](https://regex101.com)
336-
> 2. On compile error exact match is used as fallback
337-
338-
> [!WARNING]
339-
> Remember that some symbols have special meanings in regex, a good rule of thumb is:
340-
>
341-
> - If it is a special, it probably needs to be escaped (`/`) if you are not looking to use regex
342-
> - Otherwise test your pattern on a [regex testing site](https://regex101.com)
343-
344-
Supported [placeholder types](#placeholders):
345-
346-
| `.` Variables | `@` Body | `#` Headers |
347-
| ------------- | -------- | ----------- |
348-
| ❌ | ✅ | ✅ |
349-
350-
### Field Mappings
351-
352-
To improve compatibility with other services Secured Signal API provides **Field Mappings** and a built-in `message` mapping.
353-
354-
<details>
355-
<summary><strong>Default `message` mapping</strong></summary>
356-
357-
| Field | Score | Field | Score |
358-
| ------------ | ----- | ---------------- | ----- |
359-
| msg | 100 | data.content | 9 |
360-
| content | 99 | data.description | 8 |
361-
| description | 98 | data.text | 7 |
362-
| text | 20 | data.summary | 6 |
363-
| summary | 15 | data.details | 5 |
364-
| details | 14 | body | 2 |
365-
| data.message | 10 | data | 1 |
366-
367-
</details>
368-
369-
Secured Signal API will pick the best scoring field (if available) to set the key to the correct value from the request body.
370-
371-
Field Mappings can be added by setting `message.fieldMappings` in your config:
372-
373-
```yaml
374-
settings:
375-
message:
376-
fieldMappings:
377-
"@message":
378-
[
379-
{ field: "msg", score: 80 },
380-
{ field: "data.message", score: 79 },
381-
{ field: "array[0].message", score: 78 },
382-
]
383-
".NUMBER": [{ field: "phone_number", score: 100 }]
384-
```
385-
386-
Supported [placeholder types](#placeholders):
387-
388-
| `.` Variables | `@` Body | `#` Headers |
389-
| ------------- | -------- | ----------- |
390-
| ✅ | ✅ | ❌ |
102+
{{{ #://docs/configuration/index.md }}}
391103

392104
## Contributing
393105

0 commit comments

Comments
 (0)