mirror of
https://github.com/kuhyx/signal-bot.git
synced 2026-11-21 18:52:29 +01:00
Per-person photo commands, where the mechanism is public and the album is not. Nothing identifying is in this repository: who the people are, what fires their photos and which file shows whom all live in one directory outside it, and the tests, the docs and the offline e2e run use three invented people instead. Several names in one message intersect -- "!alfa beta" is a photo with both -- and where an entry offers a choice the bot picks among the readings that actually have a photo, so a question the album could answer is not refused. A combination nobody photographed gets one line rather than silence, which from the group's side is indistinguishable from a broken bot. Scoping is enforced in the dispatcher, not in the handler: a command the group is not allowed resolves to nothing, so it is not answered, not counted as a command, and never named in a log line outside its own groups. A handler that quietly returned would leak all three. Commands are named by pseudonym (pack:p1), so the journal and command_uses say somebody asked for a photo and nothing about whose. Video works: the attachment goes out as data:video/mp4;filename=...;base64, which is the container's own spelling, read off its /swagger/doc.json. Told it is a photo, Signal renders a clip as an unplayable file. tool/tagger.py serves one page on loopback to fill the album in -- names are typed into the page, never as arguments, and it prints how many photos each command would have when it stops, because a command with zero is dead on arrival. Also renames the real people who were still sitting in the stats test fixtures. They remain in the history; the point is that nothing new is added to it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017w1HZ3cZ7neL3rFdQ6VMBA
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# The photo pack
|
||
|
||
A pack is a private album the bot posts from: `!alfa` returns a random photo
|
||
of alfa, and `!alfa beta` returns one with both of them on it.
|
||
|
||
**Nothing about a real pack is in this repository, and nothing ever will be.**
|
||
Who the people are, what somebody types to get their photo and which file
|
||
shows whom live in one directory outside the repo. This document, the tests
|
||
and the offline end-to-end run all use the same invented people — alfa, beta,
|
||
gamma — so the mechanism can be public while the album stays private.
|
||
|
||
## Where it lives
|
||
|
||
```
|
||
~/.local/share/signal-bot/pack/
|
||
people.json # the commands, and the only place names exist
|
||
tags.json # which file shows whom
|
||
media/ # the photos and videos themselves
|
||
```
|
||
|
||
Found in this order: `PHOTO_PACK_DIR`, then `$STATE_DIRECTORY/pack` (what
|
||
systemd hands a **system** unit), then `$XDG_DATA_HOME/signal-bot/pack`.
|
||
Under the *user* unit this repo installs, `StateDirectory=` would resolve
|
||
below `$XDG_STATE_HOME` rather than `$XDG_DATA_HOME`, so the deployed bot
|
||
names its pack outright in `.env` instead of relying on discovery.
|
||
|
||
Two absences, deliberately different:
|
||
|
||
- a pack **nobody named** that is not there, or that has no `people.json`
|
||
yet, is an installation without an album: the commands do not exist, and
|
||
that is the normal case on every machine and in the whole test suite;
|
||
- a pack named in `PHOTO_PACK_DIR` that is missing, or whose manifest cannot
|
||
be honoured, **fails startup**. `load_config` raising is an answer, and a
|
||
bot that came up healthy and said "no such photo" forever would not be.
|
||
|
||
## people.json
|
||
|
||
```json
|
||
{
|
||
"groups": ["group.WlRKbExYZGhkR05vWldRdA=="],
|
||
"people": [
|
||
{"key": "p1", "triggers": ["!alfa", "!alfka"]},
|
||
{"key": "p2", "triggers": ["!beta"]}
|
||
],
|
||
"combos": [
|
||
{"key": "c1", "triggers": ["!oboje"], "all_of": ["p1", "p2"]},
|
||
{"key": "c2", "triggers": ["!ktokolwiek"], "any_of": ["p1", "p2"]}
|
||
]
|
||
}
|
||
```
|
||
|
||
- **`groups` is the whole privacy guarantee.** In any other group these are
|
||
not commands at all: not answered, not counted as a command, not named in a
|
||
log line. A handler that quietly returned would still leak all three, which
|
||
is why the *dispatcher* enforces it — `registry.resolve_with_args` takes the
|
||
group and gives back nothing outside it.
|
||
- **`key` is a pseudonym**, and the only identifier that reaches the journal
|
||
or the `command_uses` table. A command is `pack:p1`; reading either says
|
||
somebody asked for a photo and nothing about whose.
|
||
- **`all_of` means one photo with all of them; `any_of` means either**, and
|
||
where a choice exists the bot picks among the readings that actually have a
|
||
photo, so a combination that could be answered is not refused.
|
||
- Triggers may not contain a digit — `folding.py` maps `0134578` onto letters,
|
||
so `!alfa7` is not what you typed. Two spellings that fold the same are fine
|
||
*within one entry* (`!ala`/`!ala` is one person written twice) and
|
||
refused across two.
|
||
|
||
## tags.json
|
||
|
||
```json
|
||
{"alfa.png": ["p1"], "both.png": ["p1", "p2"], "clip.mp4": ["p1"]}
|
||
```
|
||
|
||
A tag naming a file that is not in `media/` fails startup: a renamed file
|
||
would otherwise drop out of the album in silence. An empty list means "seen,
|
||
nobody in it", which is how the tagger records a photo you skipped.
|
||
|
||
Videos work. The attachment goes out as
|
||
`data:video/mp4;filename=<name>;base64,<data>` — the spelling is the
|
||
container's own, from its `/swagger/doc.json` — because told it is a photo,
|
||
Signal renders a clip as a file nobody can play.
|
||
|
||
## Filling it in: tool/tagger.py
|
||
|
||
```sh
|
||
python tool/tagger.py --import ~/photos # copy the files in, then tag
|
||
python tool/tagger.py # carry on where you left off
|
||
```
|
||
|
||
It serves one page on `127.0.0.1:8140`: the item, a numbered button per
|
||
person, `1`–`9` to toggle, `→`/`←` to move. Every toggle rewrites `tags.json`
|
||
atomically, so closing the tab loses nothing. Names are typed **into the
|
||
page**, never as arguments — an argument would land in the shell history —
|
||
and the group is picked from the live `/v1/groups` listing rather than pasted.
|
||
|
||
When you stop it, it prints how many items were never opened and how many
|
||
photos each command would have. **A command showing `0` is dead on arrival**;
|
||
that is the number to check before restarting the bot, not after somebody in
|
||
the group tries it.
|
||
|
||
## Running the mechanism without an album
|
||
|
||
`scripts/e2e.sh` writes a synthetic pack with `tool/e2e_pack.py` and proves,
|
||
offline and with no Signal account, that one name posts a photo, two names
|
||
intersect, an impossible combination gets one line and no attachment, a video
|
||
leaves as a video, and the same command in another group produces **zero**
|
||
sends.
|