feat(embed): add backend embed channels with auth and rate limiting (#1657)

Introduce embed_channels storage, publish-token and session-token auth,
origin allowlist enforcement, shared Redis rate limiter, public embed API
routes, webhooks with SSRF validation, and session listing by embed source.
This commit is contained in:
wizardchen
2026-06-12 22:40:18 +08:00
committed by lyingbug
parent a0786b6fe7
commit ed9802ff2b
30 changed files with 4070 additions and 216 deletions
@@ -0,0 +1,78 @@
package repository
import (
"context"
"errors"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"gorm.io/gorm"
)
type embedChannelRepository struct {
db *gorm.DB
}
func NewEmbedChannelRepository(db *gorm.DB) interfaces.EmbedChannelRepository {
return &embedChannelRepository{db: db}
}
func (r *embedChannelRepository) Create(ctx context.Context, ch *types.EmbedChannel) error {
return r.db.WithContext(ctx).Create(ch).Error
}
func (r *embedChannelRepository) GetByID(ctx context.Context, id string) (*types.EmbedChannel, error) {
var ch types.EmbedChannel
err := r.db.WithContext(ctx).Where("id = ?", id).First(&ch).Error
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return &ch, nil
}
func (r *embedChannelRepository) GetByPublishToken(ctx context.Context, token string) (*types.EmbedChannel, error) {
var ch types.EmbedChannel
err := r.db.WithContext(ctx).Where("publish_token = ?", token).First(&ch).Error
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return &ch, nil
}
func (r *embedChannelRepository) ListByAgent(
ctx context.Context, tenantID uint64, agentID string,
) ([]*types.EmbedChannel, error) {
var rows []*types.EmbedChannel
err := r.db.WithContext(ctx).
Where("tenant_id = ? AND agent_id = ?", tenantID, agentID).
Order("created_at DESC").
Find(&rows).Error
return rows, err
}
func (r *embedChannelRepository) ListByTenant(
ctx context.Context, tenantID uint64,
) ([]*types.EmbedChannel, error) {
var rows []*types.EmbedChannel
err := r.db.WithContext(ctx).
Where("tenant_id = ?", tenantID).
Order("created_at DESC").
Find(&rows).Error
return rows, err
}
func (r *embedChannelRepository) Update(ctx context.Context, ch *types.EmbedChannel) error {
return r.db.WithContext(ctx).Save(ch).Error
}
func (r *embedChannelRepository) Delete(ctx context.Context, tenantID uint64, id string) error {
return r.db.WithContext(ctx).
Where("tenant_id = ? AND id = ?", tenantID, id).
Delete(&types.EmbedChannel{}).Error
}
+18 -3
View File
@@ -148,13 +148,28 @@ func (r *sessionRepository) QueryPaged(
joinClause := "LEFT JOIN im_channel_sessions ics ON ics.session_id = s.id"
applySource := func(db *gorm.DB) *gorm.DB {
switch strings.ToLower(strings.TrimSpace(q.Source)) {
src := strings.TrimSpace(q.Source)
lower := strings.ToLower(src)
embedPrefix := types.EmbedSessionMarkerPrefix
switch lower {
case "":
return db
case "web":
return db.Where("ics.id IS NULL")
// User web chats only — exclude embed-widget sessions (same IM-null row).
return db.Where(
"ics.id IS NULL AND (s.description = '' OR s.description NOT LIKE ?)",
embedPrefix+"%",
)
case "embed":
return db.Where("ics.id IS NULL AND s.description LIKE ?", embedPrefix+"%")
default:
return db.Where("ics.platform = ?", strings.ToLower(q.Source))
if strings.HasPrefix(lower, "embed:") {
channelID := strings.TrimSpace(src[len("embed:"):])
if channelID != "" {
return db.Where("ics.id IS NULL AND s.description = ?", embedPrefix+channelID)
}
}
return db.Where("ics.platform = ?", lower)
}
}
applyAgent := func(db *gorm.DB) *gorm.DB {
@@ -222,3 +222,26 @@ func TestSessionRepositoryQueryPagedKeepsClearedIMSessionsOutOfWeb(t *testing.T)
require.ElementsMatch(t, []string{active.ID, cleared.ID}, listItemIDsForTest(wecomItems),
"wecom must include both the active and the cleared IM session")
}
func TestSessionRepositoryQueryPagedSplitsWebAndEmbedSessions(t *testing.T) {
repo, db := newSessionRepositoryForTest(t)
require.NoError(t, db.AutoMigrate(&testIMChannelSession{}))
ctx := context.Background()
web := createSessionForTest(t, db, 1, "alice")
embed := createSessionForTest(t, db, 1, "alice")
require.NoError(t, db.Model(&types.Session{}).Where("id = ?", embed.ID).
Update("description", types.EmbedSessionMarkerPrefix+"ch-1").Error)
webItems, _, err := repo.QueryPaged(ctx, &types.SessionListQuery{
TenantID: 1, UserID: "alice", Source: "web", Page: 1, PageSize: 50,
})
require.NoError(t, err)
require.Equal(t, []string{web.ID}, listItemIDsForTest(webItems))
embedItems, _, err := repo.QueryPaged(ctx, &types.SessionListQuery{
TenantID: 1, UserID: "alice", Source: "embed:ch-1", Page: 1, PageSize: 50,
})
require.NoError(t, err)
require.Equal(t, []string{embed.ID}, listItemIDsForTest(embedItems))
}
@@ -0,0 +1,402 @@
package service
import (
"context"
"crypto/rand"
"crypto/subtle"
"encoding/base64"
"errors"
"fmt"
"strings"
apperrors "github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/redis/go-redis/v9"
)
const embedTokenBytes = 32
var (
ErrEmbedChannelNotFound = errors.New("embed channel not found")
ErrEmbedTokenInvalid = errors.New("embed publish token is invalid")
ErrEmbedChannelDisabled = errors.New("embed channel is disabled")
ErrEmbedChunkNotFound = errors.New("embed chunk not found")
ErrEmbedChunkForbidden = errors.New("embed chunk not accessible")
)
type embedChannelService struct {
repo interfaces.EmbedChannelRepository
agentService interfaces.CustomAgentService
chunkService interfaces.ChunkService
redis *redis.Client
}
func NewEmbedChannelService(
repo interfaces.EmbedChannelRepository,
agentService interfaces.CustomAgentService,
chunkService interfaces.ChunkService,
redisClient *redis.Client,
) interfaces.EmbedChannelService {
return &embedChannelService{
repo: repo,
agentService: agentService,
chunkService: chunkService,
redis: redisClient,
}
}
func generateEmbedPublishToken() (string, error) {
buf := make([]byte, embedTokenBytes)
if _, err := rand.Read(buf); err != nil {
return "", err
}
return "em_" + base64.RawURLEncoding.EncodeToString(buf), nil
}
func (s *embedChannelService) Create(
ctx context.Context, tenantID uint64, agentID string, req *types.EmbedChannel,
) (*types.EmbedChannel, string, error) {
agentID = strings.TrimSpace(agentID)
if _, err := s.ensureAgentOwned(ctx, tenantID, agentID); err != nil {
return nil, "", err
}
token, err := generateEmbedPublishToken()
if err != nil {
return nil, "", err
}
originsJSON := req.AllowedOrigins
if len(originsJSON) == 0 {
originsJSON = []byte("[]")
}
ch := &types.EmbedChannel{
TenantID: tenantID,
AgentID: agentID,
Name: strings.TrimSpace(req.Name),
Enabled: req.Enabled,
PublishToken: token,
AllowedOrigins: originsJSON,
WelcomeMessage: req.WelcomeMessage,
RateLimitPerMinute: req.RateLimitPerMinute,
RateLimitPerDay: req.RateLimitPerDay,
PrimaryColor: strings.TrimSpace(req.PrimaryColor),
PageTitle: strings.TrimSpace(req.PageTitle),
HeaderTitleMode: types.NormalizeEmbedHeaderTitleMode(req.HeaderTitleMode),
ShowSuggestedQuestions: req.ShowSuggestedQuestions,
WidgetPosition: types.NormalizeEmbedWidgetPosition(req.WidgetPosition),
AllowWebSearch: req.AllowWebSearch,
AllowMemory: req.AllowMemory,
AllowFileUpload: req.AllowFileUpload,
DefaultLocale: types.NormalizeEmbedDefaultLocale(req.DefaultLocale),
}
if ch.RateLimitPerMinute <= 0 {
ch.RateLimitPerMinute = 30
}
if ch.RateLimitPerDay <= 0 {
ch.RateLimitPerDay = types.DefaultEmbedRateLimitPerDay
}
if err := s.repo.Create(ctx, ch); err != nil {
return nil, "", err
}
return ch, token, nil
}
func (s *embedChannelService) ListByAgent(
ctx context.Context, tenantID uint64, agentID string,
) ([]*types.EmbedChannel, error) {
agentID = strings.TrimSpace(agentID)
if _, err := s.ensureAgentOwned(ctx, tenantID, agentID); err != nil {
return nil, err
}
return s.repo.ListByAgent(ctx, tenantID, agentID)
}
func (s *embedChannelService) ListByTenant(
ctx context.Context, tenantID uint64,
) ([]*types.EmbedChannel, error) {
return s.repo.ListByTenant(ctx, tenantID)
}
func (s *embedChannelService) Update(
ctx context.Context, tenantID uint64, id string, req *types.EmbedChannel,
enabled *bool, showSuggested *bool, allowWebSearch *bool, allowMemory *bool, allowFileUpload *bool,
defaultLocale *string, webhookURL *string, webhookSecret *string,
) (*types.EmbedChannel, error) {
ch, err := s.getOwned(ctx, tenantID, id)
if err != nil {
return nil, err
}
if req.Name != "" {
ch.Name = strings.TrimSpace(req.Name)
}
ch.WelcomeMessage = req.WelcomeMessage
ch.PrimaryColor = strings.TrimSpace(req.PrimaryColor)
ch.PageTitle = strings.TrimSpace(req.PageTitle)
ch.HeaderTitleMode = types.NormalizeEmbedHeaderTitleMode(req.HeaderTitleMode)
if showSuggested != nil {
ch.ShowSuggestedQuestions = *showSuggested
}
if allowWebSearch != nil {
ch.AllowWebSearch = *allowWebSearch
}
if allowMemory != nil {
ch.AllowMemory = *allowMemory
}
if allowFileUpload != nil {
ch.AllowFileUpload = *allowFileUpload
}
if defaultLocale != nil {
ch.DefaultLocale = types.NormalizeEmbedDefaultLocale(*defaultLocale)
}
if webhookURL != nil {
trimmed := strings.TrimSpace(*webhookURL)
if err := ValidateEmbedWebhookURL(trimmed); err != nil {
return nil, err
}
ch.WebhookURL = trimmed
}
if webhookSecret != nil {
ch.WebhookSecret = strings.TrimSpace(*webhookSecret)
}
if req.WidgetPosition != "" {
ch.WidgetPosition = types.NormalizeEmbedWidgetPosition(req.WidgetPosition)
}
if enabled != nil {
ch.Enabled = *enabled
}
if req.RateLimitPerMinute > 0 {
ch.RateLimitPerMinute = req.RateLimitPerMinute
}
if req.RateLimitPerDay > 0 {
ch.RateLimitPerDay = req.RateLimitPerDay
}
if req.AllowedOrigins != nil {
if len(req.AllowedOrigins) == 0 {
ch.AllowedOrigins = []byte("[]")
} else {
ch.AllowedOrigins = req.AllowedOrigins
}
}
if err := s.repo.Update(ctx, ch); err != nil {
return nil, err
}
return ch, nil
}
func (s *embedChannelService) Delete(ctx context.Context, tenantID uint64, id string) error {
if _, err := s.getOwned(ctx, tenantID, id); err != nil {
return err
}
return s.repo.Delete(ctx, tenantID, id)
}
func (s *embedChannelService) RotateToken(
ctx context.Context, tenantID uint64, id string,
) (*types.EmbedChannel, string, error) {
ch, err := s.getOwned(ctx, tenantID, id)
if err != nil {
return nil, "", err
}
token, err := generateEmbedPublishToken()
if err != nil {
return nil, "", err
}
ch.PublishToken = token
if err := s.repo.Update(ctx, ch); err != nil {
return nil, "", err
}
return ch, token, nil
}
func (s *embedChannelService) LookupForEmbed(
ctx context.Context, channelID, token string,
) (*types.EmbedChannel, error) {
token = strings.TrimSpace(token)
if token == "" {
return nil, ErrEmbedTokenInvalid
}
ch, err := s.repo.GetByID(ctx, channelID)
if err != nil {
return nil, err
}
if ch == nil {
return nil, ErrEmbedTokenInvalid
}
if !ch.Enabled {
return nil, ErrEmbedChannelDisabled
}
if subtle.ConstantTimeCompare([]byte(ch.PublishToken), []byte(token)) != 1 {
return nil, ErrEmbedTokenInvalid
}
return ch, nil
}
func (s *embedChannelService) PublicConfig(ctx context.Context, ch *types.EmbedChannel) types.EmbedChannelPublicConfig {
kbIDs := s.resolveKnowledgeBaseIDs(ctx, ch)
displayTitle, agentName, agentAvatar := s.resolveDisplayMeta(ctx, ch)
agentWebSearchEnabled := false
agentImageUploadEnabled := false
if agent, err := s.agentService.GetAgentByID(ctx, ch.AgentID); err == nil && agent != nil {
agentWebSearchEnabled = agent.Config.WebSearchEnabled
agentImageUploadEnabled = agent.Config.ImageUploadEnabled
}
return types.EmbedChannelPublicConfig{
ChannelID: ch.ID,
Name: ch.Name,
DisplayTitle: displayTitle,
KnowledgeBaseIDs: kbIDs,
AgentID: ch.AgentID,
AgentName: agentName,
AgentAvatar: agentAvatar,
WelcomeMessage: ch.WelcomeMessage,
PrimaryColor: ch.PrimaryColor,
PageTitle: ch.PageTitle,
HeaderTitleMode: types.NormalizeEmbedHeaderTitleMode(ch.HeaderTitleMode),
ShowSuggestedQuestions: ch.ShowSuggestedQuestions,
AllowedOrigins: ch.AllowedOriginsList(),
WidgetPosition: types.NormalizeEmbedWidgetPosition(ch.WidgetPosition),
AllowWebSearch: ch.AllowWebSearch,
AllowMemory: ch.AllowMemory,
AllowFileUpload: ch.AllowFileUpload,
AgentWebSearchEnabled: agentWebSearchEnabled,
AgentImageUploadEnabled: agentImageUploadEnabled,
DefaultLocale: types.NormalizeEmbedDefaultLocale(ch.DefaultLocale),
}
}
func (s *embedChannelService) EmbedChunk(
ctx context.Context, ch *types.EmbedChannel, chunkID string,
) (*types.Chunk, error) {
chunkID = strings.TrimSpace(chunkID)
if chunkID == "" {
return nil, ErrEmbedChunkNotFound
}
chunk, err := s.chunkService.GetChunkByIDOnly(ctx, chunkID)
if err != nil || chunk == nil {
return nil, ErrEmbedChunkNotFound
}
if !s.chunkAllowedForEmbed(ctx, ch, chunk) {
return nil, ErrEmbedChunkForbidden
}
return chunk, nil
}
func (s *embedChannelService) chunkAllowedForEmbed(
ctx context.Context, ch *types.EmbedChannel, chunk *types.Chunk,
) bool {
if chunk == nil || chunk.KnowledgeBaseID == "" {
return false
}
// 显式重校验租户:GetChunkByIDOnly 无租户过滤,且 KBSelectionMode=="all"/默认
// 分支会无条件放行,必须在此挡住跨租户 chunk id 撞库读取他人知识库正文。
if ch == nil || chunk.TenantID != ch.TenantID {
return false
}
allowedKBs := s.resolveKnowledgeBaseIDs(ctx, ch)
if len(allowedKBs) > 0 {
for _, kbID := range allowedKBs {
if kbID == chunk.KnowledgeBaseID {
return true
}
}
return false
}
agent, err := s.agentService.GetAgentByID(ctx, ch.AgentID)
if err != nil || agent == nil {
return false
}
switch agent.Config.KBSelectionMode {
case "none":
return false
case "selected":
return false
default:
return true
}
}
func (s *embedChannelService) SuggestedQuestions(
ctx context.Context, ch *types.EmbedChannel, limit int,
) ([]types.SuggestedQuestion, error) {
if ch == nil || !ch.ShowSuggestedQuestions {
return nil, nil
}
if limit <= 0 {
limit = 6
}
kbIDs := s.resolveKnowledgeBaseIDs(ctx, ch)
return s.agentService.GetSuggestedQuestions(ctx, ch.AgentID, kbIDs, nil, limit)
}
// EmbedDisplayTitle resolves the human-readable title for embed sessions and UI chrome.
func (s *embedChannelService) EmbedDisplayTitle(ctx context.Context, ch *types.EmbedChannel) string {
title, _, _ := s.resolveDisplayMeta(ctx, ch)
return title
}
func (s *embedChannelService) resolveDisplayMeta(
ctx context.Context, ch *types.EmbedChannel,
) (displayTitle, agentName, agentAvatar string) {
if pageTitle := strings.TrimSpace(ch.PageTitle); pageTitle != "" {
displayTitle = pageTitle
} else if name := strings.TrimSpace(ch.Name); name != "" {
displayTitle = name
}
agent, err := s.agentService.GetAgentByID(ctx, ch.AgentID)
if err == nil && agent != nil {
agentName = strings.TrimSpace(agent.Name)
agentAvatar = strings.TrimSpace(agent.Avatar)
if displayTitle == "" && agentName != "" {
displayTitle = agentName
}
}
if displayTitle == "" {
displayTitle = "AI Assistant"
}
return displayTitle, agentName, agentAvatar
}
func (s *embedChannelService) resolveKnowledgeBaseIDs(ctx context.Context, ch *types.EmbedChannel) []string {
agent, err := s.agentService.GetAgentByID(ctx, ch.AgentID)
if err == nil && agent != nil && agent.Config.KBSelectionMode == "selected" {
return append([]string(nil), agent.Config.KnowledgeBases...)
}
return nil
}
func (s *embedChannelService) ensureAgentOwned(ctx context.Context, tenantID uint64, agentID string) (*types.CustomAgent, error) {
agentID = strings.TrimSpace(agentID)
if agentID == "" {
return nil, apperrors.NewBadRequestError("agent_id is required")
}
agent, err := s.agentService.GetAgentByID(ctx, agentID)
if err != nil {
return nil, err
}
if agent == nil || agent.TenantID != tenantID {
return nil, apperrors.NewNotFoundError("agent not found")
}
return agent, nil
}
func (s *embedChannelService) GetOwnedChannel(
ctx context.Context, tenantID uint64, id string,
) (*types.EmbedChannel, error) {
return s.getOwned(ctx, tenantID, id)
}
func (s *embedChannelService) getOwned(ctx context.Context, tenantID uint64, id string) (*types.EmbedChannel, error) {
ch, err := s.repo.GetByID(ctx, id)
if err != nil {
return nil, err
}
if ch == nil || ch.TenantID != tenantID {
return nil, ErrEmbedChannelNotFound
}
return ch, nil
}
// EmbedSessionDescription returns the marker stored on embed-created sessions.
func EmbedSessionDescription(channelID string) string {
return fmt.Sprintf("%s%s", types.EmbedSessionMarkerPrefix, channelID)
}
@@ -0,0 +1,123 @@
package service
import (
"context"
"errors"
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
)
type stubChunkForEmbed struct {
interfaces.ChunkService
chunks map[string]*types.Chunk
}
func (s *stubChunkForEmbed) GetChunkByIDOnly(_ context.Context, id string) (*types.Chunk, error) {
chunk, ok := s.chunks[id]
if !ok {
return nil, ErrChunkNotFound
}
return chunk, nil
}
func newEmbedChunkService(agent *types.CustomAgent, chunks map[string]*types.Chunk) *embedChannelService {
return &embedChannelService{
agentService: &stubAgentForEmbed{agent: agent},
chunkService: &stubChunkForEmbed{chunks: chunks},
}
}
func TestChunkAllowedForEmbedAllowedKB(t *testing.T) {
svc := newEmbedChunkService(
&types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
KnowledgeBases: []string{"kb-allowed"},
},
},
map[string]*types.Chunk{
"chunk-1": {ID: "chunk-1", TenantID: 5, KnowledgeBaseID: "kb-allowed"},
},
)
ch := &types.EmbedChannel{ID: "ch-1", TenantID: 5, AgentID: "agent-1"}
if !svc.chunkAllowedForEmbed(context.Background(), ch, &types.Chunk{TenantID: 5, KnowledgeBaseID: "kb-allowed"}) {
t.Fatal("chunk in allowed KB should be permitted")
}
chunk, err := svc.EmbedChunk(context.Background(), ch, "chunk-1")
if err != nil {
t.Fatalf("EmbedChunk() = %v", err)
}
if chunk == nil || chunk.ID != "chunk-1" {
t.Fatalf("unexpected chunk: %#v", chunk)
}
}
func TestChunkAllowedForEmbedCrossTenantDenied(t *testing.T) {
svc := newEmbedChunkService(
&types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
KnowledgeBases: []string{"kb-allowed"},
},
},
map[string]*types.Chunk{
"chunk-x": {ID: "chunk-x", TenantID: 999, KnowledgeBaseID: "kb-allowed"},
},
)
ch := &types.EmbedChannel{ID: "ch-1", TenantID: 5, AgentID: "agent-1"}
chunk := &types.Chunk{ID: "chunk-x", TenantID: 999, KnowledgeBaseID: "kb-allowed"}
if svc.chunkAllowedForEmbed(context.Background(), ch, chunk) {
t.Fatal("cross-tenant chunk must be denied before KB checks")
}
_, err := svc.EmbedChunk(context.Background(), ch, "chunk-x")
if !errors.Is(err, ErrEmbedChunkForbidden) {
t.Fatalf("EmbedChunk() = %v, want ErrEmbedChunkForbidden", err)
}
}
func TestChunkAllowedForEmbedWrongKBDenied(t *testing.T) {
svc := newEmbedChunkService(
&types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
KnowledgeBases: []string{"kb-allowed"},
},
},
map[string]*types.Chunk{
"chunk-other": {ID: "chunk-other", TenantID: 5, KnowledgeBaseID: "kb-other"},
},
)
ch := &types.EmbedChannel{ID: "ch-1", TenantID: 5, AgentID: "agent-1"}
chunk := &types.Chunk{ID: "chunk-other", TenantID: 5, KnowledgeBaseID: "kb-other"}
if svc.chunkAllowedForEmbed(context.Background(), ch, chunk) {
t.Fatal("chunk outside allowed KB list must be denied")
}
_, err := svc.EmbedChunk(context.Background(), ch, "chunk-other")
if !errors.Is(err, ErrEmbedChunkForbidden) {
t.Fatalf("EmbedChunk() = %v, want ErrEmbedChunkForbidden", err)
}
}
func TestChunkAllowedForEmbedAllModePermitsInTenant(t *testing.T) {
svc := newEmbedChunkService(
&types.CustomAgent{
Config: types.CustomAgentConfig{KBSelectionMode: "all"},
},
map[string]*types.Chunk{
"chunk-all": {ID: "chunk-all", TenantID: 5, KnowledgeBaseID: "kb-any"},
},
)
ch := &types.EmbedChannel{ID: "ch-1", TenantID: 5, AgentID: "agent-1"}
if !svc.chunkAllowedForEmbed(context.Background(), ch, &types.Chunk{TenantID: 5, KnowledgeBaseID: "kb-any"}) {
t.Fatal("all-mode agent should permit in-tenant chunks")
}
}
@@ -0,0 +1,142 @@
package service
import (
"context"
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
)
type stubAgentForEmbed struct {
interfaces.CustomAgentService
agent *types.CustomAgent
err error
}
func (s *stubAgentForEmbed) GetAgentByID(_ context.Context, _ string) (*types.CustomAgent, error) {
if s.err != nil {
return nil, s.err
}
return s.agent, nil
}
func TestResolveKnowledgeBaseIDsFromAgent(t *testing.T) {
svc := &embedChannelService{
agentService: &stubAgentForEmbed{
agent: &types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
KnowledgeBases: []string{"kb-a", "kb-b"},
},
},
},
}
ids := svc.resolveKnowledgeBaseIDs(context.Background(), &types.EmbedChannel{
AgentID: "agent-1",
})
if len(ids) != 2 || ids[0] != "kb-a" || ids[1] != "kb-b" {
t.Fatalf("unexpected kb ids: %#v", ids)
}
}
func TestPublicConfigUsesAgentKBs(t *testing.T) {
svc := &embedChannelService{
agentService: &stubAgentForEmbed{
agent: &types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
KnowledgeBases: []string{"kb-primary"},
},
},
},
}
cfg := svc.PublicConfig(context.Background(), &types.EmbedChannel{
ID: "ch-1",
AgentID: "agent-1",
Name: "Support",
})
if len(cfg.KnowledgeBaseIDs) != 1 || cfg.KnowledgeBaseIDs[0] != "kb-primary" {
t.Fatalf("unexpected public config: %#v", cfg)
}
if cfg.AgentID != "agent-1" || cfg.ChannelID != "ch-1" {
t.Fatalf("unexpected ids: %#v", cfg)
}
if cfg.DisplayTitle != "Support" {
t.Fatalf("display_title = %q, want channel name", cfg.DisplayTitle)
}
}
func TestPublicConfigDisplayTitlePrefersPageTitle(t *testing.T) {
svc := &embedChannelService{
agentService: &stubAgentForEmbed{
agent: &types.CustomAgent{
Name: "Agent Name",
},
},
}
cfg := svc.PublicConfig(context.Background(), &types.EmbedChannel{
ID: "ch-3",
AgentID: "agent-3",
Name: "Internal Channel",
PageTitle: "Visitor Chat",
})
if cfg.DisplayTitle != "Visitor Chat" {
t.Fatalf("display_title = %q, want page title", cfg.DisplayTitle)
}
}
func TestPublicConfigIncludesCapabilityFlags(t *testing.T) {
svc := &embedChannelService{
agentService: &stubAgentForEmbed{
agent: &types.CustomAgent{
Config: types.CustomAgentConfig{
KBSelectionMode: "all",
WebSearchEnabled: true,
},
},
},
}
cfg := svc.PublicConfig(context.Background(), &types.EmbedChannel{
ID: "ch-cap",
AgentID: "agent-cap",
AllowWebSearch: true,
AllowMemory: true,
WidgetPosition: "top-left",
})
if !cfg.AllowWebSearch {
t.Fatalf("allow_web_search = false, want true")
}
if !cfg.AllowMemory {
t.Fatalf("allow_memory = false, want true")
}
if !cfg.AgentWebSearchEnabled {
t.Fatalf("agent_web_search_enabled = false, want true")
}
if cfg.WidgetPosition != "top-left" {
t.Fatalf("widget_position = %q, want top-left", cfg.WidgetPosition)
}
}
func TestPublicConfigDisplayTitleFallsBackToAgentName(t *testing.T) {
svc := &embedChannelService{
agentService: &stubAgentForEmbed{
agent: &types.CustomAgent{
Name: "客服助手",
Config: types.CustomAgentConfig{
KBSelectionMode: "all",
},
},
},
}
cfg := svc.PublicConfig(context.Background(), &types.EmbedChannel{
ID: "ch-2",
AgentID: "agent-2",
})
if cfg.DisplayTitle != "客服助手" {
t.Fatalf("display_title = %q, want agent name", cfg.DisplayTitle)
}
if cfg.AgentName != "客服助手" {
t.Fatalf("agent_name = %q", cfg.AgentName)
}
}
@@ -0,0 +1,143 @@
package service
import (
"context"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"encoding/base64"
"errors"
"strings"
"time"
"github.com/Tencent/WeKnora/internal/types"
"github.com/redis/go-redis/v9"
)
const (
embedSessionTokenPrefix = "ems_"
embedSessionRedisPrefix = "embed:session:"
embedSessionTTL = 30 * time.Minute
)
var ErrEmbedSessionUnavailable = errors.New("embed session tokens unavailable")
func generateEmbedSessionToken() (string, error) {
buf := make([]byte, embedTokenBytes)
if _, err := rand.Read(buf); err != nil {
return "", err
}
return embedSessionTokenPrefix + base64.RawURLEncoding.EncodeToString(buf), nil
}
// IssueSessionToken mints a short-lived session token bound to channelID.
func (s *embedChannelService) IssueSessionToken(ctx context.Context, channelID string) (string, int, error) {
if s.redis == nil {
return "", 0, ErrEmbedSessionUnavailable
}
channelID = strings.TrimSpace(channelID)
if channelID == "" {
return "", 0, ErrEmbedTokenInvalid
}
token, err := generateEmbedSessionToken()
if err != nil {
return "", 0, err
}
key := embedSessionRedisPrefix + token
if err := s.redis.Set(ctx, key, channelID, embedSessionTTL).Err(); err != nil {
return "", 0, err
}
return token, int(embedSessionTTL.Seconds()), nil
}
// ResolveSessionToken returns the channel ID stored for a session token.
func (s *embedChannelService) ResolveSessionToken(ctx context.Context, token string) (string, error) {
token = strings.TrimSpace(token)
if !strings.HasPrefix(token, embedSessionTokenPrefix) {
return "", ErrEmbedTokenInvalid
}
if s.redis == nil {
return "", ErrEmbedSessionUnavailable
}
channelID, err := s.redis.Get(ctx, embedSessionRedisPrefix+token).Result()
if err == redis.Nil {
return "", ErrEmbedTokenInvalid
}
if err != nil {
return "", err
}
channelID = strings.TrimSpace(channelID)
if channelID == "" {
return "", ErrEmbedTokenInvalid
}
return channelID, nil
}
// LookupEnabledChannel loads an embed channel and verifies it is enabled.
func (s *embedChannelService) LookupEnabledChannel(ctx context.Context, channelID string) (*types.EmbedChannel, error) {
channelID = strings.TrimSpace(channelID)
if channelID == "" {
return nil, ErrEmbedTokenInvalid
}
ch, err := s.repo.GetByID(ctx, channelID)
if err != nil {
return nil, err
}
if ch == nil {
return nil, ErrEmbedTokenInvalid
}
if !ch.Enabled {
return nil, ErrEmbedChannelDisabled
}
return ch, nil
}
// IsEmbedSessionToken reports whether token is a session token (ems_ prefix).
func IsEmbedSessionToken(token string) bool {
return strings.HasPrefix(strings.TrimSpace(token), embedSessionTokenPrefix)
}
// SignEmbedSessionHandle binds a chat session id to its embed channel with an
// HMAC keyed by the channel's (server-only) publish token. The handle is handed
// to the widget at session-creation time and must be presented on every history
// load / chat call. Because the session id travels in the request path (and can
// land in access logs), this signature — sent in a header, never logged — is the
// real authorization secret: a leaked session id is useless without it. Rotating
// the channel token invalidates outstanding handles, which is acceptable.
func SignEmbedSessionHandle(ch *types.EmbedChannel, sessionID string) string {
if ch == nil || strings.TrimSpace(sessionID) == "" {
return ""
}
mac := hmac.New(sha256.New, []byte(ch.PublishToken))
mac.Write([]byte(ch.ID + "|" + sessionID))
return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
}
// VerifyEmbedSessionHandle reports whether sig is a valid handle for sessionID
// on channel ch, using a constant-time comparison.
func VerifyEmbedSessionHandle(ch *types.EmbedChannel, sessionID, sig string) bool {
sig = strings.TrimSpace(sig)
if sig == "" {
return false
}
expected := SignEmbedSessionHandle(ch, sessionID)
if expected == "" {
return false
}
return subtle.ConstantTimeCompare([]byte(expected), []byte(sig)) == 1
}
// IssuePreviewSession mints a short-lived session token for management UI preview.
func (s *embedChannelService) IssuePreviewSession(
ctx context.Context, tenantID uint64, channelID string,
) (string, int, error) {
ch, err := s.getOwned(ctx, tenantID, channelID)
if err != nil {
return "", 0, err
}
if !ch.Enabled {
return "", 0, ErrEmbedChannelDisabled
}
return s.IssueSessionToken(ctx, ch.ID)
}
@@ -0,0 +1,85 @@
package service
import (
"context"
"testing"
"github.com/Tencent/WeKnora/internal/types"
)
func TestEmbedSessionHandleSignVerify(t *testing.T) {
ch := &types.EmbedChannel{ID: "ch-1", PublishToken: "em_secret_token"}
const sessionID = "11111111-2222-3333-4444-555555555555"
sig := SignEmbedSessionHandle(ch, sessionID)
if sig == "" {
t.Fatal("expected a non-empty signature")
}
if !VerifyEmbedSessionHandle(ch, sessionID, sig) {
t.Fatal("valid handle should verify")
}
// Tampered session id must not verify with the same signature.
if VerifyEmbedSessionHandle(ch, "00000000-0000-0000-0000-000000000000", sig) {
t.Fatal("signature must be bound to the session id")
}
// A different channel token (e.g. after rotation) invalidates the handle.
rotated := &types.EmbedChannel{ID: "ch-1", PublishToken: "em_rotated_token"}
if VerifyEmbedSessionHandle(rotated, sessionID, sig) {
t.Fatal("rotating the channel token must invalidate old handles")
}
// A different channel id must not verify.
other := &types.EmbedChannel{ID: "ch-2", PublishToken: "em_secret_token"}
if VerifyEmbedSessionHandle(other, sessionID, sig) {
t.Fatal("signature must be bound to the channel id")
}
// Empty / missing signature is rejected.
if VerifyEmbedSessionHandle(ch, sessionID, "") {
t.Fatal("empty signature must be rejected")
}
if SignEmbedSessionHandle(nil, sessionID) != "" {
t.Fatal("nil channel must yield empty signature")
}
if SignEmbedSessionHandle(ch, "") != "" {
t.Fatal("empty session id must yield empty signature")
}
}
func TestIsEmbedSessionToken(t *testing.T) {
if !IsEmbedSessionToken("ems_abc123") {
t.Fatal("expected ems_ prefix to be session token")
}
if IsEmbedSessionToken("em_abc123") {
t.Fatal("publish token must not be treated as session token")
}
if IsEmbedSessionToken("") {
t.Fatal("empty token must not match")
}
}
func TestIssueSessionTokenWithoutRedis(t *testing.T) {
svc := &embedChannelService{redis: nil}
_, _, err := svc.IssueSessionToken(context.Background(), "channel-1")
if err != ErrEmbedSessionUnavailable {
t.Fatalf("expected ErrEmbedSessionUnavailable, got %v", err)
}
}
func TestResolveSessionTokenWithoutRedis(t *testing.T) {
svc := &embedChannelService{redis: nil}
_, err := svc.ResolveSessionToken(context.Background(), "ems_test")
if err != ErrEmbedSessionUnavailable {
t.Fatalf("expected ErrEmbedSessionUnavailable, got %v", err)
}
}
func TestResolveSessionTokenRejectsPublishToken(t *testing.T) {
svc := &embedChannelService{redis: nil}
_, err := svc.ResolveSessionToken(context.Background(), "em_publish_only")
if err != ErrEmbedTokenInvalid {
t.Fatalf("expected ErrEmbedTokenInvalid for publish token, got %v", err)
}
}
@@ -0,0 +1,111 @@
package service
import (
"bytes"
"context"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
secutils "github.com/Tencent/WeKnora/internal/utils"
)
const embedWebhookTimeout = 5 * time.Second
// ErrEmbedWebhookURLInvalid is returned when a webhook URL fails format or SSRF checks.
var ErrEmbedWebhookURLInvalid = errors.New("invalid embed webhook URL")
// ValidateEmbedWebhookURL checks an optional outbound webhook URL. Empty is allowed.
func ValidateEmbedWebhookURL(raw string) error {
trimmed := strings.TrimSpace(raw)
if trimmed == "" {
return nil
}
parsed, err := url.Parse(trimmed)
if err != nil || parsed.Host == "" {
return fmt.Errorf("%w: webhook URL must be a valid http(s) URL", ErrEmbedWebhookURLInvalid)
}
switch parsed.Scheme {
case "http", "https":
default:
return fmt.Errorf("%w: webhook URL must use http or https", ErrEmbedWebhookURLInvalid)
}
if err := secutils.ValidateURLForSSRF(trimmed); err != nil {
if hint := secutils.FormatSSRFError("Webhook URL", trimmed, err); hint != "" {
return fmt.Errorf("%w: %s", ErrEmbedWebhookURLInvalid, hint)
}
return fmt.Errorf("%w: %v", ErrEmbedWebhookURLInvalid, err)
}
return nil
}
// DispatchEmbedWebhook POSTs an event to the channel webhook URL (best-effort, async).
func DispatchEmbedWebhook(ch *types.EmbedChannel, eventType, sessionID string, payload map[string]any) {
if ch == nil {
return
}
url := strings.TrimSpace(ch.WebhookURL)
if url == "" {
return
}
if err := ValidateEmbedWebhookURL(url); err != nil {
logger.Warnf(context.Background(), "[embed_webhook] skip dispatch %s: %v", eventType, err)
return
}
body := map[string]any{
"type": eventType,
"channel_id": ch.ID,
"session_id": sessionID,
"timestamp": time.Now().UTC().Format(time.RFC3339),
}
for k, v := range payload {
body[k] = v
}
raw, err := json.Marshal(body)
if err != nil {
return
}
secret := strings.TrimSpace(ch.WebhookSecret)
go func() {
ctx, cancel := context.WithTimeout(context.Background(), embedWebhookTimeout)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(raw))
if err != nil {
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("User-Agent", "WeKnora-Embed-Webhook/1.0")
if secret != "" {
mac := hmac.New(sha256.New, []byte(secret))
_, _ = mac.Write(raw)
req.Header.Set("X-WeKnora-Signature", "sha256="+hex.EncodeToString(mac.Sum(nil)))
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
logger.Warnf(context.Background(), "[embed_webhook] dispatch %s failed: %v", eventType, err)
return
}
defer resp.Body.Close()
_, _ = io.Copy(io.Discard, resp.Body)
if resp.StatusCode >= 300 {
logger.Warnf(context.Background(), "[embed_webhook] dispatch %s HTTP %d", eventType, resp.StatusCode)
}
}()
}
// SignEmbedWebhookBody returns the hex HMAC signature for tests.
func SignEmbedWebhookBody(secret string, raw []byte) string {
mac := hmac.New(sha256.New, []byte(secret))
_, _ = mac.Write(raw)
return hex.EncodeToString(mac.Sum(nil))
}
@@ -0,0 +1,35 @@
package service
import "testing"
func TestValidateEmbedWebhookURL(t *testing.T) {
withSSRFWhitelist(t, "*.example.com,127.0.0.1")
if err := ValidateEmbedWebhookURL(""); err != nil {
t.Fatalf("empty URL should be allowed: %v", err)
}
if err := ValidateEmbedWebhookURL("https://hooks.example.com/weknora/events"); err != nil {
t.Fatalf("whitelisted public https URL should pass: %v", err)
}
if err := ValidateEmbedWebhookURL("ftp://hooks.example.com/x"); err == nil {
t.Fatal("expected non-http(s) scheme to fail")
}
if err := ValidateEmbedWebhookURL("http://127.0.0.1/webhook"); err != nil {
t.Fatalf("whitelisted loopback should pass: %v", err)
}
if err := ValidateEmbedWebhookURL("http://169.254.169.254/latest/meta-data/"); err == nil {
t.Fatal("expected link-local metadata URL to be blocked")
}
}
func TestSignEmbedWebhookBody(t *testing.T) {
raw := []byte(`{"type":"message_sent","query":"hi"}`)
sig := SignEmbedWebhookBody("test-secret", raw)
if sig == "" || len(sig) != 64 {
t.Fatalf("unexpected signature: %q", sig)
}
sig2 := SignEmbedWebhookBody("test-secret", raw)
if sig != sig2 {
t.Fatal("signature not deterministic")
}
}