WeKnora/internal/plugin/configschema/schema.go

311 lines
9.8 KiB
Go

// Package configschema describes configuration with a subset of JSON Schema
// (draft 2020-12) plus a few x- keywords for the UI, and handles the secret
// fields such a schema marks: encrypting them at rest, redacting them in
// responses and keeping them when an update sends the redaction back.
//
// One schema drives both the form the frontend renders and the server-side
// validation, replacing the per-integration field descriptors (model vendor
// ExtraField, web search config fields, hardcoded connector and IM forms).
package configschema
import (
"encoding/json"
"errors"
"fmt"
"regexp"
"sort"
"strings"
)
// Types a schema node may declare.
const (
TypeObject = "object"
TypeString = "string"
TypeNumber = "number"
TypeInteger = "integer"
TypeBoolean = "boolean"
TypeArray = "array"
)
// Schema is one node of a configuration schema. The root is an object whose
// properties are the fields of a form.
type Schema struct {
Type string `json:"type,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
Default any `json:"default,omitempty"`
Const any `json:"const,omitempty"`
Enum []any `json:"enum,omitempty"`
// OneOf lists labelled choices: each entry carries a const and a title.
OneOf []*Schema `json:"oneOf,omitempty"`
MinLength *int `json:"minLength,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
// Format is "uri" or "email"; other formats are carried but not checked.
Format string `json:"format,omitempty"`
// Secret marks a string that is encrypted at rest, redacted in
// responses, and kept when an update sends the redaction back.
Secret bool `json:"x-secret,omitempty"`
// Widget picks the form control (password, textarea, select, switch,
// headers, ...). Empty means the frontend picks from the type; "hidden"
// keeps a field out of the form while still declaring it (a secret set
// by another flow, such as WeChat's QR binding).
Widget string `json:"x-widget,omitempty"`
Placeholder string `json:"x-placeholder,omitempty"`
// I18n carries localized title / description / placeholder:
// {"title": {"zh-CN": "..."}}.
I18n map[string]map[string]string `json:"x-i18n,omitempty"`
// I18nKeys names frontend locale keys for title / description /
// placeholder. Builtins use them; the frontend falls back to I18n and
// then to the plain text when a key is missing.
I18nKeys map[string]string `json:"x-i18n-keys,omitempty"`
// VisibleIf shows the field only while every listed sibling field
// equals the given value.
VisibleIf map[string]any `json:"x-visible-if,omitempty"`
Group string `json:"x-group,omitempty"`
// Order sorts fields in the form (lower first); ties sort by key.
Order int `json:"x-order,omitempty"`
// ModelTypes limits a model vendor field to some model types.
ModelTypes []string `json:"x-model-types,omitempty"`
// Options fills a field's choices from the plugin (its
// /v1/options/{name} endpoint), for choices that depend on the
// account: projects, spaces, channels.
Options *OptionsSource `json:"x-options,omitempty"`
// OAuth makes a string field an authorization: the form shows a
// connect button, WeKnora runs the OAuth code flow and the field holds
// a reference WeKnora swaps for a fresh access token at call time.
OAuth *OAuthSpec `json:"x-oauth,omitempty"`
}
// OptionsSource names where a field's choices come from.
type OptionsSource struct {
// Name is the plugin's options endpoint: /v1/options/{name}.
Name string `json:"name"`
// DependsOn lists dotted paths of fields whose values the choices
// depend on; the form reloads them when those change.
DependsOn []string `json:"dependsOn,omitempty"`
// Search asks the plugin with what the user types (large lists).
Search bool `json:"search,omitempty"`
}
// OAuthSpec is an OAuth 2.0 authorization code flow.
type OAuthSpec struct {
AuthorizeURL string `json:"authorizeUrl"`
TokenURL string `json:"tokenUrl"`
Scopes []string `json:"scopes,omitempty"`
// ClientID and ClientSecret are usually ${system.<key>}: the OAuth app
// is registered once for the platform.
ClientID string `json:"clientId"`
ClientSecret string `json:"clientSecret,omitempty"`
// PKCE adds a code challenge (S256).
PKCE bool `json:"pkce,omitempty"`
// Params are extra authorize parameters (audience, prompt).
Params map[string]string `json:"params,omitempty"`
}
// Object returns an empty object schema.
func Object() *Schema { return &Schema{Type: TypeObject, Properties: map[string]*Schema{}} }
// Set adds a property and returns the parent for chaining. A required
// property is also listed in Required.
func (s *Schema) Set(key string, prop *Schema, required bool) *Schema {
if s.Properties == nil {
s.Properties = map[string]*Schema{}
}
s.Properties[key] = prop
if required {
s.Required = append(s.Required, key)
}
return s
}
// OrderedKeys returns property keys sorted by x-order, then by key.
func (s *Schema) OrderedKeys() []string {
keys := make([]string, 0, len(s.Properties))
for k := range s.Properties {
keys = append(keys, k)
}
sort.Slice(keys, func(i, j int) bool {
oi, oj := s.Properties[keys[i]].Order, s.Properties[keys[j]].Order
if oi != oj {
return oi < oj
}
return keys[i] < keys[j]
})
return keys
}
// Parse decodes a schema and checks that it stays within the supported
// subset.
func Parse(data []byte) (*Schema, error) {
var s Schema
if err := json.Unmarshal(data, &s); err != nil {
return nil, fmt.Errorf("decode config schema: %w", err)
}
if err := s.Check(); err != nil {
return nil, err
}
return &s, nil
}
// Check verifies that a schema uses only what this package understands. The
// root must be an object, since a configuration is always a set of fields.
func (s *Schema) Check() error {
if s.Type != TypeObject {
return errors.New("config schema root must be an object")
}
var errs []error
s.check("", &errs)
return errors.Join(errs...)
}
func (s *Schema) check(path string, errs *[]error) {
fail := func(format string, args ...any) {
*errs = append(*errs, fmt.Errorf("%s: %s", displayPath(path), fmt.Sprintf(format, args...)))
}
switch s.Type {
case TypeObject:
for _, key := range s.Required {
if _, ok := s.Properties[key]; !ok {
fail("required field %q has no property", key)
}
}
for _, key := range s.OrderedKeys() {
s.Properties[key].check(joinPath(path, key), errs)
}
case TypeArray:
if s.Items == nil {
fail("array needs items")
} else {
if s.Items.containsSecret() {
fail("secrets inside arrays are not supported")
}
s.Items.check(path+"[]", errs)
}
case TypeString, TypeNumber, TypeInteger, TypeBoolean:
default:
fail("unsupported type %q", s.Type)
}
if s.Secret && s.Type != TypeString {
fail("x-secret is only allowed on strings")
}
if s.Pattern != "" {
if _, err := regexp.Compile(s.Pattern); err != nil {
fail("invalid pattern: %v", err)
}
}
for _, choice := range s.OneOf {
if choice.Const == nil {
fail("oneOf entries must carry a const")
}
}
if o := s.Options; o != nil {
if !optionsNamePattern.MatchString(o.Name) {
fail("x-options.name must be lowercase letters, digits, '_' or '-'")
}
if s.Type != TypeString && (s.Type != TypeArray || s.Items == nil || s.Items.Type != TypeString) {
fail("x-options is only allowed on strings or arrays of strings")
}
}
if o := s.OAuth; o != nil {
if s.Type != TypeString {
fail("x-oauth is only allowed on strings")
}
if s.Secret {
fail("x-oauth fields hold a reference, not a secret; drop x-secret")
}
for name, u := range map[string]string{"authorizeUrl": o.AuthorizeURL, "tokenUrl": o.TokenURL} {
if !strings.HasPrefix(u, "https://") && !strings.HasPrefix(u, "http://localhost") {
fail("x-oauth.%s must be an https URL", name)
}
}
if o.ClientID == "" {
fail("x-oauth.clientId is required")
}
}
}
// OAuthRefPrefix starts the value of an x-oauth field: a reference to an
// OAuth connection WeKnora keeps (its tokens never reach the browser).
const OAuthRefPrefix = "oauth:"
var oauthRefPattern = regexp.MustCompile(`^oauth:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
// IsOAuthRef reports whether a value references an OAuth connection.
func IsOAuthRef(v string) bool { return oauthRefPattern.MatchString(v) }
// optionsNamePattern is an options endpoint name.
var optionsNamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{0,63}$`)
func (s *Schema) containsSecret() bool {
if s.Secret {
return true
}
for _, p := range s.Properties {
if p.containsSecret() {
return true
}
}
return s.Items != nil && s.Items.containsSecret()
}
// OAuthFields returns the x-oauth fields by dotted path. A nil schema has
// none.
func (s *Schema) OAuthFields() map[string]*OAuthSpec {
out := map[string]*OAuthSpec{}
if s == nil {
return out
}
var walk func(n *Schema, path string)
walk = func(n *Schema, path string) {
if n.OAuth != nil {
out[path] = n.OAuth
}
for key, p := range n.Properties {
walk(p, joinPath(path, key))
}
}
walk(s, "")
return out
}
// SecretPaths lists the dotted paths of every secret field, sorted.
func (s *Schema) SecretPaths() []string {
var out []string
var walk func(n *Schema, path string)
walk = func(n *Schema, path string) {
if n.Secret {
out = append(out, path)
}
for key, p := range n.Properties {
walk(p, joinPath(path, key))
}
}
walk(s, "")
sort.Strings(out)
return out
}
func joinPath(parent, key string) string {
if parent == "" {
return key
}
return parent + "." + key
}
func displayPath(path string) string {
if path == "" {
return "(root)"
}
return path
}