# dsms

dsms is a TUI for receiving and sending SMS throught your Android phone.

![](assets/screenshot.png)

[![Build status](https://builds.sr.ht/~ser/dsms/.build.yml.svg)](https://builds.sr.ht/~ser/dsms/.build.yml?)
★ [Releases](https://downloads.ser1.net/software/dsms/)
★ [3-Clause BSD license](https://hg.sr.ht/~ser/dsms/browse/LICENSE?rev=tip)
★ [Changelog](https://hg.sr.ht/~ser/dsms/browse/CHANGELOG.md?rev=tip)
★ [Issues](https://todo.sr.ht/~ser/dsms)
★ [Mailing List](https://lists.sr.ht/~ser/dsms)  
[![Go Report Card](https://goreportcard.com/badge/ser1.net/dsms)](https://goreportcard.com/report/ser1.net/dsms)
★ [Software metrics](https://downloads.ser1.net/software/dsms/badges/METRICS.md)
★ ![Code complexity](https://downloads.ser1.net/software/dsms/badges/complexity.svg)
★ ![ABC metrics](https://downloads.ser1.net/software/dsms/badges/abc_score.svg)
★ ![Lines of code](https://downloads.ser1.net/software/dsms/badges/loc.svg)
★ ![Code linting](https://downloads.ser1.net/software/dsms/badges/linting.svg)
★ ![Code security](https://downloads.ser1.net/software/dsms/badges/vulnerabilities.svg)
★ ![Markdown linting](https://downloads.ser1.net/software/dsms/badges/readme_linting.svg)
★ ![Unit tests](https://downloads.ser1.net/software/dsms/badges/unit_tests.svg)

## Features

- Recieves and displays texts forwarded by the _SMS Forwarder_ Android app, available in F-Droid
- Sends texts via the _RestSMS_ Android app, available in F-Droid
- Presents a familiar chat view of texts
- Persists texts between runs
- Detects RestSMS if its running with Network Discovery Service enabled
- Registers itself as an SMS receiver under the instance name `dsms` on ZeroConf. Currently, this does nothing because SMS Forwarder doesn't look for receivers. But it's there in case it does, someday!

## Limitations

- Requires setting up two mobile apps
- Should really only be used on a LAN; neither _SMS Forwarder_ nor _RestSMS_ are big on security. In particular, while _RestSMS_ _does_ have token authentication, it's passed as an HTML parameter, which means it's visible to anyone sniffing network traffic. Over a VPN should be fine, but don't use this over an unsecured WAN. **https will not help you!!** http query parameters are always sent unencrypted. _SMS Forwarder_ has **no** authentication suppport, at all[^1]
- _dsms_ can only know about messages that are sent and received while it is running. _SMS Forwarder_ provides no way to get message history. Messages received while dsms is offline or inaccessible, or while _SMS Forwarder_ is stopped, will never reach _dsms_.
- _dsms_ does not have access to contact information, so you only see telephone numbers.
- This is a beta application. Creature comforts are missing.

## Requirements

For this to work, two applications need to be running on your phone. Both are available in F-Droid:

- [RestSMS](https://github.com/Xcreen/RestSMS), which runs a server on your phone that accepts HTTP requests, and sends texts. Ideally, when you set this up, go into the settings and turn on Network Discovery Service; this will make running `dsms` easier.
- [SMS Forward](https://gitlab.com/pierreduchemin/smsforward), which forwards SMS messages received on the phone to a web service.

dsms runs a web service for receiving texts forwarded by _SMS Forward_, provides a chat-like TUI for selecting numbers and viewing conversations, and allows you to type messages in and send them through _RestSMS_.

## Building

dsms is written in Go, and can be installed with the command:

```
  go install ser1.net/dsms@latest
```

Or this repository can be checked out and built on the command line:

```
  hg clone https://hg.sr.ht/~ser/dsms
  cd dsms
  go build .
```

## Running

There is a `-help` command that shows the options. There is also a (nearly identical) man page in the repository. The arguments that allow _dsms_ to talk to your phone are:

- `-listen` where you provide the interface and port to which _SMS Forward_ will send texts. You should be able to omit this one; by default, _dsms_ will listen on `0.0.0.0:9192`.
- Either `-restSmsUrl` needs to be provided (which includes the address of your phone), or RestSMS must have Network Service Discovery enabled, in which case you can use the `-a` flag. If you use the `restSmsUrl` argument, it is a full URL, including scheme and path: for example, `http://192.168.1.112:8090/send`.
- `-token` is a security token you configure in _RestSMS_, and provides security so that randos can't send texts. It's any string you set; it's basically a password. There are no restrictions set by _RestSMS_, so there are none in _dsms_

You'll configure where _SMS Forward_ sends texts in that app; it'll be the IP of your desktop, and whatever port you set on the _dsms_ command line. You'll have to figure out what your phone's IP on the LAN is, and configure _RestSMS_ with the port you want it to listen on and the secret token you'll pass to _dsms_.

There are other, optional, arguments which are described by `-help`.

You really should try to use the ZeroConf option; it's much more of a pain without it. If you are using it, `dsms` tries to be smart about finding RestSMS. If it loses connection with the phone -- for example if you leave and come home and your router gives your phone a new IP -- `dsms` will try to look up the RestSMS service again, trying 5 times before it gives up.

### Bindings

Eventually, there'll be a help dialog, access to log messages, ZeroConf refresh hotkeys, and probably a kitchen sink. In the meantime, the key bindings are:

- Ctrl-c will (cleanly) exit the program

#### contacts column

- up and down navigate the phone numbers
- Enter will load the stored conversation for that phone number
- Tab will load the conversation and focus the message entry field
- Right arrow will load the conversation and focus the chat history field

#### telephone number entry field

- Tab will activate the contacts pane
- Enter will activate the message entry field. If a new telephone number has been entered, it will be added to the contacts list.

#### chat history field

- Up and down will navigate the entries
- Tab will activate the contacts column
- Enter on a message opens up a diaog where you can see long-line messages

#### message dialog

- Esc closes the dialog
- Arrows scroll if it's _really_ long

#### message entry field

- Tab will activate the telephone number field
- Enter will send the text to the currently active contact

## Development

Issues are by-and-large embedded in the code. [legume](https://hg.sr.ht/~ser/legume) (in AUR) can be used to list and inspect the tickets; when the changelog is updated, the list also gets updated, but it may not be current.

There are no unit tests. Yet.

The change log is generated with [changelog](https://hg.sr.ht/~ser/changelog).

[^1]: This is not _strictly_ true. You could configure _SMS Forwarder_ with http BASIC authentication by configuring it with a URL such as `https://USER:PASS@YOURHOST.org/`. _dsms_ does not provide any support for authentication, nor even https -- if you _do_ ignore the warning about _RestSMS_'s security and use this on a WAN, then reverse proxy _dsms_ behind something like [Caddy](https://caddyserver.com), and do the SSL and authentication in Caddy.
