Repository files navigation

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

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

Check out the officialDocumentation 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

Prerequisites: You need Docker and Docker Compose installed.

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

services:signal-api:image:bbernhard/signal-cli-rest-api:latestcontainer_name:signal-apienvironment:      -MODE=normalvolumes:      -./data:/home/.local/share/signal-clirestart:unless-stoppednetworks:backend:aliases:          -signal-apisecured-signal:image:ghcr.io/codeshelldev/secured-signal-api:latestcontainer_name:secured-signalenvironment:API__URL:http://signal-api:8080SETTINGS__MESSAGE__VARIABLES__RECIPIENTS:"[+123400002, +123400003, +123400004]"SETTINGS__MESSAGE__VARIABLES__NUMBER:"+123400001"API__TOKENS:"[LOOOOOONG_STRING]"ports:      -"8880:8880"restart:unless-stoppednetworks:backend:aliases:          -secured-signal-apinetworks:backend:

And add secure Token(s) toapi.tokens. SeeAPI TOKENs.

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

1. Register orlink a Signal account withsignal-cli-rest-api

2. Deploysecured-signal-api with at least one API token

3. Confirm you can send a test message (seeUsage)

Secured Signal API provides 3 Ways to Authenticate

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

If you are not comfortable / don't want to hardcode your Number for example and/or Recipients in you, may usePlaceholders in your Request.

How to use:

Where to use:

You can also combine them:

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

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 andregular Queriesyou have to add@ in front of any KeyValue Pair assignment.

Supported types includestrings,ints,arrays andjson dictionaries. SeeFormatting.

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

Config files allowYAML formatting and also${ENV} to get Environment Variables.

To change the internal config file location setCONFIG_PATH in yourEnvironment 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:8880api:url:http://signal-api:8080tokens:[token1, token2]logLevel:infosettings: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/sendfieldPolicies:"@number":{value:"+123400003",action:block}

You can also override theconfig.yml file for each individual token by adding configs underTOKENS_PATH (default:config/tokens/)

This way you can permission tokens by further restricting or addingEndpoints,Placeholders, etc.

Here is an example:

tokens:[LOOOONG_STRING]overrides:message:fieldMappings:# Disable Mappingsvariables:# Disable Placeholderaccess:endpoints:# Disable Sending      -"!/v2/send"

Secured Signal API uses Golang'sStandard 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 advancedMessage 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 }}

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]

Since Secured Signal API is just a Proxy you can use all of theSignal REST API endpoints except for...

These Endpoints are blocked by default due to Security Risks.

You can modify endpoints by configuringaccess.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.

Placeholders can be added undervariables and can then be referenced in the Body, Query or URL.SeePlaceholders.

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

To customize themessage attribute you can useMessage Templates to build your message by using other Body Keys and Variables.Usemessage.template to configure:

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

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

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 usingaccess.fieldPolicies like so:

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

Set the wanted action on encounter, available options areblock andallow.

Use@ for Body Keys and# for Headers.

To improve compatibility with other services Secured Signal API providesField Mappings and a built-inmessage Mapping.

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 settingmessage.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.

Found a bug? Want to change or add something?Feel free to open up anIssue or create aPull Request!

Has this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project.

:)

Are you having Problems setting up Secured Signal API?
No worries check out theDiscussions Tab and ask for help.

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

MIT

Logo designed by@CodeShellDev, All Rights Reserved.

This Project is not affiliated with the Signal Foundation.