aiolabs/maubot-plugins
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
11 commits 1 branch 0 tags 154 KiB
  • Python 100%
Find a file
Exact
Padreug d089a4b021 docs(spec): reframe identity model around operator-IdP + sidecar bunker 
Updates §7.2, §7.3, §12 to reflect the actual architecture from
aiolabs/lnbits#9 (reframed since the earlier commit) and #18 (the
concrete phase 2 bunker integration using nsecbunkerd).

Three shifts:

- LocalSigner demoted to transitional/migration helper. RemoteBunker
  Signer is the steady state for every bound user. New accounts MUST
  NOT default to LocalSigner. Earlier framing treated them as
  equivalent choices — they're not.

- Binding artifact is a per-device NIP-46 connection token with
  scoped permissions, not just a (mxid → user_id) mapping row. Calls
  out the security property: compromise of one client device
  (tracker, ATM, webapp) leaks only that token's scope, not the
  user's full identity. Revocation is one RPC at the bunker.

- §12 redrawn around the operator-IdP-with-sidecar-bunker pattern.
  Names nsecbunkerd as the canonical bunker for the aiolabs ref
  impl, points at #9 + #18 for the LNbits side. Pattern is reusable
  beyond LNbits — any operator providing identity-as-a-service can
  run this shape.

NIP-26 explicitly out (Nostr ecosystem has deprecated; NIP-46 covers
the use case). §11 open questions trimmed accordingly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 20:19:56 +02:00
docs docs(spec): reframe identity model around operator-IdP + sidecar bunker 2026-05-25 20:19:56 +02:00
journal docs: add umbrella + journal READMEs 2026-05-24 09:55:24 +02:00
tracker feat(tracker): Phase 1 plugin — Matrix + SQLite, rules-only 2026-05-24 15:48:21 +02:00
wiki feat(wiki): docs-lookup plugin against Quartz contentIndex 2026-05-24 16:40:11 +02:00
.gitignore feat(journal): farm-journal maubot plugin 2026-05-20 23:47:10 +02:00
CLAUDE.md docs: add community-organizer protocol spec 2026-05-24 15:12:37 +02:00
README.md feat(wiki): docs-lookup plugin against Quartz contentIndex 2026-05-24 16:40:11 +02:00

README.md

maubot-plugins

Umbrella for maubot plugins used by the aiolabs / Château du Faune Matrix stack. The maubot daemon itself is provisioned via server-deploy/modules/services/maubot.nix on the castle hosts; the actual plugin code lives here.

Plugins

Plugin Purpose
journal/ Farm-journal bot. !journal <text> records what you did, scoped per-user/room/timestamp. !journal show [@user] and !journal today query back.
tracker/ Community-organizer bot. !add / !task / !sidequest / !remind / !done / !list / !setup. Implements the Community Organizer spec — per-room shortcuts, 5-level priority, rules-based inbox classifier.
wiki/ Docs-lookup bot. !ask <query> / !doc <slug-or-title> / !wiki [refresh|status]. Points at any Quartz-rendered docs site (default: docs.ariege.io), full-text searches the corpus, replies with snippets + links. Internal-network deployment posture — works during WAN outages.

Community Organizer protocol

docs/community-organizer-spec.md defines the protocol the plugins in this repo (and companion renderers like inky-impression) use to coordinate community life — tasks, journals, reminders, shopping lists — over Matrix capture + Nostr storage. Designed to be adopted by other communities; reuses NIP-52 + NIP-72 instead of inventing new event kinds. Read it before changing verb behavior or event shapes in any plugin.

Building a plugin

A .mbp is just a zip containing maubot.yaml + the plugin's Python modules at the root. No special tooling needed:

cd <plugin>/
zip -j ../<plugin>.mbp maubot.yaml *.py

(-j strips the directory prefix so files land at the zip root.)

Uploading / iterating

  1. Open the maubot UI (e.g. https://maubot.<domain>/_matrix/maubot/).
  2. Plugins → + (first time) or click the existing plugin → upload the new .mbp. Maubot keys plugins by id; uploading a new version of the same id replaces the old one.
  3. Hit Save on the affected instance after upload — toggling Enabled without Save will revert. Easy facepalm.

Bump version: in maubot.yaml for every meaningful change so the maubot UI surfaces it cleanly and old .mbp files in /var/lib/maubot/plugins/ aren't ambiguous.

Bot account convention

Each plugin attaches to a Matrix client (a regular Matrix user account controlled by maubot). For the journal bot: @journalbot:ariege.io. Bot accounts are created the same way as any user — issue a registration token from the Continuwuity admin room (!admin token issue --once) and register through Element, then add the client in the maubot UI.

Invite the bot to whichever rooms it should serve via /invite @<bot>:<domain> — maubot's autojoin handles new invites that arrive after the client's sync loop is up.

Patterns + gotchas

Maubot-specific patterns (command decorators, multi-line caveats, database_type in maubot.yaml, etc.) live in ~/dev/CLAUDE.md under "Maubot plugin development". Read that before writing a new plugin — there are several footguns that look fine but silently lose data.