Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

9.5 KB
Raw Blame
package types

import (
	"context"
	"fmt"
	"strings"
)

const (
	PrincipalWebUser         = "web_user"
	PrincipalAPITenant       = "api_tenant"
	PrincipalAPIPlatform     = "api_platform"
	PrincipalAPIExternalUser = "api_external_user"
	PrincipalIMUser          = "im_user"
	PrincipalEmbedChannel    = "embed_channel"
	PrincipalEmbedSession    = "embed_session"
	PrincipalEmbedVisitor    = "embed_visitor"
	PrincipalMCPEndpoint     = "mcp_endpoint"
)

// EmbedVisitorHeader is sent by the embed widget to identify a browser visitor
// across chat sessions within the same channel.
const EmbedVisitorHeader = "X-Embed-Visitor"

// SessionOwnerAPITenantKeyPrefix prefixes sessions.user_id for rows created by a
// tenant API key. The full owner id is "api_tenant_key:<tenantID>:<keyID>", so a
// LIKE '<prefix>%' selects every API-key session in the tenant.
const SessionOwnerAPITenantKeyPrefix = "api_tenant_key:"

// SessionOwnerAPIExternalUserPrefix prefixes sessions.user_id for rows created
// by a tenant API key whose request resolved an external-user identity. The
// remainder is "<tenantID>:<externalUserID>".
const SessionOwnerAPIExternalUserPrefix = PrincipalAPIExternalUser + ":"

// IsAPISessionOwnerID reports whether a stored session owner was produced by
// a tenant API-key request, with or without an external-user identity.
func IsAPISessionOwnerID(ownerID string) bool {
	ownerID = strings.TrimSpace(ownerID)
	return strings.HasPrefix(ownerID, SessionOwnerAPITenantKeyPrefix) ||
		strings.HasPrefix(ownerID, SessionOwnerAPIExternalUserPrefix)
}

// Principal represents the terminal caller for per-subject isolation features.
// It is intentionally separate from UserID: many principals, such as IM users
// or embed visitors, are not WeKnora accounts and must not imply RBAC rights.
type Principal struct {
	Type string
	ID   string
	// ActingVia names what acts for this principal without them present,
	// e.g. "automation:<id>". Empty when the principal acts in person. It
	// does not change who is authorized or StorageID: the principal still
	// owns the run and answers its approvals.
	ActingVia string
}

func (p Principal) Normalize() Principal {
	return Principal{
		Type:      strings.TrimSpace(p.Type),
		ID:        strings.TrimSpace(p.ID),
		ActingVia: strings.TrimSpace(p.ActingVia),
	}
}

func (p Principal) Valid() bool {
	p = p.Normalize()
	return p.Type != "" && p.ID != ""
}

func (p Principal) StorageID() string {
	p = p.Normalize()
	if !p.Valid() {
		return ""
	}
	return p.Type + ":" + p.ID
}

func WithPrincipal(ctx context.Context, principal Principal) context.Context {
	principal = principal.Normalize()
	if !principal.Valid() {
		return ctx
	}
	return context.WithValue(ctx, PrincipalContextKey, principal)
}

func PrincipalFromContext(ctx context.Context) (Principal, bool) {
	if ctx == nil {
		return Principal{}, false
	}
	if p, ok := ctx.Value(PrincipalContextKey).(Principal); ok && p.Valid() {
		return p.Normalize(), true
	}
	if uid, ok := UserIDFromContext(ctx); ok && strings.TrimSpace(uid) != "" {
		return Principal{Type: PrincipalWebUser, ID: uid}, true
	}
	return Principal{}, false
}

func WithEmbedVisitorID(ctx context.Context, visitorID string) context.Context {
	visitorID = strings.TrimSpace(visitorID)
	if visitorID == "" {
		return ctx
	}
	return context.WithValue(ctx, EmbedVisitorContextKey, visitorID)
}

func EmbedVisitorIDFromContext(ctx context.Context) string {
	if ctx == nil {
		return ""
	}
	if v, ok := ctx.Value(EmbedVisitorContextKey).(string); ok {
		return strings.TrimSpace(v)
	}
	return ""
}

// EmbedSessionPrincipal identifies a single embed visitor chat session.
// MCPEndpointPrincipal identifies calls made through a workspace MCP
// endpoint. Sessions and messages created by the ask tool are owned by it.
func MCPEndpointPrincipal(tenantID uint64, endpointID string) Principal {
	return Principal{
		Type: PrincipalMCPEndpoint,
		ID:   fmt.Sprintf("%d:%s", tenantID, endpointID),
	}
}

func EmbedSessionPrincipal(tenantID uint64, channelID, sessionID string) Principal {
	return Principal{
		Type: PrincipalEmbedSession,
		ID:   fmt.Sprintf("%d:%s:%s", tenantID, strings.TrimSpace(channelID), strings.TrimSpace(sessionID)),
	}
}

// EmbedVisitorPrincipal identifies one anonymous embed visitor (browser).
func EmbedVisitorPrincipal(tenantID uint64, channelID, visitorID string) Principal {
	return Principal{
		Type: PrincipalEmbedVisitor,
		ID:   fmt.Sprintf("%d:%s:%s", tenantID, strings.TrimSpace(channelID), strings.TrimSpace(visitorID)),
	}
}

// ValidateEmbedVisitorID checks the client-supplied anonymous visitor id.
func ValidateEmbedVisitorID(id string) error {
	id = strings.TrimSpace(id)
	if id == "" {
		return fmt.Errorf("empty embed visitor id")
	}
	if len(id) > 128 {
		return fmt.Errorf("embed visitor id too long (max 128)")
	}
	for _, r := range id {
		if r < 0x20 || r == 0x7f {
			return fmt.Errorf("embed visitor id contains invalid characters")
		}
	}
	return nil
}

// MCPOAuthPrincipalFromContext resolves the OAuth token principal for ctx.
// Embed chat sessions map to a per-visitor principal when X-Embed-Visitor is
// present; otherwise OAuth falls back to the chat session principal.
func MCPOAuthPrincipalFromContext(ctx context.Context) Principal {
	p, ok := PrincipalFromContext(ctx)
	if !ok {
		return Principal{}
	}
	p = p.Normalize()
	if p.Type != PrincipalEmbedSession {
		return p
	}
	visitorID := EmbedVisitorIDFromContext(ctx)
	if visitorID == "" {
		return p
	}
	parts := strings.SplitN(p.ID, ":", 3)
	if len(parts) < 2 {
		return p
	}
	tenantPart := strings.TrimSpace(parts[0])
	channelPart := strings.TrimSpace(parts[1])
	if tenantPart == "" || channelPart == "" {
		return p
	}
	var tenantID uint64
	if _, err := fmt.Sscanf(tenantPart, "%d", &tenantID); err != nil || tenantID == 0 {
		return Principal{Type: PrincipalEmbedVisitor, ID: tenantPart + ":" + channelPart + ":" + visitorID}
	}
	return EmbedVisitorPrincipal(tenantID, channelPart, visitorID)
}

// SessionOwnerIDFromContext returns the sessions.user_id scope for the current
// caller. API external users and embed chat sessions use principal-derived IDs;
// tenant API keys are isolated per key id; MCP OAuth token storage uses
// MCPOAuthPrincipalFromContext (visitor-level for embed).
//
// PrincipalMCPEndpoint must resolve to StorageID() too: the MCP `ask` tool
// creates its session with `MCPEndpointPrincipal(...).StorageID()` and then
// looks it up through this function. Without the case below the lookup falls
// through to the raw user id ("mcp-<endpointID>"), which never matches the
// stored owner ("mcp_endpoint:<tenantID>:<endpointID>"), so every ask call
// failed with "failed to create user message: session not found".
func SessionOwnerIDFromContext(ctx context.Context) string {
	if p, ok := PrincipalFromContext(ctx); ok {
		switch p.Type {
		case PrincipalAPIExternalUser, PrincipalEmbedSession, PrincipalMCPEndpoint:
			return p.StorageID()
		case PrincipalAPITenant:
			if scope, ok := TenantAPIKeyScopeFromContext(ctx); ok && scope.KeyID > 0 {
				if tenantID, ok := TenantIDFromContext(ctx); ok && tenantID > 0 {
					return fmt.Sprintf("%s%d:%d", SessionOwnerAPITenantKeyPrefix, tenantID, scope.KeyID)
				}
			}
		}
	}
	userID, _ := UserIDFromContext(ctx)
	return userID
}

// Authentication sources recorded on sessions.owner_auth_source. The values
// match internal/sandbox/allocation.AuthSource.
const (
	AuthSourceWeb             = "web"
	AuthSourceAPITenantKey    = "api_tenant_key"
	AuthSourceAPIPlatformKey  = "api_platform_key"
	AuthSourceAPIDirectHeader = "api_direct_header"
	AuthSourceAPISignedToken  = "api_signed_token"
	AuthSourceEmbed           = "embed"
	AuthSourceIM              = "im"
	AuthSourceMCPEndpoint     = "mcp_endpoint"
	AuthSourceInternal        = "internal"
	AuthSourceUnknown         = "unknown"
)

// WithPrincipalAuthSource records how the request's principal was verified.
func WithPrincipalAuthSource(ctx context.Context, source string) context.Context {
	source = strings.TrimSpace(source)
	if source == "" {
		return ctx
	}
	return context.WithValue(ctx, PrincipalAuthSourceContextKey, source)
}

// PrincipalAuthSourceFromContext returns "" when no auth middleware ran.
func PrincipalAuthSourceFromContext(ctx context.Context) string {
	if ctx == nil {
		return ""
	}
	if v, ok := ctx.Value(PrincipalAuthSourceContextKey).(string); ok {
		return strings.TrimSpace(v)
	}
	return ""
}

// StampSessionOwnerSource overwrites the owner's authentication source from
// the verified request context. The caller's credentials only vouch for a row
// whose owner is the caller's own owner scope; anything else (internal
// services, a row created on someone's behalf) is recorded as internal. The
// owner's kind is not stored: it follows from the source and user_id.
func StampSessionOwnerSource(ctx context.Context, s *Session) {
	if s == nil {
		return
	}
	if strings.TrimSpace(s.UserID) == "" {
		s.OwnerAuthSource = AuthSourceUnknown
		return
	}
	source := PrincipalAuthSourceFromContext(ctx)
	if _, ok := PrincipalFromContext(ctx); !ok || source == "" || SessionOwnerIDFromContext(ctx) != s.UserID {
		s.OwnerAuthSource = AuthSourceInternal
		return
	}
	s.OwnerAuthSource = source
}

// AuthSourceForBoundOwnerID describes an owner bound after creation (MCP ask,
// embed backfill). Those binders only ever bind shared-entry or channel
// owners, so the result can never qualify a session for a shared machine.
func AuthSourceForBoundOwnerID(ownerID string) string {
	switch {
	case strings.HasPrefix(ownerID, PrincipalMCPEndpoint+":"):
		return AuthSourceMCPEndpoint
	case strings.HasPrefix(ownerID, PrincipalEmbedSession+":"):
		return AuthSourceEmbed
	default:
		return AuthSourceInternal
	}
}