Secure Proxy for Signal Messenger REST API

token-based authentication, endpoint restrictions, placeholders, flexible configuration

🔒 Secure · ⭐️ Configurable · 🚀 Easy to Deploy with Docker

Contents

Check out the official Documentation for up-to-date Instructions and additional Content.

• Getting Started
• Setup
• Usage
• Configuration
  • Endpoints
  • Variables
  • Field Policies
  • Field Mappings
  • Message Templates
• Integrations
• Contributing
• Support
• Help
• License

Getting Started

Prerequisites: You need Docker and Docker Compose installed.

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

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

  secured-signal:
    image: ghcr.io/codeshelldev/secured-signal-api:latest
    container_name: secured-signal
    environment:
      API__URL: http://signal-api:8080
      SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: "[+123400002, +123400003, +123400004]"
      SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001"
      API__TOKENS: "[LOOOOOONG_STRING]"
    ports:
      - "8880:8880"
    restart: unless-stopped
    networks:
      backend:
        aliases:
          - secured-signal-api

networks:
  backend:

And add secure Token(s) to api.tokens. See 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.

Setup

Before you can send messages via Secured Signal API you must first set up Signal rAPI

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)

Tip

Run setup directly with Signal rAPI. Setup requests via Secured Signal API are blocked. See Blocked Endpoints.

Usage

Secured Signal API provides 3 Ways to Authenticate

Auth

Method	Example
Bearer Auth	Add Authorization: Bearer API_TOKEN to headers
Basic Auth	Add Authorization: Basic BASE64_STRING (api:API_TOKEN)
Query Auth	Append @authorization=API_TOKEN to request URL

Example

To send a message to +123400002:

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

Advanced

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.

How to use:

Type	Example	Note
Body	{{@data.key}}
Header	{{#Content_Type}}	- becomes _
Variable	{{.VAR}}	always uppercase

Where to use:

Type	Example
Body	{"number": "{{ .NUMBER }}", "recipients": "{{ .RECIPIENTS }}"}
Query	http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}
Path	http://sec-signal-api:8880/v1/receive/{{.NUMBER}}

You can also combine them:

{
	"content": "{{.NUMBER}} -> {{.RECIPIENTS}}"
}

KeyValue Pair 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:

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.

Supported types include strings, ints, arrays and json dictionaries. See Formatting.

Configuration

There are multiple ways to configure Secured Signal API, you can optionally use config.yml aswell as Environment Variables to override the config.

Config Files

Config files allow YAML formatting and also ${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)

This example config shows all of the individual settings that can be applied:

# Example Config (all configurations shown)
service:
  port: 8880

api:
  url: http://signal-api:8080
  tokens: [token1, token2]

logLevel: info

settings:
  message:
    template: |
      You've got a Notification:
      {{@message}} 
      At {{@data.timestamp}} on {{@data.date}}.
      Send using {{.NUMBER}}.

    variables:
      number: "+123400001"
      recipients: ["+123400002", "group.id", "user.id"]

    fieldMappings:
      "@message": [{ field: "msg", score: 100 }]

  access:
    endpoints:
      - "!/v1/about"
      - /v2/send

    fieldPolicies:
      "@number": {
        value: "+123400003",
        action: block
      }

Token Configs

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, Placeholders, etc.

Here is an example:

tokens: [LOOOONG_STRING]

overrides:
  message:
    fieldMappings: # Disable Mappings
    variables: # Disable Placeholder

  access:
    endpoints: # Disable Sending
      - "!/v2/send"

Templating

Secured Signal API uses Golang's Standard Templating Library. 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
• Placeholders

This makes advanced Message Templates like this one possible:

settings:
  message:
    template: |
      {{- $greeting := "Hello" -}}
      {{ $greeting }}, {{ @name }}!
      {{ if @age -}}
      You are {{ @age }} years old.
      {{- else -}}
      Age unknown.
      {{- end }}
      Your friends:
      {{- range @friends }}
      - {{ . }}
      {{- else }}
      You have no friends.
      {{- end }}
      Profile details:
      {{- range $key, $value := @profile }}
      - {{ $key }}: {{ $value }}
      {{- end }}
      {{ define "footer" -}}
      This is the footer for {{ @name }}.
      {{- end }}
      {{ template "footer" . -}}
      ------------------------------------
      Content-Type: {{ #Content_Type }}
      Redacted Auth Header: {{ #Authorization }}

API Tokens

During Authentication Secured Signal API will try to match the given Token against the list of Tokens inside of these Variables.

api:
  tokens: [token1, token2, token3]

Important

Using API Tokens is highly recommended, but not mandatory. Some important Security Features won't be available (like default Blocked Endpoints).

Note

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 endpoints except for...

Endpoint
/v1/configuration	/v1/unregister
/v1/devices	/v1/contacts
/v1/register	/v1/accounts
/v1/qrcodelink

These Endpoints are blocked by default due to Security Risks.

Note

Matching uses glob-style patterns: * matches any sequence of characters, ? matches a single character and [abc] matches one of the characters in the brackets

You can modify endpoints by configuring access.endpoints in your config:

settings:
  access:
    endpoints:
      - "!/v1/register"
      - "!/v1/unregister"
      - "!/v1/qrcodelink"
      - "!/v1/contacts"
      - /v2/send

By default adding an endpoint explictly 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.

Config (Allow)	(Block)	Result
/v2/send	unset	all	🛑	/v2/send	✅
unset	!/v1/receive	all	✅	/v1/receive	🛑
!/v2*	/v2/send	/v2*	🛑	/v2/send	✅

Variables

Placeholders can be added under variables and can then be referenced in the Body, Query or URL. See Placeholders.

Note

Every Placeholder Key will be converted into an Uppercase String. Example: number becomes NUMBER in {{.NUMBER}}

settings:
  message:
    variables:
      number: "+123400001",
      recipients: ["+123400002", "group.id", "user.id"]

Message Templates

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:

settings:
  message:
    template: |
      Your Message:
      {{@message}}.
      Sent with Secured Signal API.

Message Templates support Standard Golang Templating. Use @data.key to reference Body Keys, #Content_Type for Headers and .KEY for Variables.

Field Policies

Field Policies allow for blocking or specifically allowing certain fields with set values from being used in the requests body or headers.

Configure them by using access.fieldPolicies like so:

settings:
  access:
    fieldPolicies:
      "@number": { value: "+123400002", action: block }

Set the wanted action on encounter, available options are block and allow.

Use @ for Body Keys and # for Headers.

Field Mappings

To improve compatibility with other services Secured Signal API provides Field Mappings and a built-in message Mapping.

Default `message` Mapping

Field	Score	Field	Score
msg	100	data.content	9
content	99	data.description	8
description	98	data.text	7
text	20	data.summary	6
summary	15	data.details	5
details	14	body	2
data.message	10	data	1

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:

settings:
  message:
    fieldMappings:
      "@message":
        [
          { field: "msg", score: 80 },
          { field: "data.message", score: 79 },
          { field: "array[0].message", score: 78 },
        ]
      ".NUMBER": [{ field: "phone_number", score: 100 }]

Use @ for mapping to Body Keys and . for mapping to Variables.

Contributing

Found a bug? Want to change or add something? Feel free to open up an Issue or create a Pull Request!

Support

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 Tab and ask for help.

We are all Volunteers, so please be friendly and patient.

License

MIT

Legal

Logo designed by @CodeShellDev, All Rights Reserved.

This Project is not affiliated with the Signal Foundation.