secured-signal-api

README

Secured Signal Api

Secured Signal Api acts as a secure proxy for signal-rest-api.

Installation

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

And set API_TOKEN to a long secure string

---
services:
  signal-api:
    image: bbernhard/signal-cli-rest-api
    container_name: signal-api
    environment:
      - MODE=normal
    volumes:
      - ./data:/home/.local/share/signal-cli
    networks:
      backend:
        aliases:
          - signal-api
    restart: unless-stopped

  secured-signal:
    image: ghcr.io/codeshelldev/secured-signal-api
    container_name: secured-signal
    networks:
      backend:
        aliases:
          - secured-signal-api
    environment:
      SIGNAL_API_URL: http://signal-api:8080
      DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]'
      SENDER: 123456789
      API_TOKEN: LOOOOOONG_STRING
    ports:
      - "8880:8880"
    restart: unless-stopped

networks:
  backend:

Reverse proxy

Take a look at traefik implementation:

services:
  # ...
  secured-signal:
    image: ghcr.io/codeshelldev/secured-signal-api
    container_name: secured-signal
    networks:
      proxy:
      backend:
        aliases:
          - secured-signal-api
    environment:
      SIGNAL_API_URL: http://signal-api:8080
      DEFAULT_RECIPIENTS: '[ "000", "001", "002" ]'
      SENDER: 123456789
      API_TOKEN: LOOOOOONG_STRING
    labels:
      - traefik.enable=true
      - traefik.http.routers.signal-api.rule=Host(`signal-api.mydomain.com`)
      - traefik.http.routers.signal-api.entrypoints=websecure
      - traefik.http.routers.signal-api.tls=true
      - traefik.http.routers.signal-api.tls.certresolver=cloudflare
      - traefik.http.routers.signal-api.service=signal-api-svc
      - traefik.http.services.signal-api-svc.loadbalancer.server.port=8880
      - traefik.docker.network=proxy
    restart: unless-stopped

networks:
  backend:
  proxy:
    external: true

Setup

Before you can send messages via secured-signal-api you must first setup signal-api,

to send messages you have to either:

• register a Signal Account

OR

• link Signal API to an already registered Signal Device

Usage

Secured Signal API implements 3 Ways to Authenticate

Bearer

To Authenticate with secured-signal-api add Authorization: Bearer TOKEN to your request Headers

Basic Auth

To use Basic Auth as Authorization Method add Authorization: Basic base64{user:pw} to your Headers

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.

Here is a simple example:

curl -X POST http://signal-api:8880/v2/send?@authorization=TOKEN

Example

To send a message to number: 1234567:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" -d '{"message": "Hello World!", "recipients": ["1234567"]}' http://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:

{{ .NUMBER }} or {{ .RECIPIENTS }}

These Placeholders can be used in the Query or the Body of a Request like so:

Body

{
	"number": "{{ .NUMBER }}",
	"recipients": "{{ .RECIPIENTS }}"
}

Query

http://.../?@number={{.NUMBER}}

Path

http://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:

http://signal-api:8880/?@key=value

Format In order to differentiate Injection Queries and regular Queries 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

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

[!NOTE] 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 endpoints with an Exception of:

• /v1/about

• /v1/configuration

• /v1/devices

• /v1/register

• /v1/unregister

• /v1/qrcodelink

• /v1/accounts

• /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

environment:
  BLOCKED_ENDPOINTS: '[ "/v1/register","/v1/unregister","/v1/qrcodelink","/v1/contacts" ]'

Variables

By default Secured Signal API provides the following Placeholders:

• NUMBER = ENV: SENDER
• RECIPIENTS = ENV: DEFAULT_RECIPIENTS

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

environment:
  VARIABLES: ' "NUMBER2": "002", "GROUP_CHAT_1": [ "user.id", "000", "001", "group.id" ] '

Default Recipients

Set this environment variable to automatically provide default Recipients:

environment:
  DEFAULT_RECIPIENTS: ' [ "user.id", "000", "001", "group.id" ] '

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

Secured Signal API will use the highest priority Message Alias to get 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:

environment:
  MESSAGE_ALIASES: ' [{ "alias": "note", "priority": 4 }, { "alias": "test", "priority": 3 }] '

Contributing

Found a bug? Want to change or add something? 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

License

MIT