agentscope-ai / agentscope-ai/AgentTeams
feat: Matrix AppService mode integration (Phase 1) — dual-track auth, token lifecycle management, and safe rotation
- Lingua principale
- Go
- Stelle
- 5.6k
- Fork
- 692
- Merge medio
- 5g 4h
- PR unite (30g)
- 23
Descrizione
## Background
HiClaw Controller currently authenticates with the Matrix Homeserver (Tuwunel) using traditional username/password login, with each Worker/Manager account holding an independent access token. This approach has several issues:
- **Complex credential management**: Each Agent requires separate password files and access tokens; switching from Legacy to AS mode requires manual migration
- **No emergency token rotation path**: No CLI or REST endpoint for token rotation; a leaked token forces a full reinstall
- **Non-idempotent registration**: If Tuwunel rejects same-ID re-registration with a different token on Controller restart, startup fails
- **No 401 self-healing**: Workers cannot automatically recover when an access token expires or is invalidated
## Goals
Implement Matrix Application Service (AS) mode as the default authentication method while maintaining backward compatibility with Legacy mode. Provide complete token lifecycle management and an emergency rotation path.
## Scope of Changes
### Core Features
- **AS dual-track authentication**: Controller registers as an AppService with Tuwunel, obtains access tokens for each Agent via `LoginAppServiceUser` without individual passwords
- **Smoke-test-first idempotent registration**: On startup, validates the current token first; if invalid, falls back to unregister → register, independent of Tuwunel's overwrite semantics
- **Token rotation pipeline**: `hiclaw rotate appservice-token` CLI → `POST /api/v1/appservice/rotate-token` REST → unregister + register + smoke test
- **401 auto-recovery**: In AS mode, `ensureMatrixToken` always re-logins; expired tokens are automatically recovered on next reconcile
- **Legacy password cleanup**: Automatically removes stale legacy password files on AS mode startup
- **Legacy password backfill**: Auto-generates passwords when switching from AS back to Legacy mode
### Installation & Deployment
- Install script auto-generates AS tokens (as_token / hs_token) and injects them into the Controller container environment
- Controller fail-fast check for AS token presence at startup
- Embedded mode AI Gateway host replacement fix
### Testing
- 5 unit tests covering registration, unregistration, and smoke test success/failure paths
- E2E verified: fresh install, token rotation (REST + CLI), old token invalidation confirmation, restart with rotated token auto-recovery
## Acceptance Criteria
## Acceptance Criteria
- [x] Fresh install shows `Matrix AppService registered and verified` in Controller logs
- [x] `hiclaw rotate appservice-token --as-token ` succeeds; old token returns `M_UNKNOWN_TOKEN`
- [x] Controller restarted with the rotated token re-registers successfully
- [x] No password files written in AS mode; Worker access tokens obtained via AS login
- [x] All unit tests pass
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.