agentscope-ai / agentscope-ai/AgentTeams

feat: Matrix AppService mode integration (Phase 1) — dual-track auth, token lifecycle management, and safe rotation

Aperta
#912 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area:matrix-element
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.