diff --git a/pkg/miniapp/api.go b/pkg/miniapp/api.go
new file mode 100644
index 000000000..697dafa79
--- /dev/null
+++ b/pkg/miniapp/api.go
@@ -0,0 +1,168 @@
+package miniapp
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+ "time"
+)
+
+
+func (h *Handler) apiSkills(w http.ResponseWriter, r *http.Request) {
+ skillsList := h.provider.ListSkills()
+ writeJSON(w, skillsList)
+}
+
+
+func (h *Handler) apiPlan(w http.ResponseWriter, r *http.Request) {
+ info := h.provider.GetPlanInfo()
+ writeJSON(w, info)
+}
+
+
+func (h *Handler) apiSessions(w http.ResponseWriter, r *http.Request) {
+ sessions := h.provider.GetActiveSessions()
+ if sessions == nil {
+ sessions = []SessionInfo{}
+ }
+ writeJSON(w, sessions)
+}
+
+
+func (h *Handler) apiSession(w http.ResponseWriter, r *http.Request) {
+ s := h.provider.GetSessionStats()
+ if s == nil {
+ writeJSON(w, map[string]string{"status": "stats not enabled"})
+ return
+ }
+ writeJSON(w, s)
+}
+
+
+func (h *Handler) apiContext(w http.ResponseWriter, r *http.Request) {
+ writeJSON(w, h.provider.GetContextInfo())
+}
+
+
+func (h *Handler) apiPrompt(w http.ResponseWriter, r *http.Request) {
+ writeJSON(w, map[string]string{"prompt": h.provider.GetSystemPrompt()})
+}
+
+
+func (h *Handler) apiGit(w http.ResponseWriter, r *http.Request) {
+ repo := r.URL.Query().Get("repo")
+ if repo == "" {
+ writeJSON(w, h.provider.GetGitRepos())
+ } else {
+ writeJSON(w, h.provider.GetGitRepoDetail(repo))
+ }
+}
+
+
+func (h *Handler) apiCommand(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ http.Error(w, `{"error":"method not allowed"}`, http.StatusMethodNotAllowed)
+ return
+ }
+
+ body, err := io.ReadAll(io.LimitReader(r.Body, 4096))
+ if err != nil {
+ http.Error(w, `{"error":"bad request"}`, http.StatusBadRequest)
+ return
+ }
+
+ var req struct {
+ Command string `json:"command"`
+ }
+ if err := json.Unmarshal(body, &req); err != nil || req.Command == "" {
+ http.Error(w, `{"error":"missing command"}`, http.StatusBadRequest)
+ return
+ }
+
+ if !strings.HasPrefix(req.Command, "/") {
+ http.Error(w, `{"error":"command must start with /"}`, http.StatusBadRequest)
+ return
+ }
+
+ // Extract user ID from initData to identify the sender
+ initData := r.URL.Query().Get("initData")
+ userID, chatID := extractUserFromInitData(initData)
+ if userID == "" {
+ http.Error(w, `{"error":"cannot identify user"}`, http.StatusBadRequest)
+ return
+ }
+
+ h.sender.SendCommand(userID, chatID, req.Command)
+ writeJSON(w, map[string]string{"status": "ok"})
+}
+
+
+func (h *Handler) apiEvents(w http.ResponseWriter, r *http.Request) {
+ flusher, ok := w.(http.Flusher)
+ if !ok {
+ http.Error(w, `{"error":"streaming not supported"}`, http.StatusInternalServerError)
+ return
+ }
+ rc := http.NewResponseController(w)
+ _ = rc.SetWriteDeadline(time.Time{})
+
+ w.Header().Set("Content-Type", "text/event-stream")
+ w.Header().Set("Cache-Control", "no-cache")
+ w.Header().Set("Connection", "keep-alive")
+ w.Header().Set("X-Accel-Buffering", "no")
+
+ ch := h.notifier.Subscribe()
+ defer h.notifier.Unsubscribe(ch)
+
+ var lastPlan, lastSession, lastSkills, lastDev, lastContext, lastPrompt []byte
+
+ // Send initial state immediately
+ sendSSEIfChanged(w, flusher, "plan", h.provider.GetPlanInfo(), &lastPlan)
+ sendSSEIfChanged(w, flusher, "session",
+ map[string]any{"stats": h.provider.GetSessionStats(), "sessions": h.provider.GetActiveSessions()},
+ &lastSession)
+ sendSSEIfChanged(w, flusher, "skills", h.provider.ListSkills(), &lastSkills)
+ sendSSEIfChanged(w, flusher, "dev", h.devStatus(), &lastDev)
+ sendSSEIfChanged(w, flusher, "context", h.provider.GetContextInfo(), &lastContext)
+ sendSSEIfChanged(w, flusher, "prompt", map[string]string{"prompt": h.provider.GetSystemPrompt()}, &lastPrompt)
+
+ for {
+ select {
+ case <-r.Context().Done():
+ return
+ case <-h.notifier.Done():
+ return
+ case <-ch:
+ sendSSEIfChanged(w, flusher, "plan", h.provider.GetPlanInfo(), &lastPlan)
+ sendSSEIfChanged(w, flusher, "session",
+ map[string]any{"stats": h.provider.GetSessionStats(), "sessions": h.provider.GetActiveSessions()},
+ &lastSession)
+ sendSSEIfChanged(w, flusher, "skills", h.provider.ListSkills(), &lastSkills)
+ sendSSEIfChanged(w, flusher, "dev", h.devStatus(), &lastDev)
+ sendSSEIfChanged(w, flusher, "context", h.provider.GetContextInfo(), &lastContext)
+ sendSSEIfChanged(w, flusher, "prompt", map[string]string{"prompt": h.provider.GetSystemPrompt()}, &lastPrompt)
+ }
+ }
+}
+
+
+func sendSSEIfChanged(w http.ResponseWriter, f http.Flusher, event string, v any, last *[]byte) {
+ data, _ := json.Marshal(v)
+ if !bytes.Equal(data, *last) {
+ fmt.Fprintf(w, "event: %s\ndata: %s\n\n", event, data)
+ f.Flush()
+ *last = data
+ }
+}
+
+
+func writeJSON(w http.ResponseWriter, v any) {
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(v)
+}
+
+// apiDevConsole receives console output from dev preview iframes.
+
diff --git a/pkg/miniapp/auth.go b/pkg/miniapp/auth.go
new file mode 100644
index 000000000..cc2b3406f
--- /dev/null
+++ b/pkg/miniapp/auth.go
@@ -0,0 +1,131 @@
+package miniapp
+
+import (
+ "crypto/hmac"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/url"
+ "sort"
+ "strconv"
+ "strings"
+ "time"
+)
+
+// initDataMaxAge is the maximum age of initData before it is considered expired.
+const initDataMaxAge = 24 * time.Hour
+
+func (h *Handler) requireAuth(next http.HandlerFunc) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ initData := r.URL.Query().Get("initData")
+ if initData == "" {
+ http.Error(w, `{"error":"missing initData"}`, http.StatusUnauthorized)
+ return
+ }
+ if !ValidateInitData(initData, h.botToken) {
+ http.Error(w, `{"error":"invalid initData"}`, http.StatusUnauthorized)
+ return
+ }
+ if len(h.allowList) > 0 {
+ userID, _ := extractUserFromInitData(initData)
+ if userID == "" || !isAllowed(userID, h.allowList) {
+ http.Error(w, `{"error":"forbidden"}`, http.StatusForbidden)
+ return
+ }
+ }
+ next(w, r)
+ }
+}
+
+// isAllowed checks whether userID matches any entry in the allow list.
+// Logic mirrors BaseChannel.IsAllowed without importing channels package.
+func isAllowed(userID string, allowList []string) bool {
+ if len(allowList) == 0 {
+ return true
+ }
+ for _, allowed := range allowList {
+ trimmed := strings.TrimPrefix(allowed, "@")
+ allowedID := trimmed
+ if idx := strings.Index(trimmed, "|"); idx > 0 {
+ allowedID = trimmed[:idx]
+ }
+ if userID == allowed || userID == trimmed || userID == allowedID {
+ return true
+ }
+ }
+ return false
+}
+
+// extractUserFromInitData parses user.id from the initData query string.
+// initData contains a "user" param with JSON like {"id":123456,...}.
+func extractUserFromInitData(initData string) (userID, chatID string) {
+ values, err := url.ParseQuery(initData)
+ if err != nil {
+ return "", ""
+ }
+ userJSON := values.Get("user")
+ if userJSON == "" {
+ return "", ""
+ }
+ var user struct {
+ ID int64 `json:"id"`
+ }
+ if err := json.Unmarshal([]byte(userJSON), &user); err != nil || user.ID == 0 {
+ return "", ""
+ }
+ id := fmt.Sprintf("%d", user.ID)
+ // For Mini App commands, chatID = userID (private chat)
+ return id, id
+}
+
+// ValidateInitData verifies the Telegram WebApp initData HMAC-SHA256 signature
+// and checks that auth_date is not older than initDataMaxAge.
+// See https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
+func ValidateInitData(initData, botToken string) bool {
+ values, err := url.ParseQuery(initData)
+ if err != nil {
+ return false
+ }
+
+ receivedHash := values.Get("hash")
+ if receivedHash == "" {
+ return false
+ }
+
+ // Check auth_date freshness
+ if authDateStr := values.Get("auth_date"); authDateStr != "" {
+ authDate, err := strconv.ParseInt(authDateStr, 10, 64)
+ if err != nil {
+ return false
+ }
+ if time.Since(time.Unix(authDate, 0)) > initDataMaxAge {
+ return false
+ }
+ }
+
+ // Build the data-check-string: sort all key=value pairs except "hash",
+ // join with newlines.
+ var pairs []string
+ for key := range values {
+ if key == "hash" {
+ continue
+ }
+ pairs = append(pairs, fmt.Sprintf("%s=%s", key, values.Get(key)))
+ }
+ sort.Strings(pairs)
+ dataCheckString := strings.Join(pairs, "\n")
+
+ // secret_key = HMAC-SHA256("WebAppData", bot_token)
+ secretKeyMac := hmac.New(sha256.New, []byte("WebAppData"))
+ secretKeyMac.Write([]byte(botToken))
+ secretKey := secretKeyMac.Sum(nil)
+
+ // hash = HMAC-SHA256(secret_key, data_check_string)
+ hashMac := hmac.New(sha256.New, secretKey)
+ hashMac.Write([]byte(dataCheckString))
+ computedHash := hex.EncodeToString(hashMac.Sum(nil))
+
+ return hmac.Equal([]byte(computedHash), []byte(receivedHash))
+}
diff --git a/pkg/miniapp/dev.go b/pkg/miniapp/dev.go
new file mode 100644
index 000000000..1dfbaa7fa
--- /dev/null
+++ b/pkg/miniapp/dev.go
@@ -0,0 +1,477 @@
+package miniapp
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net"
+ "net/http"
+ "net/http/httputil"
+ "net/url"
+ "sort"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+
+// validateLocalhostURL parses and validates that a URL targets localhost.
+func validateLocalhostURL(target string) (*url.URL, error) {
+ u, err := url.Parse(target)
+ if err != nil {
+ return nil, fmt.Errorf("invalid URL: %w", err)
+ }
+ host := u.Hostname()
+ if host != "localhost" && host != "127.0.0.1" && host != "::1" {
+ return nil, fmt.Errorf("only localhost targets are allowed, got %q", host)
+ }
+ return u, nil
+}
+
+// RegisterDevTarget registers a new dev server target. Only localhost targets are allowed.
+
+
+// RegisterDevTarget registers a new dev server target. Only localhost targets are allowed.
+func (h *Handler) RegisterDevTarget(name, target string) (string, error) {
+ if _, err := validateLocalhostURL(target); err != nil {
+ return "", err
+ }
+
+ h.devMu.Lock()
+ defer h.devMu.Unlock()
+
+ h.devNextID++
+ id := strconv.Itoa(h.devNextID)
+
+ h.devTargets[id] = &DevTarget{ID: id, Name: name, Target: target}
+ if h.notifier != nil {
+ h.notifier.Notify()
+ }
+ return id, nil
+}
+
+// UnregisterDevTarget removes a registered target. If it was active, the proxy is disabled.
+
+
+// UnregisterDevTarget removes a registered target. If it was active, the proxy is disabled.
+func (h *Handler) UnregisterDevTarget(id string) error {
+ h.devMu.Lock()
+ defer h.devMu.Unlock()
+
+ if _, ok := h.devTargets[id]; !ok {
+ return fmt.Errorf("target %q not found", id)
+ }
+ delete(h.devTargets, id)
+
+ if h.devActiveID == id {
+ h.devActiveID = ""
+ h.devTarget = nil
+ h.devProxy = nil
+ }
+ if h.notifier != nil {
+ h.notifier.Notify()
+ }
+ return nil
+}
+
+// ActivateDevTarget sets the reverse proxy to the registered target with the given ID.
+
+
+// ActivateDevTarget sets the reverse proxy to the registered target with the given ID.
+func (h *Handler) ActivateDevTarget(id string) error {
+ h.devMu.Lock()
+ defer h.devMu.Unlock()
+
+ dt, ok := h.devTargets[id]
+ if !ok {
+ return fmt.Errorf("target %q not found", id)
+ }
+
+ u, err := url.Parse(dt.Target)
+ if err != nil {
+ return fmt.Errorf("invalid URL: %w", err)
+ }
+
+ // Fix IPv6: resolve "localhost" to 127.0.0.1 to avoid connection refused on systems
+ // where localhost resolves to [::1] but the dev server only listens on IPv4.
+ if u.Hostname() == "localhost" {
+ u.Host = net.JoinHostPort("127.0.0.1", u.Port())
+ }
+
+ proxy := httputil.NewSingleHostReverseProxy(u)
+ proxy.ModifyResponse = func(resp *http.Response) error {
+ // Prevent browser/WebView from caching dev proxy responses (CSS, JS, etc.)
+ resp.Header.Set("Cache-Control", "no-cache, no-store, must-revalidate")
+ resp.Header.Del("ETag")
+ resp.Header.Del("Last-Modified")
+
+ ct := resp.Header.Get("Content-Type")
+ if !strings.Contains(ct, "text/html") {
+ return nil
+ }
+ body, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return err
+ }
+ resp.Body.Close()
+ modified := injectDevProxyScript(body)
+ resp.Body = io.NopCloser(bytes.NewReader(modified))
+ resp.ContentLength = int64(len(modified))
+ resp.Header.Set("Content-Length", strconv.Itoa(len(modified)))
+ resp.Header.Del("Content-Encoding")
+ return nil
+ }
+ proxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
+ w.Header().Set("Content-Type", "text/html; charset=utf-8")
+ w.WriteHeader(http.StatusBadGateway)
+ fmt.Fprintf(w, `
+Cannot connect
%s
Target: %s
Cannot connect
%s
Target: %s