best-claw

best-claw is a Telegram DM gateway that replies through a Codex model.

Minimal Operations Guide

1. Onboard

cargo run -- onboard

2. Validate config

cargo run -- config check

3. Check/approve pairing requests

cargo run -- pairing list
cargo run -- pairing approve <code>

4. Optional: OAuth login

cargo run -- auth

5. Run gateway

cargo run -- gateway

6. Stop gateway

• Press q in the gateway TUI.

Operator Security Quick Reference

When approving pairing requests

• Run:
  • cargo run -- pairing list
  • cargo run -- pairing approve <code>
• Verify you know who is requesting access and that code values match.
• Keep telegram.dm_policy = "pairing" so unapproved users never receive model responses.

When handling secrets and tokens

• Keep ~/.best-claw/secrets.toml, ~/.best-claw/oauth.token.enc, and ~/.best-claw/telegram-pairing.toml on trusted machines only.
• Do not share these files over chat/email/issues.
• When moving files between machines, use trusted channels and keep permissions private (0600 on Unix).

Architecture Overview (kernel + extensions)

• src/core owns shared runtime contracts and state:
  • command/event types
  • event bus
  • runtime state
  • AppCore command dispatch
• src/extensions owns command handlers:
  • each extension declares supported command kinds (kernel contract)
  • each handler executes the command and can emit runtime events
• src/domain.rs is CLI parsing focused and maps CLI input to core commands.

Explicit Command/Event Flow

1. CLI args are parsed in domain.rs into a core command.
2. AppCore stores last_command and dispatches to the first matching extension handler.
3. Extensions run command behavior and emit events as needed (for example gateway start/stop, pairing approved).

Command-to-Extension Mapping

• onboard → OnboardExtension
• auth → AuthExtension
• config check → ConfigExtension
• pairing list, pairing approve <code> → PairingExtension
• gateway, gateway-core → TelegramGatewayExtension
• default/no recognized command → TuiExtension

Breaking Change Notice

• Internal architecture was refactored to explicit core/extensions boundaries (src/core, src/extensions).
• Runtime command handling is now extension-based through AppCore dispatch.
• Operator-facing CLI commands and operational flow remain the same.

Telegram DM Policy

• Default is telegram.dm_policy = "pairing".
• Unapproved users receive a pairing guidance message instead of a model reply.
• Users cannot receive model responses until approved.

Pairing Management During Gateway Runtime

Approved users (admins) can send these bot DM commands:

• /pairing list
• /pairing approve <code>
• /auth (runs OAuth login flow)

Network Inventory (Summary)

• Ingress listener: OAuth callback on 127.0.0.1:1455 (loopback-only HTTP during login flow).
• Egress destinations: auth.openai.com, api.openai.com, api.telegram.org (HTTPS-only).
• Remote operation recommendation: keep loopback defaults and use SSH/Tailscale tunnel instead of direct public bind.

Release checklist (operator view)

Before upgrading or deploying a new build:

• Run ./scripts/security_gate.sh and ensure it passes.
• Confirm the build passed the release security verification gate in SECURITY.md.
• Confirm the network inventory summary still matches your deployment topology.

For full trust model and network inventory details, see SECURITY.md.