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:
@@ -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.
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user