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
+12
View File
@@ -99,10 +99,22 @@ signal-cal-bot --config config.toml --once # one tick
- **Schema change**: append to `SCHEMA` in `store.py`. There is no migration - **Schema change**: append to `SCHEMA` in `store.py`. There is no migration
framework; deleting `data/signal-cal-bot.sqlite3` re-seeds silently. framework; deleting `data/signal-cal-bot.sqlite3` re-seeds silently.
## Changelog
`CHANGELOG.md` is Keep-a-Changelog format. For anything a user of the bot would
notice — behaviour, configuration, CLI, operational requirements — add a bullet
under `## [Unreleased]` in the right group (`Added`, `Changed`, `Fixed`,
`Removed`). Internal refactors and test-only changes do not need entries.
Never create version headings. No stable release exists yet; versions are cut
only when a release is actually deployed, by renaming Unreleased to
`## [x.y.z] - YYYY-MM-DD`.
## Before you finish ## Before you finish
- `pytest` green, `python -m pyflakes src tests` clean. - `pytest` green, `python -m pyflakes src tests` clean.
- New behaviour covered by a test (especially failure paths). - New behaviour covered by a test (especially failure paths).
- User-visible changes have a `CHANGELOG.md` entry under `## [Unreleased]`.
- `config.example.toml`, README and AGENTS.md still accurate. - `config.example.toml`, README and AGENTS.md still accurate.
- `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or - `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or
`signal-data/` files. `signal-data/` files.
+52
View File
@@ -0,0 +1,52 @@
# Changelog
All notable changes to this project are documented in this file. The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
project will use [Semantic Versioning](https://semver.org/) once it starts
releasing.
No stable release has been made yet: every change accumulates under
Unreleased. To make the first release, rename that section to
`## [0.1.0] - YYYY-MM-DD` and start a fresh Unreleased above it.
## [Unreleased]
### Added
- iCalendar feed polling with conditional requests (ETag/Last-Modified);
validators are only committed after a successful parse.
- Event parsing and expansion, including The Events Calendar series detection:
announcements are deduplicated per series, not per occurrence.
- Two posts per event: an announcement when it is first seen, and a reminder
three days before it starts, with a morning-of fallback for events added
less than three days ahead.
- Preferred posting windows with an urgent guard that posts early rather than
after the event has started.
- Batched sending: everything due in a window becomes one message.
- Poster images from the feed's `ATTACH` property, falling back to the event
page's `og:image` / JSON-LD; images are downscaled, cached and attached as
base64 data URIs.
- Event-page scraping for venue name and postcode, cached per URL.
- Watchdog alerts to the operator's own number when the feed or sending fails.
- CLI with run loop, `--once`, `--dump` and `--check`.
- Docker Compose setup pairing the bot with `signal-cli-rest-api`, including
headless device-linking and dedicated-number registration instructions.
- Offline test suite; AGENTS.md; GPL-3.0-or-later licensing; provenance
disclaimer.
### Changed
- Renamed from `calbot` to `signal-cal-bot`: Python package
`signal_cal_bot`, CLI `signal-cal-bot`, environment variables
`SIGNAL_CAL_BOT_*`, database `data/signal-cal-bot.sqlite3`.
### Fixed
- Connection errors while sending no longer bypass the watchdog.
- Image decoding failures, including decompression bombs, can no longer block
the text post or wedge the outbox.
- Reminders are dropped for events removed from the feed, using the feed's
coverage horizon so the 30-event export cap does not cancel future events.
- Transparent images are composited onto white instead of turning black.
- `--dump` uses a temporary database and no longer touches real state.
- Duplicate postcode no longer appears when the venue name already contains it.
+97 -9
View File
@@ -1,13 +1,18 @@
# sigcal-bot — iCal → Signal # 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) > **Disclaimer:** this code was generated by LLMs (several different models)
> and has not been audited by a human security professional. Review it before > 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 > relying on it, especially before exposing the Signal API, and treat it as
> provided without warranty. See [Provenance](#provenance). > 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 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 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. 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 ```bash
mkdir -p signal-data data cache mkdir -p signal-data data cache
docker compose up -d signal-api docker compose up -d signal-api
``` ```
Open <http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot> and scan it from The API listens on `127.0.0.1:8080` only (see `docker-compose.yml`), so it is
**Signal → Settings → Linked devices**. 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**. There are two ways to give the bot a Signal identity.
> For a separate identity, register a dedicated number instead (see the
> `signal-cli-rest-api` docs on `/v1/register`).
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 ```bash
curl -s http://localhost:8080/v1/accounts curl -s http://localhost:8080/v1/accounts
curl -s http://localhost:8080/v1/groups/+447700900000 | jq -r '.[].internal_id' 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 ### 2. Configure
```bash ```bash
@@ -205,6 +291,8 @@ an audited library:
particularly around network failure modes. particularly around network failure modes.
- Treat the defaults, comments and claims here as best effort. Verify behaviour - 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. 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 ## Limitations