Replace Slack with Lark for approval notifications

[henryqingmo]

Summary

• Replace Slack with Lark throughout: gateway notifier, webhook handler, mock service, eval suite, policy, and all tests
• Wire real Lark approval flow end-to-end: Schema 2.0 callback support, HMAC verification for mock-lark, tenant token fetch with timeout
• Fix LARK_API_BASE_URL docker-compose default — remove mock-lark hardcode so unset env routes to real Lark (open.feishu.cn); set LARK_API_BASE_URL=http://mock-lark:8090/open-apis in .env for local dev
• Rename send_slack_message → send_lark_message in policy, eval suites, fake servers, and tests
• Rename scenario approval-timeout-slack-down → approval-timeout-lark-down across scenarios, suites, and UI
• Fix LangGraph checkpoint corruption after approval denial: inject synthetic ToolMessages for orphaned tool_calls before the next agent turn
• Add README Lark setup guide (ngrok, Developer Console steps, .env config)

Test plan

• go test ./... passes
• docker compose up -d --wait starts all services healthy
• create_refund in demo-webapp triggers an interactive Lark card in the configured chat
• Clicking Approve/Deny in Lark resolves the approval hold and the agent completes
• Denying and retrying no longer produces INVALID_CHAT_HISTORY error
• Eval UI at http://localhost:8099 shows MCP Crash / Retry Storm / Approval Timeout scenarios
• Approval Timeout scenario passes with mock-lark stopped

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request migrates the approval notification system from Slack to Lark (Feishu), replacing the mock Slack services and tests with Lark equivalents, and introduces conditional rule evaluation based on tool arguments (when clauses) in the policy evaluator. Feedback on the changes highlights critical issues with Lark's API error handling, noting that business-level failures must be decoded and verified even when HTTP 200 is returned. Additionally, the signature verification logic in both the gateway and mock server needs to be corrected to match Lark's official concatenation order, and standard string comparisons should be replaced with subtle.ConstantTimeCompare to prevent timing attacks. Finally, the matchWhen helper should be updated to handle non-comparable types and numeric type mismatches robustly to avoid runtime panics.

[gemini-code-assist]

Lark Open APIs return HTTP 200 even for business-level failures, indicating the actual status via a code field in the JSON response body. To handle these errors properly, we should define a response structure to decode and verify the response code.

// larkSendMessageReq is the payload for Lark's im/v1/messages endpoint.
// Content is the JSON-encoded card string (Lark requires a JSON string, not object).
type larkSendMessageReq struct {
	ReceiveID string `json:"receive_id"`
	MsgType   string `json:"msg_type"`
	Content   string `json:"content"`
}

// larkSendMessageResp is the response from Lark's im/v1/messages endpoint.
type larkSendMessageResp struct {
	Code int    `json:"code"`
	Msg  string `json:"msg"`
}

[gemini-code-assist]

Lark's message sending API returns HTTP 200 even when the message fails to deliver (e.g., due to invalid chat ID or missing permissions), returning a non-zero code in the JSON payload. We must decode the response body and verify that code == 0 to prevent silent failures.

	rawBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return fmt.Errorf("lark notifier: read message response: %w", err)
	}
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("lark notifier: unexpected status %d: %s", resp.StatusCode, rawBody)
	}

	var sendResp larkSendMessageResp
	if err := json.Unmarshal(rawBody, &sendResp); err != nil {
		return fmt.Errorf("lark notifier: decode message response: %w", err)
	}
	if sendResp.Code != 0 {
		return fmt.Errorf("lark notifier: message error code %d: %s", sendResp.Code, sendResp.Msg)
	}

	c.log.Info("lark approval card sent", "ticketID", ticketID, "chatID", c.chatID)
	return nil

[gemini-code-assist]

The current implementation of matchWhen uses standard != comparison on any values. This has two major issues:

1. Comparing non-comparable types (like slices or maps, which are common in JSON arguments) will cause a runtime panic.
2. Numbers parsed from JSON are always float64, whereas numbers parsed from YAML are typically int or int64. This type mismatch causes numeric comparisons to silently fail (e.g., 100.0 != 100 evaluates to true).

Using reflect.DeepEqual and a numeric normalization helper solves both issues.

func matchWhen(when map[string]any, args map[string]any) bool {
	for k, wantVal := range when {
		gotVal, ok := args[k]
		if !ok {
			return false
		}
		if !compareValues(gotVal, wantVal) {
			return false
		}
	}
	return true
}

func compareValues(got, want any) bool {
	if reflect.DeepEqual(got, want) {
		return true
	}
	gotNum, gotOk := toFloat64(got)
	wantNum, wantOk := toFloat64(want)
	if gotOk && wantOk {
		return gotNum == wantNum
	}
	return false
}

func toFloat64(v any) (float64, bool) {
	switch val := v.(type) {
	case int:
		return float64(val), true
	case int8:
		return float64(val), true
	case int16:
		return float64(val), true
	case int32:
		return float64(val), true
	case int64:
		return float64(val), true
	case uint:
		return float64(val), true
	case uint8:
		return float64(val), true
	case uint16:
		return float64(val), true
	case uint32:
		return float64(val), true
	case uint64:
		return float64(val), true
	case float32:
		return float64(val), true
	case float64:
		return val, true
	}
	return 0, false
}

[gemini-code-assist]

The signature concatenation order in computeLarkSignature is incorrect. According to Lark's official specification, the signature must be computed as hex(sha256(timestamp + nonce + key + body)). The current implementation puts the key first, which will cause signature verification to fail for real Lark callbacks.

Suggested change

	// computeLarkSignature returns hex(sha256(verificationToken + timestamp + nonce + body)).
	// Both the gateway and mock-lark use this formula so signatures are mutually verifiable.
	func computeLarkSignature(verificationToken, timestamp, nonce string, body []byte) string {
	h := sha256.New()
	h.Write([]byte(verificationToken))
	h.Write([]byte(timestamp))
	h.Write([]byte(nonce))
	h.Write(body)
	return hex.EncodeToString(h.Sum(nil))
	}
	// computeLarkSignature returns hex(sha256(timestamp + nonce + verificationToken + body)).
	// This matches Lark's official signature verification specification.
	func computeLarkSignature(verificationToken, timestamp, nonce string, body []byte) string {
	h := sha256.New()
	h.Write([]byte(timestamp))
	h.Write([]byte(nonce))
	h.Write([]byte(verificationToken))
	h.Write(body)
	return hex.EncodeToString(h.Sum(nil))
	}

[gemini-code-assist]

Update the signature computation formula in the mock server to match Lark's official specification (timestamp + nonce + token + body) so that it remains in sync with the gateway's corrected signature verification.

Suggested change

	// computeSignature computes the Lark-compatible HMAC signature used by the gateway.
	// Formula: hex(sha256(verificationToken + timestamp + nonce + body))
	func computeSignature(token, timestamp, nonce string, body []byte) string {
	h := sha256.New()
	h.Write([]byte(token))
	h.Write([]byte(timestamp))
	h.Write([]byte(nonce))
	h.Write(body)
	return hex.EncodeToString(h.Sum(nil))
	}
	// computeSignature computes the Lark-compatible signature used by the gateway.
	// Formula: hex(sha256(timestamp + nonce + token + body))
	func computeSignature(token, timestamp, nonce string, body []byte) string {
	h := sha256.New()
	h.Write([]byte(timestamp))
	h.Write([]byte(nonce))
	h.Write([]byte(token))
	h.Write(body)
	return hex.EncodeToString(h.Sum(nil))
	}

[gemini-code-assist]

We should import "crypto/subtle" to perform constant-time signature comparisons, mitigating potential timing attacks on the webhook signature verification.

Suggested change

	import (
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log/slog"
	"net/http"
	"net/url"
	"strconv"
	"time"
	import (
	"context"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"encoding/json"
	"io"
	"log/slog"
	"net/http"
	"strconv"
	"time"

[gemini-code-assist]

Comparing cryptographic signatures using standard string comparison (!=) is vulnerable to timing attacks. Use subtle.ConstantTimeCompare to ensure constant-time comparison.

Suggested change

	providedSig := r.Header.Get("X-Lark-Signature")
	if expectedSig != providedSig {
	h.log.Warn("lark webhook: signature mismatch")
	http.Error(w, "bad request", http.StatusBadRequest)
	return
	}
	providedSig := r.Header.Get("X-Lark-Signature")
	if subtle.ConstantTimeCompare([]byte(expectedSig), []byte(providedSig)) != 1 {
	h.log.Warn("lark webhook: signature mismatch")
	http.Error(w, "bad request", http.StatusBadRequest)
	return
	}