311 lines
9.8 KiB
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
|
|
}
|