Out‑of‑band room invites for Matrix / Beeper – because good doors deserve a knock

Knock is a micro‑service that lets people request to join a private Matrix room without exposing the room address or relying on admins being online. Think of it as the digital equivalent of knocking on a closed door: the “knock” (invite request) happens out‑of‑band via a simple webhook form, while Knock takes care of validating, rate‑limiting, and delivering the Matrix invite on your behalf.

1. Architecture
2. Quick Start
3. Configuration
4. Running
5. API Reference
6. Background Tasks
7. Security Notes
8. Contributing
9. Roadmap
10. License

          ┌───────────────┐        (1) webhook
User ───▶ │  Form (Tally) │ ──────────────────┐
          └───────────────┘                   │
                                             ▼
                                        ┌─────────┐   HTTP  ❱❱❱❱❱
                                        │ Knock   │──────────────────┐
                                        │ FastAPI │                  │
                                        └─────────┘                  │
                               async tasks ▲  ▲ background   Matrix  │
                                            │  │                API  │
                                            │  │                      ▼
                              block‑list ✔  │  │ welcome msg ✔   ┌────────────┐
                                            │  │ invite / kick ✔  │    Room    │
                                            ▼  ▼                      └────────────┘
                              JSON / txt on disk (tokens, block‑list, pending‑invites)

• Invite flow:

  1. User submits matrix ID in a public form.
  2. Form platform POSTs to /invite_from_form.
  3. Knock validates, spam‑checks, and (if allowed) calls Matrix /invite.
  4. Once the user joins, Knock sends them a friendly welcome message.

• Admin actions:

  • /block_user, /unblock_user, /rescind_invite allow real‑time moderation.
  • CSV‑style files on disk keep state across restarts.

git clone https://github.com/your‑org/knock.git && cd knock
cp .env.example .env # then edit values

docker compose up -d

The service will be available on http://localhost:8000.

Add a form integration that POSTs its payload (unchanged!) to

POST http://localhost:8000/invite_from_form

That’s it – start sharing the form link instead of your room ID.

All configuration happens through environment variables; a dotenv file is recommended for local dev.

* If you already have long‑lived tokens you can instead set BEEPER_LOGIN_TOKEN and MATRIX_ACCESS_TOKEN and skip the email flow.

See docs/env_vars.md for the full matrix.

uvicorn mknock:app --reload --port 8000

[Service]
EnvironmentFile=/opt/knock/.env
ExecStart=/usr/local/bin/uvicorn mknock:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always

Health‑check endpoint: GET / → {"status":"running"}

All admin endpoints expect Authorization: Bearer <API_KEY> if API_KEY is set.

Both tasks run inside the same process – no external workers needed.

• Bearer auth – Set API_KEY to protect moderation endpoints.
• Stored credentials – Tokens are cached unencrypted in tokens.json; use file permissions or secrets mounts.
• Rate limits – Adjust REQUEST_DELAY, MAX_REQUESTS_PER_WINDOW, etc. to suit your traffic.
• Spoof protection – The invite flow validates that the MXID exists on the homeserver and matches a regex.

1. Fork the repo & create a branch.
2. Run make lint && make test – tests must pass.
3. Submit a pull‑request; describe why the change is needed.
4. Keep commits small & focused.

• Web UI for moderators.
• Redis / Postgres back‑ends (replace JSON + txt).
• Helm chart for Kubernetes.
• Support for non‑Beeper homeservers.