Document headless linking, dedicated identity and alpha status

- README: SSH-tunnel and QR-as-file linking for headless servers
- README: dedicated-number registration path for a separate bot identity
- README: alpha-quality notice, provenance caveat, non-affiliation
- add CHANGELOG.md (Keep a Changelog, everything under Unreleased)
- AGENTS.md: require Unreleased changelog entries
This commit is contained in:
2026-11-18 17:06:18 +00:00
parent f97d0f2e09
commit f6d0db664e
3 changed files with 161 additions and 9 deletions
+97 -9
View File
@@ -1,13 +1,18 @@
# sigcal-bot — iCal → Signal
> **Alpha software.** This project is alpha quality and has never had a stable
> release. Behaviour, configuration keys and defaults may change without
> notice between commits, and it has not run in a real group for long. Watch
> the first weeks of posts closely.
>
> **Disclaimer:** this code was generated by LLMs (several different models)
> and has not been audited by a human security professional. Review it before
> relying on it, especially before exposing the Signal API, and treat it as
> provided without warranty. See [Provenance](#provenance).
>
> In general, we reccomend using a fresh Signal identity that is only used for Sigcal bot.
> In general, we recommend using a fresh Signal identity that is only used for sigcal-bot.
>
> This project is independant of and not accosiated with Signal, the 501c3 nonprofit.
> This project is independent of and not associated with Signal, the 501(c)(3) nonprofit.
Polls an iCalendar feed and posts events to a Signal group, with the event's
poster image attached. Built for [Commons Calendar ical feed](https://commonscalendar.uk) (The
@@ -78,27 +83,108 @@ committing can duplicate exactly one post.
Requirements: Docker (and Docker Compose). A Signal account to link.
### 1. Start signal-cli-rest-api and link a device
### 1. Start signal-cli-rest-api and give the bot an identity
```bash
mkdir -p signal-data data cache
docker compose up -d signal-api
```
Open <http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot> and scan it from
**Signal → Settings → Linked devices**.
The API listens on `127.0.0.1:8080` only (see `docker-compose.yml`), so it is
reachable from the server itself or through an SSH tunnel — not the network.
Keep it that way: anyone who can reach it can send messages as the account.
> Linking as a secondary device means the bot posts **as your own number**.
> For a separate identity, register a dedicated number instead (see the
> `signal-cli-rest-api` docs on `/v1/register`).
There are two ways to give the bot a Signal identity.
Fetch the linked number and the group ID:
#### A. Link to your own account (default, quickest)
The bot becomes a linked device of your phone, like Signal Desktop, and every
post appears **as your number**. There is nothing to register — you scan a QR
code once.
**Linking on a headless server.** `/v1/qrcodelink` returns a QR *image* that
the phone must scan, and the server has no browser. Either:
- **SSH tunnel (easiest).** From your laptop:
```bash
ssh -L 8080:localhost:8080 you@server
```
Then open <http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot>
in your local browser and scan it from
**Signal → Settings → Linked devices → +**.
- **Fetch the QR as a file.** On the server:
```bash
curl -s "http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot" \
-o /tmp/link-qr.png
```
Copy it somewhere with a screen (`scp server:/tmp/link-qr.png .`, or
`ssh server cat /tmp/link-qr.png > link-qr.png`), display it, and scan it
with the phone. The QR rotates on every request and the link session is
short-lived: if the scan fails, request a fresh one. Delete the file
afterwards.
Then read back the number and the group ID:
```bash
curl -s http://localhost:8080/v1/accounts
curl -s http://localhost:8080/v1/groups/+447700900000 | jq -r '.[].internal_id'
```
#### B. Register a dedicated number (separate bot identity)
Linking means every post looks like *you* wrote it. For a community group it is
often better to give the bot its own Signal account — its own name and avatar,
not tied to any member, so people do not mistake reminders for a person
speaking, and the bot can be handed over without touching anyone's phone.
You need a number that can receive an SMS or voice call. A spare SIM or
pay-as-you-go eSIM works; Signal blocks most VoIP providers (Twilio and
similar), so do not plan around one.
1. Signal requires a captcha for registrations made from a server. Open
<https://signalcaptchas.org/registration/generate.html> in a browser, open
the developer console, and find the blocked navigation to
`signalcaptcha://{value}` — copy everything after `signalcaptcha://`.
2. Register the number with that captcha:
```bash
curl -X POST -H "Content-Type: application/json" \
-d '{"captcha":"<captcha value>"}' \
'http://localhost:8080/v1/register/+447700900123'
```
Add `"use_voice": true` to receive the code by voice call instead of SMS.
3. Enter the code you receive:
```bash
curl -X POST 'http://localhost:8080/v1/register/+447700900123/verify/123-456'
```
4. Give the account a recognisable name and avatar through the profile endpoint
(see the [API docs](https://bbernhard.github.io/signal-cli-rest-api/)).
5. Have a group admin **add the bot's number to the group like a normal
contact** (do not try to link it as a device). Then fetch the group ID with
the bot's number:
```bash
curl -s http://localhost:8080/v1/groups/+447700900123 | jq -r '.[].internal_id'
```
Caveats for the dedicated-number route:
- The registration lives in `signal-data/`. Losing it **loses the account**:
there is no phone to re-link from, and re-registering needs a new captcha and
sometimes a cooldown.
- Signal reclaims numbers that go unused for a long time. If the calendar might
be quiet for months, enable `watchdog.daily_heartbeat` so the account keeps
some activity.
- The bot's number is visible to every member of the group.
### 2. Configure
```bash
@@ -205,6 +291,8 @@ an audited library:
particularly around network failure modes.
- Treat the defaults, comments and claims here as best effort. Verify behaviour
against your own feed and Signal setup before relying on it in production.
- The project is **alpha** and unreleased: expect breaking changes, and do not
treat any config key or default as stable until a version is tagged.
## Limitations