bzl

self-hosted ephemeral community engine
Log | Files | Refs | README | LICENSE

DIRECTORY_SPEC.md (2802B)

      1 # Directory plugins (draft)
      2 
      3 Goal: make `chat.bzl.one` (or any chosen “directory instance”) show a list of other Bzl instances + links, without requiring account crossover.
      4 
      5 This spec intentionally splits responsibilities:
      6 - **`directory-server`** (install only on the directory instance) receives announcements and serves a directory feed.
      7 - **`directory-publisher`** (install on any instance that wants to be listed) announces its instance info to the directory.
      8 
      9 ## Trust + safety model
     10 
     11 Directory listings are a spam magnet unless you add a trust gate.
     12 
     13 Baseline (simple + good enough for MVP):
     14 - Directory has a **shared secret** (`token`) required for announcements.
     15 - Publishers include the token as `Authorization: Bearer <token>` (or `X-Bzl-Directory-Token`).
     16 - Directory can still **hide/block** entries via in-plugin config (manual moderation).
     17 
     18 Future upgrade (better):
     19 - Per-instance tokens issued by the directory (claim flow).
     20 - Optional “verified domain” proof (e.g. DNS TXT, or hosting a token at `/.well-known/...`).
     21 
     22 ## Data model
     23 
     24 ### Announcement payload (publisher → directory)
     25 
     26 `POST /api/plugins/directory-server/announce`
     27 
     28 ```json
     29 {
     30   "instance": {
     31     "id": "temple",
     32     "url": "https://temple.azakaela.com",
     33     "name": "Temple",
     34     "description": "Cozy small-town chat",
     35     "bzlVersion": "0.1.0",
     36     "requiresRegistrationCode": false
     37   },
     38   "publicHives": [
     39     {
     40       "title": "Announcements",
     41       "url": "https://temple.azakaela.com/#/hive/announcements",
     42       "description": "What’s new",
     43       "tags": ["news"]
     44     }
     45   ]
     46 }
     47 ```
     48 
     49 Notes:
     50 - `instance.id` is stable, unique within the directory.
     51 - `publicHives` is **opt-in**. Default should be empty.
     52 
     53 ### Directory entry (stored by directory)
     54 
     55 ```json
     56 {
     57   "instance": { "...": "..." },
     58   "publicHives": [ "..."],
     59   "lastSeenAt": 1700000000000
     60 }
     61 ```
     62 
     63 ## Endpoints (directory-server)
     64 
     65 - `POST /api/plugins/directory-server/announce`
     66   - Auth: `Authorization: Bearer <token>` OR `X-Bzl-Directory-Token: <token>`
     67   - Stores/updates the entry and updates `lastSeenAt`.
     68 
     69 - `GET /api/plugins/directory-server/list`
     70   - Public JSON feed consumed by:
     71     - the directory UI (in-app plugin UI), and/or
     72     - external tooling.
     73 
     74 ## UX (directory instance)
     75 
     76 Minimum viable UX:
     77 - A “Directory” view that’s optionally shown first.
     78 - Each entry shows: name, description, URL, “last seen”.
     79 - Optional “Public hives” collapsible list under each entry.
     80 - Owner controls:
     81   - Set token
     82   - Hide entry
     83   - Block hostname/instance id
     84 
     85 ## Publisher behavior
     86 
     87 Publisher plugin should support:
     88 - “Publish now” button (owner only)
     89 - Auto-publish heartbeat every N minutes (default 10–30m)
     90 - Local config:
     91   - directory URL
     92   - token
     93   - instance metadata (name/description/url)
     94   - list of public hive links
     95