Skip to content

Commit e9ca933

Browse files
CodeShellDevCodeShellDev
authored
Merge pull request #14 from CodeShellDev/main
Update Dev
2 parents d439a1c + dee80c1 commit e9ca933

File tree

5 files changed

+186
-106
lines changed

5 files changed

+186
-106
lines changed

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

Lines changed: 90 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,100 @@
1-
# Secured Signal Api
1+
# Secured Signal API
22

3-
Secured Signal Api acts as a secure proxy for signal-rest-api.
3+
Secured Signal API acts as a secure proxy for [Signal rAPI](https://github.com/bbernhard/signal-cli-rest-api).
44

55
## Installation
66

77
Get the latest version of the `docker-compose.yaml` file:
88

9-
And set `API_TOKEN` to a long secure string
9+
And set `API_TOKEN` to a long secure string.
10+
11+
> [!IMPORTANT]
12+
> This Documentation will be using `sec-signal-api:8880` as the service host,
13+
> this **won't work**, instead use your containers IP + Port.
14+
> Or a hostname if applicable. See [Reverse Proxy](#reverse-proxy)
1015
1116
```yaml
1217
{ { file.docker-compose.yaml } }
1318
```
1419

1520
### Reverse proxy
1621

17-
Take a look at traefik implementation:
22+
Take a look at the [traefik](https://github.com/traefik/traefik) implementation:
1823

1924
```yaml
2025
{ { file.examples/traefik.docker-compose.yaml } }
2126
```
2227

2328
## Setup
2429

25-
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),
30+
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)
2631

27-
to send messages you have to either:
32+
To be able to use the API you have to either:
2833

29-
- **register a Signal Account**
34+
- **register with your Signal Account**
3035

3136
OR
3237

3338
- **link Signal API to an already registered Signal Device**
3439

40+
> [!TIP]
41+
> It is advised to do Setup directly with Signal rAPI
42+
> if you try to Setup with Secured Signal API you will be blocked from doing so. See [Blocked Endpoints](#blocked-endpoints).
43+
3544
## Usage
3645

37-
Secured Signal API implements 3 Ways to Authenticate
46+
Secured Signal API provides 3 Ways to Authenticate
3847

3948
### Bearer
4049

41-
To Authenticate with `secured-signal-api` add `Authorization: Bearer TOKEN` to your request Headers
50+
To Authenticate add `Authorization: Bearer API_TOKEN` to your request Headers
4251

4352
### Basic Auth
4453

45-
To use Basic Auth as Authorization Method add `Authorization: Basic base64{user:pw}` to your Headers
54+
To use Basic Auth as Authorization Method add `Authorization: Basic BASE64_STRING` to your Headers
55+
56+
User is `api` (LOWERCASE)
57+
58+
Formatting for `BASE64_STRING` = `user:API_KEY`.
59+
60+
example:
61+
62+
```bash
63+
echo "api:API_KEY" | base64
64+
```
65+
66+
=> `YXBpOkFQSV9LRVkK`
4667

4768
### Query Auth
4869

4970
If you are working with a limited Application you may **not** be able to modify Headers or the Request Body
50-
in this case you should use **Query Auth**.
71+
in this case you can use **Query Auth**.
5172

5273
Here is a simple example:
5374

5475
```bash
55-
curl -X POST http://signal-api:8880/v2/send?@authorization=TOKEN
76+
curl -X POST http://sec-signal-api:8880/v2/send?@authorization=API_TOKEN
5677
```
5778

79+
Notice the `@` infront of `authorization`. See [Formatting](#format)
80+
5881
### Example
5982

60-
To send a message to `number`: `1234567`:
83+
To send a message to 1234567:
6184

6285
```bash
63-
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://signal-api:8880/v2/send
86+
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
6487
```
6588

6689
### Advanced
6790

6891
#### Placeholders
6992

70-
If you are not comfortable with hardcoding your Number and/or Recipients in you may use **Placeholders** in your request like:
93+
If you are not comfortable / don't want to hardcode your Number and/or Recipients in you may use **Placeholders** in your Request.
7194

72-
`{{ .NUMBER }}` or `{{ .RECIPIENTS }}`
95+
Built-in Placeholders: `{{ .NUMBER }}` and `{{ .RECIPIENTS }}`
7396

74-
These _Placeholders_ can be used in the Query or the Body of a Request like so:
97+
These Placeholders can be used in the Request Query or the Body of a Request like so:
7598

7699
**Body**
77100

@@ -85,45 +108,46 @@ These _Placeholders_ can be used in the Query or the Body of a Request like so:
85108
**Query**
86109

87110
```
88-
http://.../?@number={{.NUMBER}}
111+
http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}
89112
```
90113

91114
**Path**
92115

93116
```
94-
http://signal-api:8880/v1/receive/{{.NUMBER}}
117+
http://sec-signal-api:8880/v1/receive/{{.NUMBER}}
95118
```
96119

97120
#### KeyValue Pair Injection
98121

99-
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:
122+
In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query:
100123

101124
```
102-
http://signal-api:8880/?@key=value
125+
http://sec-signal-api:8880/?@key=value
103126
```
104127

105-
**Format**
128+
##### Format
129+
106130
In order to differentiate Injection Queries and _regular_ Queries
107-
you have to add `@` in front of any KeyValue Pair assignment
131+
you have to add `@` in front of any KeyValue Pair assignment.
108132

109133
### Environment Variables
110134

111135
#### API Token
112136

113137
> [!IMPORTANT]
114-
> It is highly recommended to set this Environment Variable to a long secure string
138+
> It is highly recommended to set this Environment Variable
115139
116-
_What if I just don't?_
140+
> _What if I just don't?_
117141
118-
Well Secured Signal API will still work, but important Security Features won't be available
119-
like Blocked Endpoints and anyone with access to your Docker Container will be able to send Messages in your Name
142+
Well, Secured Signal API will still work, but important Security Features won't be available
143+
like Blocked Endpoints and any sort of Auth.
120144

121145
> [!NOTE]
122-
> Blocked Endpoints can be reactivated by manually setting them in the environment
146+
> Blocked Endpoints can be reactivated by manually setting them in the Environment
123147
124148
#### Blocked Endpoints
125149

126-
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:
150+
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...
127151

128152
- **/v1/about**
129153

@@ -141,7 +165,7 @@ Because Secured Signal API is just a secure Proxy you can use all of the [Signal
141165

142166
- **/v1/contacts**
143167

144-
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
168+
These Endpoints are blocked by default due to Security Risks, but can be modified by setting `BLOCKED_ENDPOINTS` to a valid json array string
145169

146170
```yaml
147171
environment:
@@ -150,46 +174,56 @@ environment:
150174
151175
#### Variables
152176
153-
By default Secured Signal API provides the following **Placeholders**:
177+
By default Secured Signal API provides the following Placeholders:
178+
179+
- **NUMBER** = _ENV_: `NUMBER`
180+
- **RECIPIENTS** = _ENV_: `RECIPIENTS`
154181

155-
- **NUMBER** = _ENV_: `SENDER`
156-
- **RECIPIENTS** = _ENV_: `DEFAULT_RECIPIENTS`
182+
#### Customization
157183

158-
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
184+
Placeholders can be added by setting `VARIABLES` inside your Environment.
159185

160186
```yaml
161187
environment:
162188
VARIABLES: ' "NUMBER2": "002", "GROUP_CHAT_1": [ "user.id", "000", "001", "group.id" ] '
163189
```
164190

165-
#### Default Recipients
191+
#### Recipients
166192

167-
Set this environment variable to automatically provide default Recipients:
193+
Set this Environment Variable to automatically provide default Recipients:
168194

169195
```yaml
170196
environment:
171-
DEFAULT_RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] '
197+
RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] '
198+
```
199+
200+
example:
201+
202+
```json
203+
{
204+
"recipients": "{{.RECIPIENTS}}"
205+
}
172206
```
173207

174208
#### Message Aliases
175209

176210
To improve compatibility with other services Secured Signal API provides aliases for the `message` attribute by default:
177211

178-
| Alias | Priority |
179-
| ----------- | ----------- |
180-
| msg | 100 |
181-
| content | 99 |
182-
| description | 98 |
183-
| text | 20 |
184-
| body | 15 |
185-
| summary | 10 |
186-
| details | 9 |
187-
| payload | 2 |
188-
| data | 1 |
212+
| Alias | Priority |
213+
| ----------- | -------- |
214+
| msg | 100 |
215+
| content | 99 |
216+
| description | 98 |
217+
| text | 20 |
218+
| body | 15 |
219+
| summary | 10 |
220+
| details | 9 |
221+
| payload | 2 |
222+
| data | 1 |
189223

190-
Secured Signal API will use the highest priority Message Alias to get the correct message from the Request Body.
224+
Secured Signal API will use the highest priority Message Alias to extract the correct message from the Request Body.
191225

192-
If you are missing a Message Alias to have Secured Signal API integrated with a Service you can simply set `MESSAGE_ALIASES` in ENV:
226+
Message Aliases can be added by setting `MESSAGE_ALIASES`:
193227

194228
```yaml
195229
environment:
@@ -203,6 +237,12 @@ Feel free to open up an issue or create a Pull Request!
203237

204238
_This is a small project so don't expect any huge changes in the future_
205239

240+
## Support
241+
242+
Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project.
243+
244+
:)
245+
206246
## License
207247

208248
[MIT](https://choosealicense.com/licenses/mit/)

0 commit comments

Comments
 (0)