Broker Quick Start (For Contributors)

Get up and running with Broker development in 10 minutes. If you're short on time, this page is enough to get started; for details refer to the Broker Development Tutorial and Broker Architecture.

---

1. 10-Minute Getting Started

1.1 Generate Author Key (One-Time)

python main.py broker keygen --name alice
# Output: pub_key_b64 = <base64 public key>
# Key written to: ~/.familiars/authors/alice.key

1.2 Create a Broker from Template

# Windows
xcopy /E /I workspace\manager\brokers\starter_broker workspace\manager\brokers\my_broker

# Linux/macOS
cp -r workspace/manager/brokers/starter_broker workspace/manager/brokers/my_broker

Edit workspace/manager/brokers/my_broker/manifest.json:

• Change broker_id (must == directory name)
• Change name / description
• Fill in author_pubkey (your public key)

1.3 Local Development Iteration

# Package
python main.py broker pack workspace/manager/brokers/my_broker \
    --output ./my_broker-0.1.0.broker.zip

# Verify (inspect output)
python main.py broker verify ./my_broker-0.1.0.broker.zip --pretty
# → Outputs pub_key_b64, manifest_sha256, zip_sha256

Local development does not require install (packages from built_in / user_created sources are directly visible in the workshop). The bridge automatically scans directories under workspace/manager/brokers/ at startup.

1.4 Publish

To Public Relay (Recommended)

python main.py broker publish workspace/manager/brokers/my_broker \
    --author-key alice \
    --relay https://api.familiars.cn

Enters the review queue (pending) → operator approve → publicly visible.

To Your Own Static Site

python main.py broker publish workspace/manager/brokers/my_broker \
    --author-key alice \
    --host-dir workspace/marketplace_host \
    --download-url-base https://your-marketplace.example.com

Then have users export FAMILIARS_MARKETPLACE_URL=https://your-marketplace.example.com.

1.5 User-Side Install

# CLI
python main.py broker marketplace-index                       # Browse index
python main.py broker install \
    --url https://api.familiars.cn/marketplace/download/<broker_id>/<version> \
    --sha256 <zip_sha256> \
    --pubkey <pub_key_b64>

# UI: Workshop → 🏬 Marketplace → click my_broker → Install

---

2. Key File (manifest.json)

{
  "broker_id": "my_broker",
  "name": "My Broker",
  "version": "0.1.0",
  "schema_version": 1,
  "author_pubkey": "<your public key>",
  "description": "...",

  "capabilities_required": ["guild", "ledger"],

  "role_defs": {
    "owner": {"caps": ["*"]},
    "member": {"caps": ["message.post", "room.read"]}
  },

  "ui": {
    "entry": "index.html"
  },

  "permissions": {
    "network": false,
    "extra_modules": []
  }
}

Field	Description
broker_id	Globally unique, == directory name == zip-internal id
author_pubkey	Your public key (must be correct, or publish/install verification will fail)
capabilities_required	Declares which local APIs are needed from the cluster
ui.entry	iframe UI entry point (.html relative to ui/)
role_defs	Role → capability sets
permissions	Plugin sandbox permissions

---

3. Writing UI (Minimal Example)

ui/index.html:

<!DOCTYPE html>
<html>
<head><script src="../sdk.js"></script></head>
<body>
  <h1 id="title"></h1>
  <button onclick="load()">Load rooms</button>
  <pre id="out"></pre>
  <script>
    const api = window.familiars;
    document.getElementById('title').textContent = 'Hello, ' + api.broker_id;
    async function load() {
      const res = await api.rooms.list();
      document.getElementById('out').textContent = JSON.stringify(res, null, 2);
    }
  </script>
</body>
</html>

../sdk.js is served by the bridge at /api/broker_app/<id>/sdk.js and injects window.familiars into the iframe.

Full SDK API: workspace/manager/brokers/SDK.md.

---

4. Writing a Plugin (Minimal Example)

plugins/greeter.py:

from broker_sdk import store

def on_message_posted(payload):
    store.upsert(
        f"seen/{payload['message_id']}",
        title="seen",
        meta={"cluster_id": payload.get("cluster_id")}
    )

triggers.json:

[
  {
    "event": "message.posted",
    "action_kind": "plugin_fn",
    "action_ref": "plugins.greeter:on_message_posted"
  }
]

Key points:

• Plugin functions receive only a single payload dict parameter;
• Facades (store / rooms / ledger) are imported from broker_sdk;
• Do NOT add an sdk parameter (the old version is deprecated).

---

5. Three Mandatory Verifications (All Required)

install_from_url verifies in sequence:

1. sha256: Downloaded content hash must exactly match the index record
2. SIGNATURE: <pubkey>\n<sig>\n inside the zip, uses pubkey to verify sha256(manifest.json) signature
3. author_pubkey: The pubkey in the signature must match the index declaration

Any mismatch → installation rejected with a specific error message.

---

6. Debugging Tips

Symptom	Troubleshooting
Broker won't install	Check audit.log for the specific action; check if capabilities_required is blocked by approval
Installed then disappears	Check if capabilities_required was rejected by the user
iframe UI not showing	Open browser DevTools and check if window.familiars exists; check if ../sdk.js loaded
Plugin not triggering	Are field names in triggers.json spelled correctly? action_ref format is plugins.<module>:<fn>
Signature invalid after changing manifest	Must run broker sign to re-sign

Debugging commands:

# List installed brokers
python main.py broker workshop list

# View audit log
tail -f workspace/.bridge.audit.log

# View marketplace index
python main.py broker marketplace-index

---

7. Learning Path

1. Copy starter_broker: Install locally → see how the iframe UI is hosted
2. Read hello_broker: See the minimal plugin + triggers example
3. Read example_broker: Vue/Vite project + dist/ build output
4. Read ventaris: Full business-grade reference implementation (tasks + medals + room six-section)

---

8. CLI Command Reference

Command	Description
python main.py broker keygen --name <name>	Generate author key
python main.py broker keys-list	List local keys
python main.py broker pack --source-dir <dir>	Package as .broker.zip
python main.py broker sign <zip> --author-key <name>	Sign
python main.py broker verify <zip> --pretty	Verify + output three elements
python main.py broker install --url <url> --sha256 <hex> --pubkey <b64>	Install from URL
python main.py broker marketplace-index	Query marketplace index
python main.py broker publish <dir> --author-key <name> --relay <url>	Publish to relay
python main.py broker relay-review --relay <url> --operator-key <key>	Operator review

---

References

• Full development manual: BROKER_DEVELOPMENT.md (repo root)
• SDK documentation: workspace/manager/brokers/SDK.md
• Template: workspace/manager/brokers/starter_broker/
• Broker Development Tutorial / Broker Architecture / Capability Reference