diff --git a/.github/workflows/control-plane.yml b/.github/workflows/control-plane.yml index d2c84e45..5395ca19 100644 --- a/.github/workflows/control-plane.yml +++ b/.github/workflows/control-plane.yml @@ -56,7 +56,7 @@ jobs: - name: Run tests working-directory: control-plane - run: go test ./... + run: go test -tags sqlite_fts5 ./... - name: Lint working-directory: control-plane diff --git a/.gitignore b/.gitignore index 3695860b..742bef14 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,14 @@ dist/ coverage.out *.test tmp/ +examples/go_agent_nodes/permission_agent_* +examples/go_agent_nodes/go_agent_nodes + +# Compiled binaries +control-plane/agentfield-server +control-plane/af +examples/**/go_agent_node* +!examples/**/*.go # Python __pycache__/ diff --git a/control-plane/.env.example b/control-plane/.env.example index a2e4b9ab..48f03768 100644 --- a/control-plane/.env.example +++ b/control-plane/.env.example @@ -48,6 +48,13 @@ AGENTFIELD_STORAGE_MODE=local # AGENTFIELD_STORAGE_CLOUD_CONNECTION_POOL=true # AGENTFIELD_STORAGE_CLOUD_REPLICATION_MODE=async +# VC Authorization +# Admin token for admin API endpoints (tag approval, policy management) +# AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN=admin-secret +# Internal token sent to agents during request forwarding. +# Agents with RequireOriginAuth=true validate this to ensure only the control plane can invoke them. +# AGENTFIELD_AUTHORIZATION_INTERNAL_TOKEN=internal-secret-token + # Development/Debug # GIN_MODE=debug # LOG_LEVEL=info diff --git a/control-plane/agentfield-server b/control-plane/agentfield-server deleted file mode 100755 index 74c03505..00000000 Binary files a/control-plane/agentfield-server and /dev/null differ diff --git a/control-plane/config/agentfield.yaml b/control-plane/config/agentfield.yaml index 508c8258..eff7dd4e 100644 --- a/control-plane/config/agentfield.yaml +++ b/control-plane/config/agentfield.yaml @@ -36,6 +36,11 @@ api: - "Accept" - "Authorization" - "X-Requested-With" + - "X-API-Key" + - "X-Admin-Token" + - "X-Caller-DID" + - "X-DID-Signature" + - "X-DID-Timestamp" exposed_headers: - "Content-Length" - "X-Total-Count" @@ -46,6 +51,13 @@ storage: local: database_path: "" kv_store_path: "" + postgres: + host: "localhost" + port: 5433 + database: "agentfield_dev" + user: "agentfield" + password: "agentfield" + sslmode: "disable" vector: enabled: true distance: "cosine" @@ -71,3 +83,62 @@ features: encryption: "AES-256-GCM" backup_enabled: true backup_interval: "24h" + authorization: + enabled: true + did_auth_enabled: false + domain: "localhost:8080" + timestamp_window_seconds: 300 + default_approval_duration_hours: 24 + admin_token: "admin-secret" + internal_token: "internal-secret-token" + tag_approval_rules: + default_mode: "auto" + rules: + - tags: ["sensitive", "financial", "payments"] + approval: "manual" + reason: "Sensitive/financial tags require admin review" + - tags: ["public", "analytics"] + approval: "auto" + reason: "Auto-approved" + access_policies: + - name: "analytics_to_data_service" + caller_tags: ["analytics"] + target_tags: ["data-service"] + allow_functions: ["query_*", "get_*", "analyze_*"] + deny_functions: ["delete_*", "update_*"] + constraints: + limit: + operator: "<=" + value: 1000 + action: "allow" + priority: 100 + - name: "payments_to_payments" + caller_tags: ["payments"] + target_tags: ["payments"] + allow_functions: ["process_*", "get_*"] + deny_functions: ["refund_*"] + constraints: + amount: + operator: "<=" + value: 10000 + action: "allow" + priority: 90 + connector: + enabled: true + token: "test-connector-token-123" + capabilities: + policy_management: + enabled: true + read_only: false + tag_management: + enabled: true + read_only: false + did_management: + enabled: false + reasoner_management: + enabled: true + read_only: false + status_read: + enabled: true + observability_config: + enabled: false diff --git a/control-plane/dev.sh b/control-plane/dev.sh index 4d3c6833..ca83e42d 100755 --- a/control-plane/dev.sh +++ b/control-plane/dev.sh @@ -2,8 +2,11 @@ # Start control plane with hot-reload using Air # # Usage: -# ./dev.sh # Start with hot-reload (SQLite mode) -# ./dev.sh postgres # Start with PostgreSQL (set AGENTFIELD_DATABASE_URL first) +# ./dev.sh # SQLite mode with hot-reload +# ./dev.sh postgres # PostgreSQL mode (starts postgres via docker-compose) +# ./dev.sh pg-stop # Stop the dev postgres container +# ./dev.sh pg-reset # Stop postgres and wipe its data volume +# ./dev.sh pg-test # Run Go postgres tests against dev database # # Prerequisites: # go install github.com/air-verse/air@v1.61.7 @@ -17,12 +20,37 @@ if ! command -v air &> /dev/null; then go install github.com/air-verse/air@v1.61.7 fi +pg_up() { + echo "Starting dev postgres..." + docker compose -f docker-compose.dev.yml up -d --wait + echo "Postgres ready at localhost:5432 (agentfield_dev)" +} + +pg_down() { + docker compose -f docker-compose.dev.yml down "$@" +} + case "${1:-}" in postgres|pg) + pg_up echo "Starting control plane with PostgreSQL (hot-reload)..." - export AGENTFIELD_STORAGE_MODE=postgresql + export AGENTFIELD_STORAGE_MODE=postgres air -c .air.toml ;; + pg-stop) + echo "Stopping dev postgres..." + pg_down + ;; + pg-reset) + echo "Stopping dev postgres and wiping data..." + pg_down -v + ;; + pg-test) + pg_up + echo "Running postgres storage tests..." + POSTGRES_TEST_URL="postgres://agentfield:agentfield@localhost:5433/agentfield_dev?sslmode=disable" \ + go test ./internal/storage/ -run TestPostgres -v -count=1 + ;; *) echo "Starting control plane with SQLite (hot-reload)..." export AGENTFIELD_STORAGE_MODE=local diff --git a/control-plane/docker-compose.dev.yml b/control-plane/docker-compose.dev.yml new file mode 100644 index 00000000..2691b584 --- /dev/null +++ b/control-plane/docker-compose.dev.yml @@ -0,0 +1,20 @@ +services: + postgres: + image: pgvector/pgvector:pg16 + container_name: agentfield-dev-postgres + environment: + POSTGRES_USER: agentfield + POSTGRES_PASSWORD: agentfield + POSTGRES_DB: agentfield_dev + ports: + - "5433:5432" + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U agentfield -d agentfield_dev"] + interval: 3s + timeout: 2s + retries: 10 + +volumes: + pgdata: diff --git a/control-plane/go.mod b/control-plane/go.mod index 282255d0..5d0eeaf7 100644 --- a/control-plane/go.mod +++ b/control-plane/go.mod @@ -23,6 +23,7 @@ require ( github.com/spf13/cobra v1.8.1 github.com/spf13/viper v1.20.1 github.com/stretchr/testify v1.10.0 + golang.org/x/crypto v0.37.0 golang.org/x/term v0.32.0 google.golang.org/grpc v1.67.3 google.golang.org/protobuf v1.36.6 @@ -94,7 +95,6 @@ require ( go.uber.org/atomic v1.9.0 // indirect go.uber.org/multierr v1.9.0 // indirect golang.org/x/arch v0.15.0 // indirect - golang.org/x/crypto v0.37.0 // indirect golang.org/x/net v0.38.0 // indirect golang.org/x/sync v0.13.0 // indirect golang.org/x/sys v0.36.0 // indirect diff --git a/control-plane/internal/application/container.go b/control-plane/internal/application/container.go index d594e7de..76353c5e 100644 --- a/control-plane/internal/application/container.go +++ b/control-plane/internal/application/container.go @@ -7,6 +7,7 @@ import ( "github.com/Agent-Field/agentfield/control-plane/internal/cli/framework" "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/Agent-Field/agentfield/control-plane/internal/encryption" "github.com/Agent-Field/agentfield/control-plane/internal/core/services" "github.com/Agent-Field/agentfield/control-plane/internal/infrastructure/process" "github.com/Agent-Field/agentfield/control-plane/internal/infrastructure/storage" @@ -55,6 +56,9 @@ func CreateServiceContainer(cfg *config.Config, agentfieldHome string) *framewor // Create DID registry with database storage (required) if storageProvider != nil { didRegistry = didServices.NewDIDRegistryWithStorage(storageProvider) + if passphrase := cfg.Features.DID.Keystore.EncryptionPassphrase; passphrase != "" { + didRegistry.SetEncryptionService(encryption.NewEncryptionService(passphrase)) + } } else { // DID registry requires database storage, skip if not available didRegistry = nil diff --git a/control-plane/internal/config/config.go b/control-plane/internal/config/config.go index 139b973e..9c34ca76 100644 --- a/control-plane/internal/config/config.go +++ b/control-plane/internal/config/config.go @@ -5,6 +5,7 @@ import ( "os" // Added for os.Stat, os.ReadFile "path/filepath" // Added for filepath.Join "strconv" + "strings" "time" "gopkg.in/yaml.v3" // Added for yaml.Unmarshal @@ -69,18 +70,92 @@ type ExecutionQueueConfig struct { // FeatureConfig holds configuration for enabling/disabling features. type FeatureConfig struct { - DID DIDConfig `yaml:"did" mapstructure:"did"` + DID DIDConfig `yaml:"did" mapstructure:"did"` + Connector ConnectorConfig `yaml:"connector" mapstructure:"connector"` +} + +// ConnectorConfig holds configuration for the connector service integration. +type ConnectorConfig struct { + Enabled bool `yaml:"enabled" mapstructure:"enabled"` + Token string `yaml:"token" mapstructure:"token"` + Capabilities map[string]ConnectorCapability `yaml:"capabilities" mapstructure:"capabilities"` +} + +// ConnectorCapability defines whether a capability domain is enabled and its access mode. +type ConnectorCapability struct { + Enabled bool `yaml:"enabled" mapstructure:"enabled"` + ReadOnly bool `yaml:"read_only" mapstructure:"read_only"` } // DIDConfig holds configuration for DID identity system. type DIDConfig struct { - Enabled bool `yaml:"enabled" mapstructure:"enabled" default:"true"` - Method string `yaml:"method" mapstructure:"method" default:"did:key"` - KeyAlgorithm string `yaml:"key_algorithm" mapstructure:"key_algorithm" default:"Ed25519"` - DerivationMethod string `yaml:"derivation_method" mapstructure:"derivation_method" default:"BIP32"` - KeyRotationDays int `yaml:"key_rotation_days" mapstructure:"key_rotation_days" default:"90"` - VCRequirements VCRequirements `yaml:"vc_requirements" mapstructure:"vc_requirements"` - Keystore KeystoreConfig `yaml:"keystore" mapstructure:"keystore"` + Enabled bool `yaml:"enabled" mapstructure:"enabled" default:"true"` + Method string `yaml:"method" mapstructure:"method" default:"did:key"` + KeyAlgorithm string `yaml:"key_algorithm" mapstructure:"key_algorithm" default:"Ed25519"` + DerivationMethod string `yaml:"derivation_method" mapstructure:"derivation_method" default:"BIP32"` + KeyRotationDays int `yaml:"key_rotation_days" mapstructure:"key_rotation_days" default:"90"` + VCRequirements VCRequirements `yaml:"vc_requirements" mapstructure:"vc_requirements"` + Keystore KeystoreConfig `yaml:"keystore" mapstructure:"keystore"` + Authorization AuthorizationConfig `yaml:"authorization" mapstructure:"authorization"` +} + +// AuthorizationConfig holds configuration for VC-based authorization. +type AuthorizationConfig struct { + // Enabled determines if the authorization system is active + Enabled bool `yaml:"enabled" mapstructure:"enabled" default:"false"` + // DIDAuthEnabled enables DID-based authentication on API routes + DIDAuthEnabled bool `yaml:"did_auth_enabled" mapstructure:"did_auth_enabled" default:"false"` + // Domain is the domain used for did:web identifiers (e.g., "localhost:8080") + Domain string `yaml:"domain" mapstructure:"domain" default:"localhost:8080"` + // TimestampWindowSeconds is the allowed time drift for DID signature timestamps + TimestampWindowSeconds int64 `yaml:"timestamp_window_seconds" mapstructure:"timestamp_window_seconds" default:"300"` + // DefaultApprovalDurationHours is the default duration for permission approvals + DefaultApprovalDurationHours int `yaml:"default_approval_duration_hours" mapstructure:"default_approval_duration_hours" default:"720"` + // AdminToken is a separate token required for admin operations (tag approval, + // policy management). If empty, admin routes fall back to the standard API key. + AdminToken string `yaml:"admin_token" mapstructure:"admin_token"` + // InternalToken is sent as Authorization: Bearer header when the control plane + // forwards execution requests to agents. Agents with RequireOriginAuth enabled + // validate this token, preventing direct access to their HTTP ports. + InternalToken string `yaml:"internal_token" mapstructure:"internal_token"` + // TagApprovalRules configures how proposed tags are handled at registration time. + // Default mode is "auto" (all tags auto-approved) for backward compatibility. + TagApprovalRules TagApprovalRulesConfig `yaml:"tag_approval_rules" mapstructure:"tag_approval_rules"` + // AccessPolicies defines tag-based authorization policies for cross-agent calls. + AccessPolicies []AccessPolicyConfig `yaml:"access_policies" mapstructure:"access_policies"` +} + +// TagApprovalRulesConfig configures tag approval behavior at registration. +type TagApprovalRulesConfig struct { + // DefaultMode is the approval mode for tags not matching any rule: "auto", "manual", or "forbidden". + // Default: "auto" (backward compat — all tags auto-approved when no rules configured). + DefaultMode string `yaml:"default_mode" mapstructure:"default_mode"` + Rules []TagApprovalRule `yaml:"rules" mapstructure:"rules"` +} + +// TagApprovalRule defines the approval mode for a set of tags. +type TagApprovalRule struct { + Tags []string `yaml:"tags" mapstructure:"tags"` + Approval string `yaml:"approval" mapstructure:"approval"` // "auto", "manual", "forbidden" + Reason string `yaml:"reason" mapstructure:"reason"` +} + +// AccessPolicyConfig defines a tag-based authorization policy for cross-agent calls. +type AccessPolicyConfig struct { + Name string `yaml:"name" mapstructure:"name"` + CallerTags []string `yaml:"caller_tags" mapstructure:"caller_tags"` + TargetTags []string `yaml:"target_tags" mapstructure:"target_tags"` + AllowFunctions []string `yaml:"allow_functions" mapstructure:"allow_functions"` + DenyFunctions []string `yaml:"deny_functions" mapstructure:"deny_functions"` + Constraints map[string]ConstraintConfig `yaml:"constraints" mapstructure:"constraints"` + Action string `yaml:"action" mapstructure:"action"` // "allow" or "deny" + Priority int `yaml:"priority" mapstructure:"priority"` // higher = evaluated first +} + +// ConstraintConfig defines a parameter constraint for a policy. +type ConstraintConfig struct { + Operator string `yaml:"operator" mapstructure:"operator"` // "<=", ">=", "==", "!=", "<", ">" + Value any `yaml:"value" mapstructure:"value"` } // VCRequirements holds VC generation requirements. @@ -96,11 +171,12 @@ type VCRequirements struct { // KeystoreConfig holds keystore configuration. type KeystoreConfig struct { - Type string `yaml:"type" mapstructure:"type" default:"local"` - Path string `yaml:"path" mapstructure:"path" default:"./data/keys"` - Encryption string `yaml:"encryption" mapstructure:"encryption" default:"AES-256-GCM"` - BackupEnabled bool `yaml:"backup_enabled" mapstructure:"backup_enabled" default:"true"` - BackupInterval string `yaml:"backup_interval" mapstructure:"backup_interval" default:"24h"` + Type string `yaml:"type" mapstructure:"type" default:"local"` + Path string `yaml:"path" mapstructure:"path" default:"./data/keys"` + Encryption string `yaml:"encryption" mapstructure:"encryption" default:"AES-256-GCM"` + EncryptionPassphrase string `yaml:"encryption_passphrase" mapstructure:"encryption_passphrase"` + BackupEnabled bool `yaml:"backup_enabled" mapstructure:"backup_enabled" default:"true"` + BackupInterval string `yaml:"backup_interval" mapstructure:"backup_interval" default:"24h"` } // APIConfig holds configuration for API settings @@ -209,4 +285,53 @@ func applyEnvOverrides(cfg *Config) { cfg.AgentField.NodeHealth.HeartbeatStaleThreshold = d } } + + // Authorization overrides + if val := os.Getenv("AGENTFIELD_AUTHORIZATION_ENABLED"); val != "" { + cfg.Features.DID.Authorization.Enabled = val == "true" || val == "1" + } + if val := os.Getenv("AGENTFIELD_AUTHORIZATION_DID_AUTH_ENABLED"); val != "" { + cfg.Features.DID.Authorization.DIDAuthEnabled = val == "true" || val == "1" + } + if val := os.Getenv("AGENTFIELD_AUTHORIZATION_DOMAIN"); val != "" { + cfg.Features.DID.Authorization.Domain = val + } + if val := os.Getenv("AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN"); val != "" { + cfg.Features.DID.Authorization.AdminToken = val + } + if val := os.Getenv("AGENTFIELD_AUTHORIZATION_INTERNAL_TOKEN"); val != "" { + cfg.Features.DID.Authorization.InternalToken = val + } + + // Connector overrides + if val := os.Getenv("AGENTFIELD_CONNECTOR_ENABLED"); val != "" { + cfg.Features.Connector.Enabled = val == "true" || val == "1" + } + if val := os.Getenv("AGENTFIELD_CONNECTOR_TOKEN"); val != "" { + cfg.Features.Connector.Token = val + } + // Connector capability overrides (true / false / readonly) + connectorCapEnvMap := map[string]string{ + "AGENTFIELD_CONNECTOR_CAP_POLICY_MANAGEMENT": "policy_management", + "AGENTFIELD_CONNECTOR_CAP_TAG_MANAGEMENT": "tag_management", + "AGENTFIELD_CONNECTOR_CAP_DID_MANAGEMENT": "did_management", + "AGENTFIELD_CONNECTOR_CAP_REASONER_MANAGEMENT": "reasoner_management", + "AGENTFIELD_CONNECTOR_CAP_STATUS_READ": "status_read", + "AGENTFIELD_CONNECTOR_CAP_OBSERVABILITY_CONFIG": "observability_config", + } + for envKey, capName := range connectorCapEnvMap { + if val := os.Getenv(envKey); val != "" { + if cfg.Features.Connector.Capabilities == nil { + cfg.Features.Connector.Capabilities = make(map[string]ConnectorCapability) + } + switch strings.ToLower(val) { + case "true": + cfg.Features.Connector.Capabilities[capName] = ConnectorCapability{Enabled: true, ReadOnly: false} + case "readonly": + cfg.Features.Connector.Capabilities[capName] = ConnectorCapability{Enabled: true, ReadOnly: true} + default: + cfg.Features.Connector.Capabilities[capName] = ConnectorCapability{Enabled: false} + } + } + } } diff --git a/control-plane/internal/encryption/encryption.go b/control-plane/internal/encryption/encryption.go index 572f6871..08b5a8c8 100644 --- a/control-plane/internal/encryption/encryption.go +++ b/control-plane/internal/encryption/encryption.go @@ -97,6 +97,60 @@ func (es *EncryptionService) Decrypt(ciphertext string) (string, error) { return string(plaintext), nil } +// EncryptBytes encrypts raw bytes and returns the ciphertext as bytes (nonce prepended). +func (es *EncryptionService) EncryptBytes(plaintext []byte) ([]byte, error) { + if len(plaintext) == 0 { + return nil, nil + } + + block, err := aes.NewCipher(es.key) + if err != nil { + return nil, fmt.Errorf("failed to create AES cipher: %w", err) + } + + gcm, err := cipher.NewGCM(block) + if err != nil { + return nil, fmt.Errorf("failed to create GCM: %w", err) + } + + nonce := make([]byte, gcm.NonceSize()) + if _, err := io.ReadFull(rand.Reader, nonce); err != nil { + return nil, fmt.Errorf("failed to generate nonce: %w", err) + } + + return gcm.Seal(nonce, nonce, plaintext, nil), nil +} + +// DecryptBytes decrypts ciphertext bytes (nonce prepended) and returns the plaintext bytes. +func (es *EncryptionService) DecryptBytes(ciphertext []byte) ([]byte, error) { + if len(ciphertext) == 0 { + return nil, nil + } + + block, err := aes.NewCipher(es.key) + if err != nil { + return nil, fmt.Errorf("failed to create AES cipher: %w", err) + } + + gcm, err := cipher.NewGCM(block) + if err != nil { + return nil, fmt.Errorf("failed to create GCM: %w", err) + } + + nonceSize := gcm.NonceSize() + if len(ciphertext) < nonceSize { + return nil, fmt.Errorf("ciphertext too short") + } + + nonce, encryptedData := ciphertext[:nonceSize], ciphertext[nonceSize:] + plaintext, err := gcm.Open(nil, nonce, encryptedData, nil) + if err != nil { + return nil, fmt.Errorf("failed to decrypt: %w", err) + } + + return plaintext, nil +} + // EncryptConfigurationValues encrypts sensitive values in a configuration map func (es *EncryptionService) EncryptConfigurationValues(config map[string]interface{}, secretFields []string) (map[string]interface{}, error) { result := make(map[string]interface{}) diff --git a/control-plane/internal/handlers/admin/access_policies.go b/control-plane/internal/handlers/admin/access_policies.go new file mode 100644 index 00000000..4ef76929 --- /dev/null +++ b/control-plane/internal/handlers/admin/access_policies.go @@ -0,0 +1,183 @@ +package admin + +import ( + "net/http" + "strconv" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" +) + +// AccessPolicyHandlers handles admin access policy HTTP requests. +type AccessPolicyHandlers struct { + policyService *services.AccessPolicyService +} + +// NewAccessPolicyHandlers creates a new access policy admin handlers instance. +func NewAccessPolicyHandlers(policyService *services.AccessPolicyService) *AccessPolicyHandlers { + return &AccessPolicyHandlers{ + policyService: policyService, + } +} + +// ListPolicies returns all access policies. +// GET /api/v1/admin/policies +func (h *AccessPolicyHandlers) ListPolicies(c *gin.Context) { + policies, err := h.policyService.ListPolicies(c.Request.Context()) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to list access policies") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "list_failed", + "message": "Failed to list access policies", + }) + return + } + + c.JSON(http.StatusOK, types.AccessPolicyListResponse{ + Policies: policies, + Total: len(policies), + }) +} + +// CreatePolicy creates a new access policy. +// POST /api/v1/admin/policies +func (h *AccessPolicyHandlers) CreatePolicy(c *gin.Context) { + var req types.AccessPolicyRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_request", + "message": "Invalid JSON: " + err.Error(), + }) + return + } + + if req.Action != "allow" && req.Action != "deny" { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_action", + "message": "Action must be 'allow' or 'deny'", + }) + return + } + + policy, err := h.policyService.AddPolicy(c.Request.Context(), &req) + if err != nil { + logger.Logger.Error().Err(err).Str("name", req.Name).Msg("Failed to create access policy") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "create_failed", + "message": "Failed to create access policy: " + err.Error(), + }) + return + } + + c.JSON(http.StatusCreated, policy) +} + +// GetPolicy returns a single access policy by ID. +// GET /api/v1/admin/policies/:id +func (h *AccessPolicyHandlers) GetPolicy(c *gin.Context) { + id, err := strconv.ParseInt(c.Param("id"), 10, 64) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_id", + "message": "Policy ID must be a number", + }) + return + } + + policy, err := h.policyService.GetPolicyByID(c.Request.Context(), id) + if err != nil { + c.JSON(http.StatusNotFound, gin.H{ + "error": "not_found", + "message": "Access policy not found", + }) + return + } + + c.JSON(http.StatusOK, policy) +} + +// UpdatePolicy updates an existing access policy. +// PUT /api/v1/admin/policies/:id +func (h *AccessPolicyHandlers) UpdatePolicy(c *gin.Context) { + id, err := strconv.ParseInt(c.Param("id"), 10, 64) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_id", + "message": "Policy ID must be a number", + }) + return + } + + var req types.AccessPolicyRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_request", + "message": "Invalid JSON: " + err.Error(), + }) + return + } + + if req.Action != "allow" && req.Action != "deny" { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_action", + "message": "Action must be 'allow' or 'deny'", + }) + return + } + + policy, err := h.policyService.UpdatePolicy(c.Request.Context(), id, &req) + if err != nil { + logger.Logger.Error().Err(err).Int64("id", id).Msg("Failed to update access policy") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "update_failed", + "message": "Failed to update access policy: " + err.Error(), + }) + return + } + + c.JSON(http.StatusOK, policy) +} + +// DeletePolicy deletes an access policy. +// DELETE /api/v1/admin/policies/:id +func (h *AccessPolicyHandlers) DeletePolicy(c *gin.Context) { + id, err := strconv.ParseInt(c.Param("id"), 10, 64) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_id", + "message": "Policy ID must be a number", + }) + return + } + + if err := h.policyService.RemovePolicy(c.Request.Context(), id); err != nil { + logger.Logger.Error().Err(err).Int64("id", id).Msg("Failed to delete access policy") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "delete_failed", + "message": "Failed to delete access policy: " + err.Error(), + }) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "message": "Access policy deleted", + }) +} + +// RegisterRoutes registers the access policy admin routes. +func (h *AccessPolicyHandlers) RegisterRoutes(router *gin.RouterGroup) { + adminGroup := router.Group("/admin") + { + policiesGroup := adminGroup.Group("/policies") + { + policiesGroup.GET("", h.ListPolicies) + policiesGroup.POST("", h.CreatePolicy) + policiesGroup.GET("/:id", h.GetPolicy) + policiesGroup.PUT("/:id", h.UpdatePolicy) + policiesGroup.DELETE("/:id", h.DeletePolicy) + } + } +} diff --git a/control-plane/internal/handlers/admin/admin_handlers_test.go b/control-plane/internal/handlers/admin/admin_handlers_test.go new file mode 100644 index 00000000..fa9d4f16 --- /dev/null +++ b/control-plane/internal/handlers/admin/admin_handlers_test.go @@ -0,0 +1,560 @@ +package admin + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func init() { + gin.SetMode(gin.TestMode) +} + +// ============================================================================ +// Mock storage for AccessPolicyService +// ============================================================================ + +type mockPolicyStorage struct { + policies []*types.AccessPolicy + nextID int64 + createErr error +} + +func (m *mockPolicyStorage) GetAccessPolicies(_ context.Context) ([]*types.AccessPolicy, error) { + result := make([]*types.AccessPolicy, len(m.policies)) + copy(result, m.policies) + return result, nil +} + +func (m *mockPolicyStorage) GetAccessPolicyByID(_ context.Context, id int64) (*types.AccessPolicy, error) { + for _, p := range m.policies { + if p.ID == id { + return p, nil + } + } + return nil, fmt.Errorf("policy %d not found", id) +} + +func (m *mockPolicyStorage) CreateAccessPolicy(_ context.Context, policy *types.AccessPolicy) error { + if m.createErr != nil { + return m.createErr + } + m.nextID++ + policy.ID = m.nextID + m.policies = append(m.policies, policy) + return nil +} + +func (m *mockPolicyStorage) UpdateAccessPolicy(_ context.Context, policy *types.AccessPolicy) error { + for i, p := range m.policies { + if p.ID == policy.ID { + m.policies[i] = policy + return nil + } + } + return fmt.Errorf("policy %d not found", policy.ID) +} + +func (m *mockPolicyStorage) DeleteAccessPolicy(_ context.Context, id int64) error { + for i, p := range m.policies { + if p.ID == id { + m.policies = append(m.policies[:i], m.policies[i+1:]...) + return nil + } + } + return fmt.Errorf("policy %d not found", id) +} + +// ============================================================================ +// Mock storage for TagApprovalService +// ============================================================================ + +type mockTagStorage struct { + agents map[string]*types.AgentNode + agentDID map[string]*types.AgentDIDInfo +} + +func newMockTagStorage() *mockTagStorage { + return &mockTagStorage{ + agents: make(map[string]*types.AgentNode), + agentDID: make(map[string]*types.AgentDIDInfo), + } +} + +func (m *mockTagStorage) GetAgent(_ context.Context, id string) (*types.AgentNode, error) { + a, ok := m.agents[id] + if !ok { + return nil, fmt.Errorf("agent %s not found", id) + } + return a, nil +} + +func (m *mockTagStorage) RegisterAgent(_ context.Context, node *types.AgentNode) error { + m.agents[node.ID] = node + return nil +} + +func (m *mockTagStorage) ListAgentsByLifecycleStatus(_ context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) { + var result []*types.AgentNode + for _, a := range m.agents { + if a.LifecycleStatus == status { + result = append(result, a) + } + } + return result, nil +} + +func (m *mockTagStorage) GetAgentDID(_ context.Context, agentID string) (*types.AgentDIDInfo, error) { + info, ok := m.agentDID[agentID] + if !ok { + return nil, fmt.Errorf("DID not found") + } + return info, nil +} + +func (m *mockTagStorage) StoreAgentTagVC(_ context.Context, _, _, _, _, _ string, _ time.Time, _ *time.Time) error { + return nil +} + +func (m *mockTagStorage) RevokeAgentTagVC(_ context.Context, _ string) error { + return nil +} + +// ============================================================================ +// Access Policy Handler Tests +// ============================================================================ + +func setupPolicyRouter(storage *mockPolicyStorage) (*gin.Engine, *services.AccessPolicyService) { + svc := services.NewAccessPolicyService(storage) + _ = svc.Initialize(context.Background()) + handlers := NewAccessPolicyHandlers(svc) + + r := gin.New() + api := r.Group("/api/v1") + handlers.RegisterRoutes(api) + return r, svc +} + +func TestAccessPolicyHandlers_ListPolicies_Empty(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/policies", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + var resp types.AccessPolicyListResponse + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp)) + assert.Equal(t, 0, resp.Total) + assert.Empty(t, resp.Policies) +} + +func TestAccessPolicyHandlers_CreatePolicy_Success(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + body := `{"name":"finance_to_billing","caller_tags":["finance"],"target_tags":["billing"],"action":"allow","priority":10}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/policies", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusCreated, w.Code) + + var policy types.AccessPolicy + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &policy)) + assert.Equal(t, "finance_to_billing", policy.Name) + assert.True(t, policy.Enabled) +} + +func TestAccessPolicyHandlers_CreatePolicy_InvalidAction(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + body := `{"name":"bad","caller_tags":["a"],"target_tags":["b"],"action":"maybe"}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/policies", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + assert.Contains(t, w.Body.String(), "invalid_action") +} + +func TestAccessPolicyHandlers_CreatePolicy_InvalidJSON(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/policies", bytes.NewBufferString("{invalid")) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + assert.Contains(t, w.Body.String(), "invalid_request") +} + +func TestAccessPolicyHandlers_GetPolicy_Success(t *testing.T) { + now := time.Now() + storage := &mockPolicyStorage{ + policies: []*types.AccessPolicy{ + {ID: 1, Name: "test", CallerTags: []string{"a"}, TargetTags: []string{"b"}, + Action: "allow", Enabled: true, CreatedAt: now, UpdatedAt: now}, + }, + } + router, _ := setupPolicyRouter(storage) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/policies/1", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + var policy types.AccessPolicy + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &policy)) + assert.Equal(t, "test", policy.Name) +} + +func TestAccessPolicyHandlers_GetPolicy_NotFound(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/policies/999", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusNotFound, w.Code) +} + +func TestAccessPolicyHandlers_GetPolicy_InvalidID(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/policies/abc", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) + assert.Contains(t, w.Body.String(), "invalid_id") +} + +func TestAccessPolicyHandlers_DeletePolicy_Success(t *testing.T) { + now := time.Now() + storage := &mockPolicyStorage{ + policies: []*types.AccessPolicy{ + {ID: 1, Name: "to_delete", CallerTags: []string{"a"}, TargetTags: []string{"b"}, + Action: "allow", Enabled: true, CreatedAt: now, UpdatedAt: now}, + }, + } + router, _ := setupPolicyRouter(storage) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodDelete, "/api/v1/admin/policies/1", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), "success") +} + +func TestAccessPolicyHandlers_DeletePolicy_NotFound(t *testing.T) { + router, _ := setupPolicyRouter(&mockPolicyStorage{}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodDelete, "/api/v1/admin/policies/999", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) + assert.Contains(t, w.Body.String(), "delete_failed") +} + +func TestAccessPolicyHandlers_UpdatePolicy_Success(t *testing.T) { + now := time.Now() + storage := &mockPolicyStorage{ + policies: []*types.AccessPolicy{ + {ID: 1, Name: "original", CallerTags: []string{"a"}, TargetTags: []string{"b"}, + Action: "allow", Priority: 5, Enabled: true, CreatedAt: now, UpdatedAt: now}, + }, + } + router, _ := setupPolicyRouter(storage) + + body := `{"name":"updated","caller_tags":["x"],"target_tags":["y"],"action":"deny","priority":20}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPut, "/api/v1/admin/policies/1", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + var policy types.AccessPolicy + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &policy)) + assert.Equal(t, "updated", policy.Name) + assert.Equal(t, "deny", policy.Action) +} + +// ============================================================================ +// Tag Approval Handler Tests +// ============================================================================ + +func setupTagApprovalRouter(storage *mockTagStorage) *gin.Engine { + cfg := config.TagApprovalRulesConfig{DefaultMode: "manual"} + svc := services.NewTagApprovalService(cfg, storage) + handlers := NewTagApprovalHandlers(svc, nil) + + r := gin.New() + api := r.Group("/api/v1") + handlers.RegisterRoutes(api) + return r +} + +func TestTagApprovalHandlers_ListPendingAgents_Empty(t *testing.T) { + router := setupTagApprovalRouter(newMockTagStorage()) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/agents/pending", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + var resp map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp)) + assert.Equal(t, float64(0), resp["total"]) +} + +func TestTagApprovalHandlers_ListPendingAgents_ReturnsPending(t *testing.T) { + storage := newMockTagStorage() + storage.agents["pending-1"] = &types.AgentNode{ + ID: "pending-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"finance"}, + RegisteredAt: time.Now(), + } + storage.agents["ready-1"] = &types.AgentNode{ + ID: "ready-1", + LifecycleStatus: types.AgentStatusReady, + } + + router := setupTagApprovalRouter(storage) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/agents/pending", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + var resp map[string]any + require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp)) + assert.Equal(t, float64(1), resp["total"]) +} + +func TestTagApprovalHandlers_ApproveAgentTags_Success(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"finance"}, + } + + router := setupTagApprovalRouter(storage) + + body := `{"approved_tags":["finance"]}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/approve-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), "success") + + // Verify the agent was updated + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusStarting, agent.LifecycleStatus) + assert.Equal(t, []string{"finance"}, agent.ApprovedTags) +} + +func TestTagApprovalHandlers_ApproveAgentTags_InvalidJSON(t *testing.T) { + storage := newMockTagStorage() + router := setupTagApprovalRouter(storage) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/approve-tags", bytes.NewBufferString("{bad")) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusBadRequest, w.Code) +} + +func TestTagApprovalHandlers_ApproveAgentTags_NonPendingReturns409(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + } + + router := setupTagApprovalRouter(storage) + + body := `{"approved_tags":["finance"]}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/approve-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusConflict, w.Code) + assert.Contains(t, w.Body.String(), "not_pending_approval") +} + +func TestTagApprovalHandlers_RejectAgentTags_NonPendingReturns409(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + } + + router := setupTagApprovalRouter(storage) + + body := `{"reason":"revoke access"}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/reject-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusConflict, w.Code) + assert.Contains(t, w.Body.String(), "not_pending_approval") +} + +func TestTagApprovalHandlers_ApproveAgentTags_PerSkill(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"payment"}}, + }, + } + + router := setupTagApprovalRouter(storage) + + body := `{"approved_tags":[],"skill_tags":{"s1":["payment"]}}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/approve-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusStarting, agent.LifecycleStatus) + assert.Equal(t, []string{"payment"}, agent.Skills[0].ApprovedTags) +} + +func TestTagApprovalHandlers_RejectAgentTags_Success(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"root"}, + } + + router := setupTagApprovalRouter(storage) + + body := `{"reason":"Forbidden tag"}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/reject-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), "success") + + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusOffline, agent.LifecycleStatus) +} + +func TestTagApprovalHandlers_RejectAgentTags_EmptyBody(t *testing.T) { + // Rejection should work even without a body (reason is optional) + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + } + + router := setupTagApprovalRouter(storage) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/reject-tags", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestTagApprovalHandlers_RejectAgentTags_NotFoundFails(t *testing.T) { + router := setupTagApprovalRouter(newMockTagStorage()) + + body := `{"reason":"test"}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/nonexistent/reject-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) + assert.Contains(t, w.Body.String(), "rejection_failed") +} + +func TestTagApprovalHandlers_RevokeAgentTags_ReadyAgent(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + ApprovedTags: []string{"finance", "billing"}, + } + + router := setupTagApprovalRouter(storage) + + body := `{"reason":"security review"}` + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/revoke-tags", bytes.NewBufferString(body)) + req.Header.Set("Content-Type", "application/json") + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), "success") + + // Verify agent was transitioned to pending_approval with cleared tags + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusPendingApproval, agent.LifecycleStatus) + assert.Nil(t, agent.ApprovedTags) +} + +func TestTagApprovalHandlers_RevokeAgentTags_EmptyBody(t *testing.T) { + storage := newMockTagStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + ApprovedTags: []string{"finance"}, + } + + router := setupTagApprovalRouter(storage) + + // Revocation without reason should work + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/agent-1/revoke-tags", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestTagApprovalHandlers_RevokeAgentTags_NotFoundFails(t *testing.T) { + router := setupTagApprovalRouter(newMockTagStorage()) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/agents/nonexistent/revoke-tags", nil) + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusInternalServerError, w.Code) + assert.Contains(t, w.Body.String(), "revocation_failed") +} diff --git a/control-plane/internal/handlers/admin/tag_approval.go b/control-plane/internal/handlers/admin/tag_approval.go new file mode 100644 index 00000000..0777f7fc --- /dev/null +++ b/control-plane/internal/handlers/admin/tag_approval.go @@ -0,0 +1,298 @@ +package admin + +import ( + "errors" + "net/http" + "sort" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/internal/storage" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" +) + +// TagApprovalHandlers handles admin tag approval HTTP requests. +type TagApprovalHandlers struct { + tagApprovalService *services.TagApprovalService + storage storage.StorageProvider +} + +// NewTagApprovalHandlers creates a new tag approval admin handlers instance. +func NewTagApprovalHandlers(tagApprovalService *services.TagApprovalService, storage storage.StorageProvider) *TagApprovalHandlers { + return &TagApprovalHandlers{ + tagApprovalService: tagApprovalService, + storage: storage, + } +} + +// ListPendingAgents returns all agents in pending_approval status. +// GET /api/v1/admin/agents/pending +func (h *TagApprovalHandlers) ListPendingAgents(c *gin.Context) { + agents, err := h.tagApprovalService.ListPendingAgents(c.Request.Context()) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to list pending agents") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "list_failed", + "message": "Failed to list pending agents", + }) + return + } + + // Convert to response format + responses := make([]types.PendingAgentResponse, 0, len(agents)) + for _, agent := range agents { + responses = append(responses, types.PendingAgentResponse{ + AgentID: agent.ID, + ProposedTags: agent.ProposedTags, + ApprovedTags: agent.ApprovedTags, + Status: string(agent.LifecycleStatus), + RegisteredAt: agent.RegisteredAt.Format("2006-01-02T15:04:05Z"), + }) + } + + c.JSON(http.StatusOK, gin.H{ + "agents": responses, + "total": len(responses), + }) +} + +// ListApprovedAgents returns all agents that have approved tags (not pending). +// GET /api/v1/admin/agents/approved +func (h *TagApprovalHandlers) ListApprovedAgents(c *gin.Context) { + agents, err := h.storage.ListAgents(c.Request.Context(), types.AgentFilters{}) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to list agents for approved tags") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "list_failed", + "message": "Failed to list approved agents", + }) + return + } + + responses := make([]types.PendingAgentResponse, 0) + for _, agent := range agents { + if agent.LifecycleStatus == types.AgentStatusPendingApproval || len(agent.ApprovedTags) == 0 { + continue + } + responses = append(responses, types.PendingAgentResponse{ + AgentID: agent.ID, + ProposedTags: agent.ProposedTags, + ApprovedTags: agent.ApprovedTags, + Status: string(agent.LifecycleStatus), + RegisteredAt: agent.RegisteredAt.Format("2006-01-02T15:04:05Z"), + }) + } + + c.JSON(http.StatusOK, gin.H{ + "agents": responses, + "total": len(responses), + }) +} + +// ApproveAgentTags approves an agent's proposed tags. +// POST /api/v1/admin/agents/:agent_id/approve-tags +func (h *TagApprovalHandlers) ApproveAgentTags(c *gin.Context) { + agentID := c.Param("agent_id") + if agentID == "" { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "missing_agent_id", + "message": "agent_id is required", + }) + return + } + + var req types.TagApprovalRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "invalid_request", + "message": "Invalid JSON: " + err.Error(), + }) + return + } + + // If per-skill/per-reasoner tags are provided, use per-skill approval + if len(req.SkillTags) > 0 || len(req.ReasonerTags) > 0 { + if err := h.tagApprovalService.ApproveAgentTagsPerSkill(c.Request.Context(), agentID, req.SkillTags, req.ReasonerTags, "admin"); err != nil { + if errors.Is(err, services.ErrNotPendingApproval) { + c.JSON(http.StatusConflict, gin.H{ + "error": "not_pending_approval", + "message": err.Error(), + }) + return + } + logger.Logger.Error().Err(err).Str("agent_id", agentID).Msg("Failed to approve agent tags (per-skill)") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "approval_failed", + "message": "Failed to approve agent tags: " + err.Error(), + }) + return + } + } else { + if err := h.tagApprovalService.ApproveAgentTags(c.Request.Context(), agentID, req.ApprovedTags, "admin"); err != nil { + if errors.Is(err, services.ErrNotPendingApproval) { + c.JSON(http.StatusConflict, gin.H{ + "error": "not_pending_approval", + "message": err.Error(), + }) + return + } + logger.Logger.Error().Err(err).Str("agent_id", agentID).Msg("Failed to approve agent tags") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "approval_failed", + "message": "Failed to approve agent tags: " + err.Error(), + }) + return + } + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "message": "Agent tags approved", + "agent_id": agentID, + "approved_tags": req.ApprovedTags, + }) +} + +// RejectAgentTags rejects an agent's proposed tags. +// POST /api/v1/admin/agents/:agent_id/reject-tags +func (h *TagApprovalHandlers) RejectAgentTags(c *gin.Context) { + agentID := c.Param("agent_id") + if agentID == "" { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "missing_agent_id", + "message": "agent_id is required", + }) + return + } + + var req types.TagRejectionRequest + if err := c.ShouldBindJSON(&req); err != nil { + // Allow empty body for rejection (reason is optional) + req = types.TagRejectionRequest{} + } + + if err := h.tagApprovalService.RejectAgentTags(c.Request.Context(), agentID, "admin", req.Reason); err != nil { + if errors.Is(err, services.ErrNotPendingApproval) { + c.JSON(http.StatusConflict, gin.H{ + "error": "not_pending_approval", + "message": err.Error(), + }) + return + } + logger.Logger.Error().Err(err).Str("agent_id", agentID).Msg("Failed to reject agent tags") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "rejection_failed", + "message": "Failed to reject agent tags: " + err.Error(), + }) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "message": "Agent tags rejected", + "agent_id": agentID, + }) +} + +// RevokeAgentTags revokes an agent's approved tags, transitioning it back to pending_approval. +// POST /api/v1/admin/agents/:agent_id/revoke-tags +func (h *TagApprovalHandlers) RevokeAgentTags(c *gin.Context) { + agentID := c.Param("agent_id") + if agentID == "" { + c.JSON(http.StatusBadRequest, gin.H{ + "error": "missing_agent_id", + "message": "agent_id is required", + }) + return + } + + var req struct { + Reason string `json:"reason"` + } + _ = c.ShouldBindJSON(&req) // reason is optional + + if err := h.tagApprovalService.RevokeAgentTags(c.Request.Context(), agentID, "admin", req.Reason); err != nil { + logger.Logger.Error().Err(err).Str("agent_id", agentID).Msg("Failed to revoke agent tags") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "revocation_failed", + "message": "Failed to revoke agent tags: " + err.Error(), + }) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "message": "Agent tags revoked", + "agent_id": agentID, + }) +} + +// ListKnownTags returns all unique tags known to the system from agents and policies. +// GET /api/v1/admin/tags +func (h *TagApprovalHandlers) ListKnownTags(c *gin.Context) { + tagSet := make(map[string]struct{}) + + // Collect tags from all agents + agents, err := h.storage.ListAgents(c.Request.Context(), types.AgentFilters{}) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to list agents for known tags") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "list_failed", + "message": "Failed to collect known tags", + }) + return + } + + for _, agent := range agents { + for _, t := range agent.ProposedTags { + tagSet[t] = struct{}{} + } + for _, t := range agent.ApprovedTags { + tagSet[t] = struct{}{} + } + for _, r := range agent.Reasoners { + for _, t := range r.Tags { + tagSet[t] = struct{}{} + } + for _, t := range r.ProposedTags { + tagSet[t] = struct{}{} + } + } + for _, s := range agent.Skills { + for _, t := range s.Tags { + tagSet[t] = struct{}{} + } + for _, t := range s.ProposedTags { + tagSet[t] = struct{}{} + } + } + } + + tags := make([]string, 0, len(tagSet)) + for t := range tagSet { + tags = append(tags, t) + } + sort.Strings(tags) + + c.JSON(http.StatusOK, gin.H{ + "tags": tags, + "total": len(tags), + }) +} + +// RegisterRoutes registers the tag approval admin routes. +func (h *TagApprovalHandlers) RegisterRoutes(router *gin.RouterGroup) { + adminGroup := router.Group("/admin") + { + agentsGroup := adminGroup.Group("/agents") + { + agentsGroup.GET("/pending", h.ListPendingAgents) + agentsGroup.GET("/approved", h.ListApprovedAgents) + agentsGroup.POST("/:agent_id/approve-tags", h.ApproveAgentTags) + agentsGroup.POST("/:agent_id/reject-tags", h.RejectAgentTags) + agentsGroup.POST("/:agent_id/revoke-tags", h.RevokeAgentTags) + } + adminGroup.GET("/tags", h.ListKnownTags) + } +} diff --git a/control-plane/internal/handlers/connector/handlers.go b/control-plane/internal/handlers/connector/handlers.go new file mode 100644 index 00000000..e1a49bf6 --- /dev/null +++ b/control-plane/internal/handlers/connector/handlers.go @@ -0,0 +1,490 @@ +package connector + +import ( + "fmt" + "net/http" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/Agent-Field/agentfield/control-plane/internal/handlers/admin" + "github.com/Agent-Field/agentfield/control-plane/internal/server/middleware" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/internal/storage" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + + "github.com/gin-gonic/gin" +) + +// Handlers provides connector-specific HTTP handlers for the control plane. +type Handlers struct { + connectorConfig config.ConnectorConfig + storage storage.StorageProvider + statusManager *services.StatusManager + accessPolicyService *services.AccessPolicyService + tagApprovalService *services.TagApprovalService + didService *services.DIDService +} + +// NewHandlers creates connector handlers with injected dependencies. +func NewHandlers( + cfg config.ConnectorConfig, + store storage.StorageProvider, + statusManager *services.StatusManager, + accessPolicyService *services.AccessPolicyService, + tagApprovalService *services.TagApprovalService, + didService *services.DIDService, +) *Handlers { + return &Handlers{ + connectorConfig: cfg, + storage: store, + statusManager: statusManager, + accessPolicyService: accessPolicyService, + tagApprovalService: tagApprovalService, + didService: didService, + } +} + +// RegisterRoutes registers all connector routes on the given router group. +// Each route group is gated by its corresponding capability — the CP is the +// sole authority for what the connector token is allowed to access. +// The /manifest endpoint is always accessible so the connector can learn +// its granted capabilities on startup. +func (h *Handlers) RegisterRoutes(group *gin.RouterGroup) { + caps := h.connectorConfig.Capabilities + + // Manifest endpoint — always accessible (connector needs this to learn capabilities) + group.GET("/manifest", h.GetManifest) + + // Reasoner management routes + reasonerGroup := group.Group("") + reasonerGroup.Use(middleware.ConnectorCapabilityCheck("reasoner_management", caps)) + { + reasonerGroup.GET("/reasoners", h.ListReasoners) + reasonerGroup.GET("/reasoners/:id", h.GetReasoner) + reasonerGroup.PUT("/reasoners/:id/version", h.SetReasonerVersion) + reasonerGroup.POST("/reasoners/:id/restart", h.RestartReasoner) + reasonerGroup.GET("/groups", h.ListAgentGroups) + reasonerGroup.GET("/groups/:group_id/nodes", h.ListGroupNodes) + + // Version-aware routes (Phase 2) + reasonerGroup.GET("/reasoners/:id/versions", h.ListReasonerVersions) + reasonerGroup.GET("/reasoners/:id/versions/:version", h.GetReasonerVersion) + reasonerGroup.PUT("/reasoners/:id/versions/:version/weight", h.SetReasonerTrafficWeight) + reasonerGroup.POST("/reasoners/:id/versions/:version/restart", h.RestartReasonerVersion) + } + + // Policy management routes (proxied admin endpoints) + if h.accessPolicyService != nil { + policyGroup := group.Group("") + policyGroup.Use(middleware.ConnectorCapabilityCheck("policy_management", caps)) + policyHandlers := admin.NewAccessPolicyHandlers(h.accessPolicyService) + policyHandlers.RegisterRoutes(policyGroup) + } + + // Tag management routes (proxied admin endpoints) + if h.tagApprovalService != nil { + tagGroup := group.Group("") + tagGroup.Use(middleware.ConnectorCapabilityCheck("tag_management", caps)) + tagHandlers := admin.NewTagApprovalHandlers(h.tagApprovalService, h.storage) + tagHandlers.RegisterRoutes(tagGroup) + } +} + +// GetManifest returns the server-side capability manifest showing what +// this control plane supports and what the connector is configured to access. +func (h *Handlers) GetManifest(c *gin.Context) { + capabilities := make(map[string]map[string]interface{}) + for name, cap := range h.connectorConfig.Capabilities { + capabilities[name] = map[string]interface{}{ + "enabled": cap.Enabled, + "read_only": cap.ReadOnly, + } + } + + manifest := gin.H{ + "connector_enabled": h.connectorConfig.Enabled, + "capabilities": capabilities, + "features": gin.H{ + "did_enabled": h.didService != nil, + "authorization_enabled": h.accessPolicyService != nil, + }, + } + + c.JSON(http.StatusOK, manifest) +} + +// ListReasoners returns all registered agent nodes with their reasoner info. +func (h *Handlers) ListReasoners(c *gin.Context) { + ctx := c.Request.Context() + agents, err := h.storage.ListAgents(ctx, types.AgentFilters{}) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + type nodeInfo struct { + NodeID string `json:"node_id"` + GroupID string `json:"group_id"` + TeamID string `json:"team_id"` + Version string `json:"version"` + HealthStatus types.HealthStatus `json:"health_status"` + Reasoners []types.ReasonerDefinition `json:"reasoners"` + Skills []types.SkillDefinition `json:"skills"` + } + + var result []nodeInfo + for _, agent := range agents { + result = append(result, nodeInfo{ + NodeID: agent.ID, + GroupID: agent.GroupID, + TeamID: agent.TeamID, + Version: agent.Version, + HealthStatus: agent.HealthStatus, + Reasoners: agent.Reasoners, + Skills: agent.Skills, + }) + } + + c.JSON(http.StatusOK, gin.H{ + "reasoners": result, + "total": len(result), + }) +} + +// GetReasoner returns detailed info for a specific agent node. +func (h *Handlers) GetReasoner(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + + agent, err := h.storage.GetAgent(ctx, id) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent node not found"}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "id": agent.ID, + "group_id": agent.GroupID, + "team_id": agent.TeamID, + "version": agent.Version, + "health_status": agent.HealthStatus, + "lifecycle_status": agent.LifecycleStatus, + "reasoners": agent.Reasoners, + "skills": agent.Skills, + "base_url": agent.BaseURL, + }) +} + +// SetReasonerVersion updates the version for a specific agent node. +func (h *Handlers) SetReasonerVersion(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + + var body struct { + Version string `json:"version" binding:"required"` + } + if err := c.ShouldBindJSON(&body); err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "version is required"}) + return + } + + agent, err := h.storage.GetAgent(ctx, id) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent node not found"}) + return + } + + previousVersion := agent.Version + + if err := h.storage.UpdateAgentVersion(ctx, id, body.Version); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "previous_version": previousVersion, + }) +} + +// RestartReasoner initiates a restart for a specific agent node by transitioning +// its lifecycle status to "starting". +func (h *Handlers) RestartReasoner(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + + agent, err := h.storage.GetAgent(ctx, id) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent node not found"}) + return + } + + if h.statusManager == nil { + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "status manager not available"}) + return + } + + startingState := types.AgentStateStarting + update := &types.AgentStatusUpdate{ + State: &startingState, + Source: types.StatusSourceManual, + Reason: "connector restart request", + } + + if err := h.statusManager.UpdateAgentStatus(ctx, id, update); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "restarted_at": time.Now().UTC().Format(time.RFC3339), + }) +} + +// ListAgentGroups returns distinct agent groups with summary info. +func (h *Handlers) ListAgentGroups(c *gin.Context) { + ctx := c.Request.Context() + teamID := c.Query("team_id") + if teamID == "" { + teamID = "default" + } + + groups, err := h.storage.ListAgentGroups(ctx, teamID) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "groups": groups, + "total": len(groups), + }) +} + +// ListGroupNodes returns all nodes belonging to a specific group. +func (h *Handlers) ListGroupNodes(c *gin.Context) { + ctx := c.Request.Context() + groupID := c.Param("group_id") + + agents, err := h.storage.ListAgentsByGroup(ctx, groupID) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + type nodeInfo struct { + NodeID string `json:"node_id"` + GroupID string `json:"group_id"` + TeamID string `json:"team_id"` + Version string `json:"version"` + HealthStatus types.HealthStatus `json:"health_status"` + LifecycleStatus types.AgentLifecycleStatus `json:"lifecycle_status"` + Reasoners []types.ReasonerDefinition `json:"reasoners"` + Skills []types.SkillDefinition `json:"skills"` + } + + var result []nodeInfo + for _, agent := range agents { + result = append(result, nodeInfo{ + NodeID: agent.ID, + GroupID: agent.GroupID, + TeamID: agent.TeamID, + Version: agent.Version, + HealthStatus: agent.HealthStatus, + LifecycleStatus: agent.LifecycleStatus, + Reasoners: agent.Reasoners, + Skills: agent.Skills, + }) + } + + c.JSON(http.StatusOK, gin.H{ + "nodes": result, + "total": len(result), + }) +} + +// ListReasonerVersions returns all versions of a specific agent. +func (h *Handlers) ListReasonerVersions(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + + versions, err := h.storage.ListAgentVersions(ctx, id) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + // Also check for the default (unversioned) agent + defaultAgent, _ := h.storage.GetAgent(ctx, id) + + type versionInfo struct { + Version string `json:"version"` + TrafficWeight int `json:"traffic_weight"` + HealthStatus types.HealthStatus `json:"health_status"` + LifecycleStatus types.AgentLifecycleStatus `json:"lifecycle_status"` + BaseURL string `json:"base_url"` + LastHeartbeat time.Time `json:"last_heartbeat"` + } + + var result []versionInfo + if defaultAgent != nil { + result = append(result, versionInfo{ + Version: defaultAgent.Version, + TrafficWeight: defaultAgent.TrafficWeight, + HealthStatus: defaultAgent.HealthStatus, + LifecycleStatus: defaultAgent.LifecycleStatus, + BaseURL: defaultAgent.BaseURL, + LastHeartbeat: defaultAgent.LastHeartbeat, + }) + } + for _, v := range versions { + result = append(result, versionInfo{ + Version: v.Version, + TrafficWeight: v.TrafficWeight, + HealthStatus: v.HealthStatus, + LifecycleStatus: v.LifecycleStatus, + BaseURL: v.BaseURL, + LastHeartbeat: v.LastHeartbeat, + }) + } + + if len(result) == 0 { + c.JSON(http.StatusNotFound, gin.H{"error": "agent not found"}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "id": id, + "versions": result, + "total": len(result), + }) +} + +// GetReasonerVersion returns detailed info for a specific (id, version) pair. +func (h *Handlers) GetReasonerVersion(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + version := c.Param("version") + + agent, err := h.storage.GetAgentVersion(ctx, id, version) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent version not found"}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "id": agent.ID, + "version": agent.Version, + "traffic_weight": agent.TrafficWeight, + "health_status": agent.HealthStatus, + "lifecycle_status": agent.LifecycleStatus, + "reasoners": agent.Reasoners, + "skills": agent.Skills, + "base_url": agent.BaseURL, + }) +} + +// SetReasonerTrafficWeight updates the traffic_weight for a specific (id, version) pair. +func (h *Handlers) SetReasonerTrafficWeight(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + version := c.Param("version") + + var body struct { + Weight int `json:"weight"` + } + if err := c.ShouldBindJSON(&body); err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "weight is required"}) + return + } + if body.Weight < 0 || body.Weight > 10000 { + c.JSON(http.StatusBadRequest, gin.H{"error": "weight must be between 0 and 10000"}) + return + } + + // Verify the version exists and get previous weight + agent, err := h.storage.GetAgentVersion(ctx, id, version) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent version not found"}) + return + } + + previousWeight := agent.TrafficWeight + + if err := h.storage.UpdateAgentTrafficWeight(ctx, id, version, body.Weight); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "id": id, + "version": version, + "previous_weight": previousWeight, + "new_weight": body.Weight, + }) +} + +// RestartReasonerVersion initiates a restart for a specific agent version. +func (h *Handlers) RestartReasonerVersion(c *gin.Context) { + ctx := c.Request.Context() + id := c.Param("id") + version := c.Param("version") + + agent, err := h.storage.GetAgentVersion(ctx, id, version) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + if agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "agent version not found"}) + return + } + + if h.statusManager == nil { + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "status manager not available"}) + return + } + + startingState := types.AgentStateStarting + update := &types.AgentStatusUpdate{ + State: &startingState, + Source: types.StatusSourceManual, + Reason: fmt.Sprintf("connector restart request (version: %s)", version), + Version: version, + } + + if err := h.statusManager.UpdateAgentStatus(ctx, id, update); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "id": id, + "version": version, + "restarted_at": time.Now().UTC().Format(time.RFC3339), + }) +} + diff --git a/control-plane/internal/handlers/did_handlers.go b/control-plane/internal/handlers/did_handlers.go index b38a1048..5512f6c0 100644 --- a/control-plane/internal/handlers/did_handlers.go +++ b/control-plane/internal/handlers/did_handlers.go @@ -1,8 +1,10 @@ package handlers import ( + "context" "encoding/json" "net/http" + "strings" "time" "github.com/gin-gonic/gin" @@ -27,12 +29,19 @@ type VCService interface { QueryExecutionVCs(filters *types.VCFilters) ([]types.ExecutionVC, error) ListWorkflowVCs() ([]*types.WorkflowVC, error) GetExecutionVCByExecutionID(executionID string) (*types.ExecutionVC, error) + ListAgentTagVCs() ([]*types.AgentTagVCRecord, error) +} + +// DIDWebResolverService defines did:web resolution operations. +type DIDWebResolverService interface { + ResolveDID(ctx context.Context, did string) (*types.DIDResolutionResult, error) } // DIDHandlers handles DID-related HTTP requests. type DIDHandlers struct { - didService DIDService - vcService VCService + didService DIDService + vcService VCService + didWebService DIDWebResolverService } // NewDIDHandlers creates a new DID handlers instance. @@ -43,6 +52,11 @@ func NewDIDHandlers(didService DIDService, vcService VCService) *DIDHandlers { } } +// SetDIDWebService sets the did:web resolver for hybrid DID resolution. +func (h *DIDHandlers) SetDIDWebService(svc DIDWebResolverService) { + h.didWebService = svc +} + // RegisterAgent handles agent DID registration requests. // POST /api/v1/did/register func (h *DIDHandlers) RegisterAgent(c *gin.Context) { @@ -77,6 +91,24 @@ func (h *DIDHandlers) ResolveDID(c *gin.Context) { return } + // Try did:web resolution first (database-stored documents) + if h.didWebService != nil && strings.HasPrefix(did, "did:web:") { + result, err := h.didWebService.ResolveDID(c.Request.Context(), did) + if err == nil && result.DIDDocument != nil { + c.JSON(http.StatusOK, gin.H{ + "did": result.DIDDocument.ID, + "did_document": result.DIDDocument, + "component_type": "agent_node", + }) + return + } + if err == nil && result.DIDResolutionMetadata.Error == "deactivated" { + c.JSON(http.StatusGone, gin.H{"error": "DID has been revoked"}) + return + } + } + + // Fall back to did:key resolution (in-memory registry) identity, err := h.didService.ResolveDID(did) if err != nil { c.JSON(http.StatusNotFound, gin.H{"error": "DID not found"}) @@ -364,11 +396,19 @@ func (h *DIDHandlers) ExportVCs(c *gin.Context) { }) } + // Query agent tag VCs + agentTagVCs, err := h.vcService.ListAgentTagVCs() + if err != nil { + logger.Logger.Debug().Err(err).Msg("Failed to list agent tag VCs") + agentTagVCs = []*types.AgentTagVCRecord{} + } + c.JSON(http.StatusOK, gin.H{ - "agent_dids": agentDIDs, - "execution_vcs": executionVCsExport, - "workflow_vcs": workflowVCs, - "total_count": len(executionVCs) + len(workflowVCs), + "agent_dids": agentDIDs, + "execution_vcs": executionVCsExport, + "workflow_vcs": workflowVCs, + "agent_tag_vcs": agentTagVCs, + "total_count": len(executionVCs) + len(workflowVCs) + len(agentTagVCs), "filters_applied": filters, }) } diff --git a/control-plane/internal/handlers/did_handlers_test.go b/control-plane/internal/handlers/did_handlers_test.go index ef11a3fa..74438afb 100644 --- a/control-plane/internal/handlers/did_handlers_test.go +++ b/control-plane/internal/handlers/did_handlers_test.go @@ -1,6 +1,7 @@ package handlers import ( + "context" "encoding/json" "fmt" "net/http" @@ -128,6 +129,10 @@ func (f *fakeVCService) ListWorkflowVCs() ([]*types.WorkflowVC, error) { return []*types.WorkflowVC{}, nil } +func (f *fakeVCService) ListAgentTagVCs() ([]*types.AgentTagVCRecord, error) { + return []*types.AgentTagVCRecord{}, nil +} + func TestRegisterAgentHandler_Success(t *testing.T) { gin.SetMode(gin.TestMode) @@ -191,6 +196,80 @@ func TestResolveDIDHandler(t *testing.T) { require.Equal(t, "did:example:123", payload["did"]) } +type fakeDIDWebService struct { + resolveFn func(ctx context.Context, did string) (*types.DIDResolutionResult, error) +} + +func (f *fakeDIDWebService) ResolveDID(ctx context.Context, did string) (*types.DIDResolutionResult, error) { + if f.resolveFn != nil { + return f.resolveFn(ctx, did) + } + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{Error: "notFound"}, + }, nil +} + +func TestResolveDIDHandler_DIDWeb(t *testing.T) { + gin.SetMode(gin.TestMode) + + handler := NewDIDHandlers(&fakeDIDService{}, &fakeVCService{}) + handler.SetDIDWebService(&fakeDIDWebService{ + resolveFn: func(ctx context.Context, did string) (*types.DIDResolutionResult, error) { + return &types.DIDResolutionResult{ + DIDDocument: &types.DIDWebDocument{ + Context: []string{"https://www.w3.org/ns/did/v1"}, + ID: did, + VerificationMethod: []types.VerificationMethod{{ + ID: did + "#key-1", + Type: "Ed25519VerificationKey2020", + Controller: did, + PublicKeyJwk: json.RawMessage(`{"kty":"OKP","crv":"Ed25519","x":"abc"}`), + }}, + Authentication: []string{did + "#key-1"}, + }, + DIDResolutionMetadata: types.DIDResolutionMetadata{ContentType: "application/did+ld+json"}, + }, nil + }, + }) + + router := gin.New() + router.GET("/api/v1/did/resolve/:did", handler.ResolveDID) + + req := httptest.NewRequest(http.MethodGet, "/api/v1/did/resolve/did:web:localhost%3A8080:agents:test-agent", nil) + resp := httptest.NewRecorder() + router.ServeHTTP(resp, req) + + require.Equal(t, http.StatusOK, resp.Code) + + var payload map[string]any + require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &payload)) + require.Contains(t, payload["did"], "did:web:") + require.NotNil(t, payload["did_document"]) +} + +func TestResolveDIDHandler_DIDWebRevoked(t *testing.T) { + gin.SetMode(gin.TestMode) + + handler := NewDIDHandlers(&fakeDIDService{}, &fakeVCService{}) + handler.SetDIDWebService(&fakeDIDWebService{ + resolveFn: func(ctx context.Context, did string) (*types.DIDResolutionResult, error) { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{Error: "deactivated"}, + DIDDocumentMetadata: types.DIDDocumentMetadata{Deactivated: true}, + }, nil + }, + }) + + router := gin.New() + router.GET("/api/v1/did/resolve/:did", handler.ResolveDID) + + req := httptest.NewRequest(http.MethodGet, "/api/v1/did/resolve/did:web:localhost%3A8080:agents:revoked-agent", nil) + resp := httptest.NewRecorder() + router.ServeHTTP(resp, req) + + require.Equal(t, http.StatusGone, resp.Code) +} + func TestGetWorkflowVCChainHandler(t *testing.T) { gin.SetMode(gin.TestMode) @@ -265,6 +344,8 @@ func TestExportVCsHandler(t *testing.T) { var payload map[string]any require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &payload)) require.Equal(t, float64(2), payload["total_count"]) + // D11 fix: Verify agent_tag_vcs field is present in export + require.Contains(t, payload, "agent_tag_vcs", "export should include agent_tag_vcs field") } func TestGetDIDStatusHandler(t *testing.T) { diff --git a/control-plane/internal/handlers/discovery.go b/control-plane/internal/handlers/discovery.go index beefc33d..8b153da2 100644 --- a/control-plane/internal/handlers/discovery.go +++ b/control-plane/internal/handlers/discovery.go @@ -74,6 +74,7 @@ type DiscoveryResponse struct { // AgentCapability describes a single agent and its reasoners/skills. type AgentCapability struct { AgentID string `json:"agent_id"` + GroupID string `json:"group_id"` BaseURL string `json:"base_url"` Version string `json:"version"` HealthStatus string `json:"health_status"` @@ -487,6 +488,7 @@ func buildDiscoveryResponse(agents []*types.AgentNode, filters DiscoveryFilters) capability := AgentCapability{ AgentID: agent.ID, + GroupID: agent.GroupID, BaseURL: agent.BaseURL, Version: agent.Version, HealthStatus: string(agent.HealthStatus), diff --git a/control-plane/internal/handlers/execute.go b/control-plane/internal/handlers/execute.go index 0d9606f8..1c47c3ba 100644 --- a/control-plane/internal/handlers/execute.go +++ b/control-plane/internal/handlers/execute.go @@ -14,10 +14,12 @@ import ( "strconv" "strings" "sync" + "sync/atomic" "time" "github.com/Agent-Field/agentfield/control-plane/internal/events" "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/internal/server/middleware" "github.com/Agent-Field/agentfield/control-plane/internal/services" "github.com/Agent-Field/agentfield/control-plane/internal/utils" "github.com/Agent-Field/agentfield/control-plane/pkg/types" @@ -28,6 +30,7 @@ import ( // ExecutionStore captures the storage operations required by the simplified execution handlers. type ExecutionStore interface { GetAgent(ctx context.Context, id string) (*types.AgentNode, error) + ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) CreateExecutionRecord(ctx context.Context, execution *types.Execution) error GetExecutionRecord(ctx context.Context, executionID string) (*types.Execution, error) UpdateExecutionRecord(ctx context.Context, executionID string, update func(*types.Execution) (*types.Execution, error)) (*types.Execution, error) @@ -60,6 +63,7 @@ type ExecuteResponse struct { Status string `json:"status"` Result interface{} `json:"result,omitempty"` ErrorMessage *string `json:"error_message,omitempty"` + ErrorDetails interface{} `json:"error_details,omitempty"` DurationMS int64 `json:"duration_ms"` FinishedAt string `json:"finished_at"` WebhookRegistered bool `json:"webhook_registered,omitempty"` @@ -86,6 +90,7 @@ type ExecutionStatusResponse struct { Status string `json:"status"` Result interface{} `json:"result,omitempty"` Error *string `json:"error,omitempty"` + ErrorDetails interface{} `json:"error_details,omitempty"` StartedAt string `json:"started_at"` CompletedAt *string `json:"completed_at,omitempty"` DurationMS *int64 `json:"duration_ms,omitempty"` @@ -111,12 +116,13 @@ type executionStatusUpdateRequest struct { } type executionController struct { - store ExecutionStore - httpClient *http.Client - payloads services.PayloadStore - webhooks services.WebhookDispatcher - eventBus *events.ExecutionEventBus - timeout time.Duration + store ExecutionStore + httpClient *http.Client + payloads services.PayloadStore + webhooks services.WebhookDispatcher + eventBus *events.ExecutionEventBus + timeout time.Duration + internalToken string // sent as Authorization header when forwarding to agents } type asyncExecutionJob struct { @@ -152,36 +158,36 @@ const ( ) // ExecuteHandler handles synchronous execution requests. -func ExecuteHandler(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration) gin.HandlerFunc { - controller := newExecutionController(store, payloads, webhooks, timeout) +func ExecuteHandler(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration, internalToken string) gin.HandlerFunc { + controller := newExecutionController(store, payloads, webhooks, timeout, internalToken) return controller.handleSync } // ExecuteAsyncHandler handles asynchronous execution requests. -func ExecuteAsyncHandler(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration) gin.HandlerFunc { - controller := newExecutionController(store, payloads, webhooks, timeout) +func ExecuteAsyncHandler(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration, internalToken string) gin.HandlerFunc { + controller := newExecutionController(store, payloads, webhooks, timeout, internalToken) return controller.handleAsync } // GetExecutionStatusHandler resolves a single execution record. func GetExecutionStatusHandler(store ExecutionStore) gin.HandlerFunc { - controller := newExecutionController(store, nil, nil, 0) + controller := newExecutionController(store, nil, nil, 0, "") return controller.handleStatus } // BatchExecutionStatusHandler resolves multiple execution records. func BatchExecutionStatusHandler(store ExecutionStore) gin.HandlerFunc { - controller := newExecutionController(store, nil, nil, 0) + controller := newExecutionController(store, nil, nil, 0, "") return controller.handleBatchStatus } // UpdateExecutionStatusHandler ingests status callbacks from agent nodes. func UpdateExecutionStatusHandler(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration) gin.HandlerFunc { - controller := newExecutionController(store, payloads, webhooks, timeout) + controller := newExecutionController(store, payloads, webhooks, timeout, "") return controller.handleStatusUpdate } -func newExecutionController(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration) *executionController { +func newExecutionController(store ExecutionStore, payloads services.PayloadStore, webhooks services.WebhookDispatcher, timeout time.Duration, internalToken string) *executionController { // Use default timeout if not provided (0 or negative) if timeout <= 0 { timeout = 90 * time.Second @@ -191,10 +197,11 @@ func newExecutionController(store ExecutionStore, payloads services.PayloadStore httpClient: &http.Client{ Timeout: timeout, }, - payloads: payloads, - webhooks: webhooks, - eventBus: store.GetExecutionEventBus(), - timeout: timeout, + payloads: payloads, + webhooks: webhooks, + eventBus: store.GetExecutionEventBus(), + timeout: timeout, + internalToken: internalToken, } } @@ -260,13 +267,14 @@ func (c *executionController) handleSync(ctx *gin.Context) { RunID: exec.RunID, Status: string(exec.Status), ErrorMessage: &errMsg, + ErrorDetails: decodeJSON(exec.ResultPayload), DurationMS: durationMS, FinishedAt: finishedAt, WebhookRegistered: exec.WebhookRegistered, } ctx.Header("X-Execution-ID", exec.ExecutionID) ctx.Header("X-Run-ID", exec.RunID) - ctx.JSON(http.StatusOK, response) + ctx.JSON(http.StatusBadGateway, response) return } @@ -282,6 +290,9 @@ func (c *executionController) handleSync(ctx *gin.Context) { } ctx.Header("X-Execution-ID", exec.ExecutionID) ctx.Header("X-Run-ID", exec.RunID) + if plan.routedVersion != "" { + ctx.Header("X-Routed-Version", plan.routedVersion) + } ctx.JSON(http.StatusOK, response) return } @@ -322,6 +333,9 @@ func (c *executionController) handleSync(ctx *gin.Context) { ctx.Header("X-Execution-ID", plan.exec.ExecutionID) ctx.Header("X-Run-ID", plan.exec.RunID) + if plan.routedVersion != "" { + ctx.Header("X-Routed-Version", plan.routedVersion) + } ctx.JSON(http.StatusOK, response) } @@ -718,6 +732,18 @@ func (c *executionController) waitForExecutionCompletion(ctx context.Context, ex Dur("timeout", timeout). Msg("waiting for execution completion via event bus") + // Check if execution already completed before we subscribed (race condition: + // fast agents may POST the callback before we subscribe to the event bus). + if existing, err := c.store.GetExecutionRecord(ctx, executionID); err == nil && existing != nil { + if types.IsTerminalExecutionStatus(existing.Status) { + logger.Logger.Debug(). + Str("execution_id", executionID). + Str("status", existing.Status). + Msg("execution already completed before event subscription") + return existing, nil + } + } + for { select { case <-ctx.Done(): @@ -768,6 +794,11 @@ type preparedExecution struct { targetType string webhookRegistered bool webhookError *string + // DID context forwarded to the target agent. + callerDID string + targetDID string + // Version that was selected during routing (empty if default/unversioned agent) + routedVersion string } func (c *executionController) prepareExecution(ctx context.Context, ginCtx *gin.Context) (*preparedExecution, error) { @@ -781,8 +812,9 @@ func (c *executionController) prepareExecution(ctx context.Context, ginCtx *gin. if err := ginCtx.ShouldBindJSON(&req); err != nil { return nil, fmt.Errorf("invalid request body: %w", err) } - if len(req.Input) == 0 { - return nil, errors.New("input is required") + // Allow empty input for skills/reasoners that take no parameters (e.g., ping, get_schema). + if req.Input == nil { + req.Input = map[string]interface{}{} } var ( @@ -800,13 +832,26 @@ func (c *executionController) prepareExecution(ctx context.Context, ginCtx *gin. } } - agent, err := c.store.GetAgent(ctx, target.NodeID) + // Version-aware agent resolution: + // 1. Try GetAgent (default unversioned agent, version='') + // 2. If not found, fall back to ListAgentVersions and select via weighted round-robin + var agent *types.AgentNode + var routedVersion string + + agent, err = c.store.GetAgent(ctx, target.NodeID) if err != nil { - return nil, fmt.Errorf("failed to load agent '%s': %w", target.NodeID, err) - } - if agent == nil { - return nil, fmt.Errorf("agent '%s' not found", target.NodeID) + // GetAgent returns error for "not found" — check if versioned agents exist + versions, listErr := c.store.ListAgentVersions(ctx, target.NodeID) + if listErr != nil || len(versions) == 0 { + return nil, fmt.Errorf("agent '%s' not found", target.NodeID) + } + // Filter to healthy nodes + agent, routedVersion = selectVersionedAgent(versions) + if agent == nil { + return nil, fmt.Errorf("agent '%s' has no healthy versioned nodes", target.NodeID) + } } + if agent.DeploymentType == "" && agent.Metadata.Custom != nil { if v, ok := agent.Metadata.Custom["serverless"]; ok && fmt.Sprint(v) == "true" { agent.DeploymentType = "serverless" @@ -926,6 +971,9 @@ func (c *executionController) prepareExecution(ctx context.Context, ginCtx *gin. targetType: targetType, webhookRegistered: webhookRegistered, webhookError: webhookError, + callerDID: middleware.GetVerifiedCallerDID(ginCtx), + targetDID: middleware.GetTargetDID(ginCtx), + routedVersion: routedVersion, }, nil } @@ -950,6 +998,15 @@ func (c *executionController) callAgent(ctx context.Context, plan *preparedExecu if plan.exec.ActorID != nil { req.Header.Set("X-Actor-ID", *plan.exec.ActorID) } + if c.internalToken != "" { + req.Header.Set("Authorization", "Bearer "+c.internalToken) + } + if plan.callerDID != "" { + req.Header.Set("X-Caller-DID", plan.callerDID) + } + if plan.targetDID != "" { + req.Header.Set("X-Target-DID", plan.targetDID) + } resp, err := c.httpClient.Do(req) if err != nil { @@ -981,7 +1038,11 @@ func (c *executionController) callAgent(ctx context.Context, plan *preparedExecu } if resp.StatusCode >= http.StatusBadRequest { - return body, time.Since(start), false, fmt.Errorf("agent error (%d): %s", resp.StatusCode, truncateForLog(body)) + return body, time.Since(start), false, &callError{ + statusCode: resp.StatusCode, + message: fmt.Sprintf("agent error (%d): %s", resp.StatusCode, truncateForLog(body)), + body: body, + } } return body, time.Since(start), false, nil @@ -1196,6 +1257,73 @@ func buildAgentURL(agent *types.AgentNode, target *parsedTarget) string { return fmt.Sprintf("%s/reasoners/%s", base, target.TargetName) } +// versionRoundRobinCounter is used for round-robin selection across versioned agents. +var versionRoundRobinCounter uint64 + +// selectVersionedAgent picks a healthy agent from the versioned list using +// weighted round-robin. Returns the selected agent and its version string. +func selectVersionedAgent(versions []*types.AgentNode) (*types.AgentNode, string) { + // Filter to healthy nodes + var healthy []*types.AgentNode + for _, v := range versions { + if v.HealthStatus == types.HealthStatusActive && v.LifecycleStatus == types.AgentStatusReady { + healthy = append(healthy, v) + } + } + if len(healthy) == 0 { + // Fallback: accept any non-offline node + for _, v := range versions { + if v.LifecycleStatus != types.AgentStatusOffline { + healthy = append(healthy, v) + } + } + } + if len(healthy) == 0 { + return nil, "" + } + + // Check if all weights are equal (use simple round-robin) + allEqual := true + firstWeight := healthy[0].TrafficWeight + totalWeight := 0 + for _, v := range healthy { + w := v.TrafficWeight + if w <= 0 { + w = 100 + } + totalWeight += w + if w != firstWeight { + allEqual = false + } + } + + if allEqual || totalWeight == 0 { + // Simple round-robin + n := atomic.AddUint64(&versionRoundRobinCounter, 1) - 1 + idx := n % uint64(len(healthy)) + selected := healthy[idx] + return selected, selected.Version + } + + // Weighted selection + n := atomic.AddUint64(&versionRoundRobinCounter, 1) - 1 + counter := n % uint64(totalWeight) + cumulative := 0 + for _, v := range healthy { + w := v.TrafficWeight + if w <= 0 { + w = 100 + } + cumulative += w + if uint64(cumulative) > counter { + return v, v.Version + } + } + + // Fallback + return healthy[0], healthy[0].Version +} + func buildServerlessPayload(target *parsedTarget, exec *types.Execution, headers executionHeaders, input map[string]interface{}) map[string]interface{} { if target == nil || exec == nil { return map[string]interface{}{ @@ -1325,7 +1453,7 @@ func renderStatus(exec *types.Execution) ExecutionStatusResponse { completedAt = &formatted } - return ExecutionStatusResponse{ + resp := ExecutionStatusResponse{ ExecutionID: exec.ExecutionID, RunID: exec.RunID, Status: exec.Status, @@ -1337,6 +1465,12 @@ func renderStatus(exec *types.Execution) ExecutionStatusResponse { WebhookRegistered: exec.WebhookRegistered, WebhookEvents: exec.WebhookEvents, } + // For failed executions, expose the agent's raw response as error_details + // so callers can access structured error data (e.g., permission_denied fields). + if exec.Status == types.ExecutionStatusFailed && len(exec.ResultPayload) > 0 { + resp.ErrorDetails = decodeJSON(exec.ResultPayload) + } + return resp } func (c *executionController) ensureWorkflowExecutionRecord(ctx context.Context, exec *types.Execution, target *parsedTarget, payload []byte) { @@ -1486,11 +1620,47 @@ func cloneBytes(src []byte) []byte { return dst } +// callError wraps an upstream agent HTTP error, preserving the original status +// code and response body for structured error propagation. +type callError struct { + statusCode int + message string + body []byte +} + +func (e *callError) Error() string { + return e.message +} + func writeExecutionError(ctx *gin.Context, err error) { if err == nil { ctx.JSON(http.StatusInternalServerError, gin.H{"error": "unknown error"}) return } + + var ce *callError + if errors.As(err, &ce) { + response := gin.H{ + "error": ce.message, + "status": "failed", + } + // Preserve structured error data from the agent's response body. + if len(ce.body) > 0 { + var parsed interface{} + if json.Unmarshal(ce.body, &parsed) == nil { + response["error_details"] = parsed + } + } + // Propagate 4xx status codes from the agent (client-facing errors); + // use 502 Bad Gateway for 5xx (upstream server failure). + httpStatus := http.StatusBadGateway + if ce.statusCode >= 400 && ce.statusCode < 500 { + httpStatus = ce.statusCode + } + ctx.JSON(httpStatus, response) + return + } + ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) } diff --git a/control-plane/internal/handlers/execute_async_test.go b/control-plane/internal/handlers/execute_async_test.go index d4ebabee..0bce7b7b 100644 --- a/control-plane/internal/handlers/execute_async_test.go +++ b/control-plane/internal/handlers/execute_async_test.go @@ -58,7 +58,7 @@ func TestExecuteAsyncHandler_QueueSaturation(t *testing.T) { // We submit more than capacity to ensure queue stays full for i := 0; i < queueCapacity*2; i++ { job := asyncExecutionJob{ - controller: newExecutionController(store, payloads, nil, 90*time.Second), + controller: newExecutionController(store, payloads, nil, 90*time.Second, ""), plan: preparedExecution{ exec: &types.Execution{ ExecutionID: "test-exec-fill", @@ -76,7 +76,7 @@ func TestExecuteAsyncHandler_QueueSaturation(t *testing.T) { time.Sleep(10 * time.Millisecond) router := gin.New() - router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/async/node-1.reasoner-a", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -131,7 +131,7 @@ func TestExecuteAsyncHandler_WithWebhook(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second, "")) reqBody := `{ "input": {"foo": "bar"}, @@ -180,7 +180,7 @@ func TestExecuteAsyncHandler_InvalidWebhook(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second, "")) // Webhook with invalid URL (too long) longURL := strings.Repeat("a", 4097) @@ -226,7 +226,7 @@ func TestHandleSync_AsyncAcknowledgment(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/node-1.reasoner-a", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -307,7 +307,7 @@ func TestCallAgent_HTTP202Response(t *testing.T) { } store := newTestExecutionStorage(agent) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") plan := &preparedExecution{ exec: &types.Execution{ @@ -346,7 +346,7 @@ func TestCallAgent_ErrorResponse(t *testing.T) { } store := newTestExecutionStorage(agent) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") plan := &preparedExecution{ exec: &types.Execution{ @@ -387,7 +387,7 @@ func TestCallAgent_Timeout(t *testing.T) { } store := newTestExecutionStorage(agent) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") // Set shorter timeout for test controller.httpClient.Timeout = 100 * time.Millisecond @@ -439,7 +439,7 @@ func TestCallAgent_ReadResponseError(t *testing.T) { } store := newTestExecutionStorage(agent) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") plan := &preparedExecution{ exec: &types.Execution{ @@ -481,7 +481,7 @@ func TestCallAgent_HeaderPropagation(t *testing.T) { } store := newTestExecutionStorage(agent) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") parentID := "parent-exec-123" sessionID := "session-456" diff --git a/control-plane/internal/handlers/execute_handler_test.go b/control-plane/internal/handlers/execute_handler_test.go index 9e6cb29c..e824292a 100644 --- a/control-plane/internal/handlers/execute_handler_test.go +++ b/control-plane/internal/handlers/execute_handler_test.go @@ -48,7 +48,7 @@ func TestExecuteHandler_Success(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/node-1.reasoner-a", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -100,7 +100,7 @@ func TestExecuteHandler_AgentError(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/node-1.reasoner-a", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -108,11 +108,15 @@ func TestExecuteHandler_AgentError(t *testing.T) { router.ServeHTTP(resp, req) - require.Equal(t, http.StatusBadRequest, resp.Code) + // Agent returned 500 → control plane returns 502 Bad Gateway with structured error details. + require.Equal(t, http.StatusBadGateway, resp.Code) - var payload map[string]string + var payload map[string]interface{} require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &payload)) require.Contains(t, payload["error"], "agent error (500)") + require.Equal(t, "failed", payload["status"]) + // The agent's JSON response body is preserved as error_details. + require.NotNil(t, payload["error_details"]) records, err := store.QueryExecutionRecords(context.Background(), types.ExecutionFilter{}) require.NoError(t, err) @@ -135,7 +139,7 @@ func TestExecuteHandler_TargetNotFound(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/:target", ExecuteHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/node-1.unknown", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -175,7 +179,7 @@ func TestExecuteAsyncHandler_ReturnsAccepted(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/async/node-1.reasoner-a", strings.NewReader(`{"input":{"foo":"bar"}}`)) req.Header.Set("Content-Type", "application/json") @@ -211,7 +215,7 @@ func TestExecuteAsyncHandler_InvalidJSON(t *testing.T) { payloads := services.NewFilePayloadStore(t.TempDir()) router := gin.New() - router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second)) + router.POST("/api/v1/execute/async/:target", ExecuteAsyncHandler(store, payloads, nil, 90*time.Second, "")) req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/async/node-1.reasoner-a", strings.NewReader("not-json")) req.Header.Set("Content-Type", "application/json") diff --git a/control-plane/internal/handlers/execute_status_update_test.go b/control-plane/internal/handlers/execute_status_update_test.go index 1855b7f7..af164795 100644 --- a/control-plane/internal/handlers/execute_status_update_test.go +++ b/control-plane/internal/handlers/execute_status_update_test.go @@ -307,7 +307,7 @@ func TestUpdateExecutionStatusHandler_ProgressUpdate(t *testing.T) { func TestWaitForExecutionCompletion_Success(t *testing.T) { store := newTestExecutionStorage(nil) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") execution := &types.Execution{ ExecutionID: "exec-1", @@ -375,7 +375,7 @@ func TestWaitForExecutionCompletion_Success(t *testing.T) { func TestWaitForExecutionCompletion_Timeout(t *testing.T) { store := newTestExecutionStorage(nil) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") execution := &types.Execution{ ExecutionID: "exec-1", @@ -399,7 +399,7 @@ func TestWaitForExecutionCompletion_Timeout(t *testing.T) { func TestWaitForExecutionCompletion_ContextCancellation(t *testing.T) { store := newTestExecutionStorage(nil) - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") execution := &types.Execution{ ExecutionID: "exec-1", @@ -439,7 +439,7 @@ func TestWaitForExecutionCompletion_ContextCancellation(t *testing.T) { func TestWaitForExecutionCompletion_NoEventBus(t *testing.T) { // Create storage without event bus store := &testExecutionStorageWithoutEventBus{} - controller := newExecutionController(store, nil, nil, 90*time.Second) + controller := newExecutionController(store, nil, nil, 90*time.Second, "") ctx := context.Background() result, err := controller.waitForExecutionCompletion(ctx, "exec-1", 1*time.Second) diff --git a/control-plane/internal/handlers/execute_test.go b/control-plane/internal/handlers/execute_test.go index c2219b60..7aa108e8 100644 --- a/control-plane/internal/handlers/execute_test.go +++ b/control-plane/internal/handlers/execute_test.go @@ -149,6 +149,12 @@ func (m *MockStorageProvider) GetLockStatus(ctx context.Context, key string) (*t func (m *MockStorageProvider) RegisterAgent(ctx context.Context, agent *types.AgentNode) error { return nil } +func (m *MockStorageProvider) GetAgentVersion(ctx context.Context, id string, version string) (*types.AgentNode, error) { + return nil, nil +} +func (m *MockStorageProvider) ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) { + return nil, nil +} func (m *MockStorageProvider) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) { return nil, nil } @@ -158,7 +164,7 @@ func (m *MockStorageProvider) UpdateAgentHealth(ctx context.Context, id string, func (m *MockStorageProvider) UpdateAgentHealthAtomic(ctx context.Context, id string, status types.HealthStatus, expectedLastHeartbeat *time.Time) error { return nil } -func (m *MockStorageProvider) UpdateAgentHeartbeat(ctx context.Context, id string, heartbeatTime time.Time) error { +func (m *MockStorageProvider) UpdateAgentHeartbeat(ctx context.Context, id string, version string, heartbeatTime time.Time) error { return nil } func (m *MockStorageProvider) UpdateAgentLifecycleStatus(ctx context.Context, id string, status types.AgentLifecycleStatus) error { diff --git a/control-plane/internal/handlers/nodes.go b/control-plane/internal/handlers/nodes.go index 06a80c2e..5090b8ee 100644 --- a/control-plane/internal/handlers/nodes.go +++ b/control-plane/internal/handlers/nodes.go @@ -343,28 +343,39 @@ func (hc *HeartbeatCache) shouldUpdateDatabase(nodeID string, now time.Time, sta } // processHeartbeatAsync processes heartbeat database updates asynchronously -func processHeartbeatAsync(storageProvider storage.StorageProvider, uiService *services.UIService, nodeID string, cached *CachedNodeData) { +func processHeartbeatAsync(storageProvider storage.StorageProvider, uiService *services.UIService, nodeID string, version string, cached *CachedNodeData) { go func() { ctx := context.Background() - // Verify node exists only when we need to update DB - if _, err := storageProvider.GetAgent(ctx, nodeID); err != nil { - logger.Logger.Error().Err(err).Msgf("❌ Node %s not found during heartbeat update", nodeID) - return + // Verify node exists using the resolved version + if version != "" { + if _, err := storageProvider.GetAgentVersion(ctx, nodeID, version); err != nil { + logger.Logger.Error().Err(err).Msgf("❌ Node %s version '%s' not found during heartbeat update", nodeID, version) + return + } + } else { + if _, err := storageProvider.GetAgent(ctx, nodeID); err != nil { + // If not found as default, try finding any version + versions, listErr := storageProvider.ListAgentVersions(ctx, nodeID) + if listErr != nil || len(versions) == 0 { + logger.Logger.Error().Err(err).Msgf("❌ Node %s not found during heartbeat update", nodeID) + return + } + } } // Update heartbeat in database - if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, cached.LastDBUpdate); err != nil { - logger.Logger.Error().Err(err).Msgf("❌ HEARTBEAT_CONTENTION: Failed to update heartbeat for node %s - %v", nodeID, err) + if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, version, cached.LastDBUpdate); err != nil { + logger.Logger.Error().Err(err).Msgf("❌ HEARTBEAT_CONTENTION: Failed to update heartbeat for node %s version '%s' - %v", nodeID, version, err) return } - logger.Logger.Debug().Msgf("💓 HEARTBEAT_CONTENTION: Async DB update completed for node %s", nodeID) + logger.Logger.Debug().Msgf("💓 HEARTBEAT_CONTENTION: Async DB update completed for node %s version '%s'", nodeID, version) }() } // RegisterNodeHandler handles the registration of a new agent node. -func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *services.UIService, didService *services.DIDService, presenceManager *services.PresenceManager) gin.HandlerFunc { +func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *services.UIService, didService *services.DIDService, presenceManager *services.PresenceManager, didWebService *services.DIDWebService, tagApprovalService *services.TagApprovalService) gin.HandlerFunc { return func(c *gin.Context) { ctx := c.Request.Context() var newNode types.AgentNode @@ -393,6 +404,30 @@ func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *ser logger.Logger.Debug().Msgf("✅ Node validation passed for ID: %s", newNode.ID) + // Default group_id to agent id for backward compatibility + if newNode.GroupID == "" { + newNode.GroupID = newNode.ID + } + + // Normalize proposed_tags → tags for backward compatibility. + // If a skill/reasoner has proposed_tags but no tags, copy proposed_tags to tags. + for i := range newNode.Reasoners { + if len(newNode.Reasoners[i].ProposedTags) > 0 && len(newNode.Reasoners[i].Tags) == 0 { + newNode.Reasoners[i].Tags = newNode.Reasoners[i].ProposedTags + } + if len(newNode.Reasoners[i].Tags) > 0 && len(newNode.Reasoners[i].ProposedTags) == 0 { + newNode.Reasoners[i].ProposedTags = newNode.Reasoners[i].Tags + } + } + for i := range newNode.Skills { + if len(newNode.Skills[i].ProposedTags) > 0 && len(newNode.Skills[i].Tags) == 0 { + newNode.Skills[i].Tags = newNode.Skills[i].ProposedTags + } + if len(newNode.Skills[i].Tags) > 0 && len(newNode.Skills[i].ProposedTags) == 0 { + newNode.Skills[i].ProposedTags = newNode.Skills[i].Tags + } + } + candidateList, defaultPort := gatherCallbackCandidates(newNode.BaseURL, newNode.CallbackDiscovery, c.ClientIP()) resolvedBaseURL := "" var normalizedCandidates []string @@ -471,25 +506,86 @@ func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *ser newNode.CallbackDiscovery.SubmittedAt = time.Now().UTC().Format(time.RFC3339) - // Check if node with the same ID already exists - existingNode, err := storageProvider.GetAgent(ctx, newNode.ID) - isReRegistration := false - if err == nil && existingNode != nil { - isReRegistration = true + // Check if node with the same ID and version already exists + var existingNode *types.AgentNode + if newNode.Version != "" { + existingNode, _ = storageProvider.GetAgentVersion(ctx, newNode.ID, newNode.Version) + + // Clean up stale empty-version row if the agent is now registering with a proper version. + // This handles upgrades from older SDKs that didn't send version during registration. + if stale, _ := storageProvider.GetAgentVersion(ctx, newNode.ID, ""); stale != nil { + if err := storageProvider.DeleteAgentVersion(ctx, newNode.ID, ""); err != nil { + logger.Logger.Warn().Err(err).Msgf("⚠️ Failed to clean up stale empty-version row for agent %s", newNode.ID) + } else { + logger.Logger.Info().Msgf("🧹 Cleaned up stale empty-version row for agent %s (now registering as %s)", newNode.ID, newNode.Version) + } + } + } else { + existingNode, _ = storageProvider.GetAgent(ctx, newNode.ID) } + isReRegistration := existingNode != nil // Set initial health status to UNKNOWN for new registrations // The health monitor will determine the actual status based on heartbeats newNode.HealthStatus = types.HealthStatusUnknown - // Handle lifecycle status for re-registrations vs new registrations + // Handle lifecycle status for re-registrations vs new registrations. if isReRegistration { - // For re-registrations, preserve existing lifecycle status if the new one is empty - // This prevents status resets that cause oscillation - if newNode.LifecycleStatus == "" && existingNode.LifecycleStatus != "" { + // Detect admin revocation: pending_approval with nil/empty approved tags + // means an admin explicitly revoked this agent's tags. In that case, + // force the agent to stay in pending_approval until re-approved. + adminRevoked := existingNode.LifecycleStatus == types.AgentStatusPendingApproval && + len(existingNode.ApprovedTags) == 0 + + if adminRevoked { + newNode.LifecycleStatus = types.AgentStatusPendingApproval + } else { + // Preserve existing approval state from the database. + // The SDK never sends approved_tags (only proposed_tags), so without + // this the UPSERT would overwrite approved_tags with an empty array, + // forcing re-approval after every CP restart or re-registration. + newNode.ApprovedTags = existingNode.ApprovedTags newNode.LifecycleStatus = existingNode.LifecycleStatus - } else if newNode.LifecycleStatus == "" { - newNode.LifecycleStatus = types.AgentStatusStarting + + // Carry over per-reasoner and per-skill approved tags. + if len(existingNode.ApprovedTags) > 0 { + approvedSet := make(map[string]struct{}) + for _, t := range existingNode.ApprovedTags { + approvedSet[strings.ToLower(strings.TrimSpace(t))] = struct{}{} + } + for i := range newNode.Reasoners { + var approved []string + proposed := newNode.Reasoners[i].ProposedTags + if len(proposed) == 0 { + proposed = newNode.Reasoners[i].Tags + } + for _, t := range proposed { + if _, ok := approvedSet[strings.ToLower(strings.TrimSpace(t))]; ok { + approved = append(approved, t) + } + } + newNode.Reasoners[i].ApprovedTags = approved + } + for i := range newNode.Skills { + var approved []string + proposed := newNode.Skills[i].ProposedTags + if len(proposed) == 0 { + proposed = newNode.Skills[i].Tags + } + for _, t := range proposed { + if _, ok := approvedSet[strings.ToLower(strings.TrimSpace(t))]; ok { + approved = append(approved, t) + } + } + newNode.Skills[i].ApprovedTags = approved + } + } + + // If lifecycle was offline or empty, reset to starting so the + // agent can go through normal startup. + if newNode.LifecycleStatus == "" || newNode.LifecycleStatus == types.AgentStatusOffline { + newNode.LifecycleStatus = types.AgentStatusStarting + } } } else { // For new registrations, use provided status or default to starting @@ -506,6 +602,29 @@ func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *ser } newNode.Metadata.Custom["callback_discovery"] = newNode.CallbackDiscovery + // Evaluate tag approval rules if the service is available and enabled. + // With default_mode=auto and no rules, this is a no-op (all tags auto-approved). + var tagApprovalResult *services.TagApprovalResult + if tagApprovalService != nil && tagApprovalService.IsEnabled() { + result := tagApprovalService.ProcessRegistrationTags(&newNode) + tagApprovalResult = &result + if len(result.Forbidden) > 0 { + c.JSON(http.StatusForbidden, gin.H{ + "error": "forbidden_tags", + "message": "Registration rejected: agent proposes forbidden tags", + "forbidden_tags": result.Forbidden, + }) + return + } + if !result.AllAutoApproved { + logger.Logger.Info(). + Str("agent_id", newNode.ID). + Strs("pending_tags", result.ManualReview). + Strs("auto_approved", result.AutoApproved). + Msg("Agent registration requires tag approval") + } + } + // Store the new node if err := storageProvider.RegisterAgent(ctx, &newNode); err != nil { logger.Logger.Error().Err(err).Msg("❌ Storage error") @@ -558,11 +677,28 @@ func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *ser } } + // Create DID:web document so the DID auth middleware can verify this agent. + // This is non-fatal — DID:key registration above is the critical path. + if didWebService != nil { + if _, _, err := didWebService.GetOrCreateDIDDocument(ctx, newNode.ID); err != nil { + logger.Logger.Warn().Err(err).Msgf("⚠️ DID:web document creation failed for node %s (non-fatal)", newNode.ID) + } else { + logger.Logger.Debug().Msgf("✅ DID:web document ensured for node %s", newNode.ID) + } + } + + // Issue Tag VC for auto-approved agents now that agent + DID are stored. + // This must happen AFTER RegisterAgent + DID registration so that + // issueTagVC can look up the agent's DID from storage. + if tagApprovalResult != nil && tagApprovalResult.AllAutoApproved && len(tagApprovalResult.AutoApproved) > 0 && tagApprovalService != nil { + tagApprovalService.IssueAutoApprovedTagsVC(ctx, newNode.ID, tagApprovalResult.AutoApproved) + } + // Note: Node registration events are now handled by the health monitor // The health monitor will detect the new node and emit appropriate events if presenceManager != nil { - presenceManager.Touch(newNode.ID, time.Now().UTC()) + presenceManager.Touch(newNode.ID, newNode.Version, time.Now().UTC()) } responsePayload := gin.H{ @@ -579,6 +715,15 @@ func RegisterNodeHandler(storageProvider storage.StorageProvider, uiService *ser responsePayload["callback_discovery"] = newNode.CallbackDiscovery } + // Include tag approval status in response when agent is pending + if newNode.LifecycleStatus == types.AgentStatusPendingApproval && tagApprovalResult != nil { + responsePayload["status"] = "pending_approval" + responsePayload["message"] = "Node registered but awaiting tag approval" + responsePayload["proposed_tags"] = newNode.ProposedTags + responsePayload["pending_tags"] = tagApprovalResult.ManualReview + responsePayload["auto_approved_tags"] = tagApprovalResult.AutoApproved + } + c.JSON(http.StatusCreated, responsePayload) } } @@ -605,6 +750,11 @@ func ListNodesHandler(storageProvider storage.StorageProvider) gin.HandlerFunc { filters.TeamID = &teamID } + // Check for group_id filter parameter + if groupID := c.Query("group_id"); groupID != "" { + filters.GroupID = &groupID + } + // Check for show_all parameter to override default active filter if showAll := c.Query("show_all"); showAll == "true" { filters.HealthStatus = nil // Remove health status filter to show all nodes @@ -635,8 +785,14 @@ func GetNodeHandler(storageProvider storage.StorageProvider) gin.HandlerFunc { return } - node, err := storageProvider.GetAgent(ctx, nodeID) - if err != nil { + var node *types.AgentNode + var err error + if version := c.Query("version"); version != "" { + node, err = storageProvider.GetAgentVersion(ctx, nodeID, version) + } else { + node, err = storageProvider.GetAgent(ctx, nodeID) + } + if err != nil || node == nil { c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } @@ -662,6 +818,7 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic // Try to parse enhanced heartbeat data (optional) var enhancedHeartbeat struct { + Version string `json:"version,omitempty"` Status string `json:"status,omitempty"` MCPServers []struct { Alias string `json:"alias"` @@ -669,7 +826,7 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic ToolCount int `json:"tool_count"` } `json:"mcp_servers,omitempty"` Timestamp string `json:"timestamp,omitempty"` - HealthScore *int `json:"health_score,omitempty"` // New: allow agents to report health score + HealthScore *int `json:"health_score,omitempty"` } // Read the request body if present @@ -685,13 +842,19 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic // Check if database update is needed using caching now := time.Now().UTC() if presenceManager != nil && presenceManager.HasLease(nodeID) { - presenceManager.Touch(nodeID, now) + presenceManager.Touch(nodeID, enhancedHeartbeat.Version, now) } needsDBUpdate, cached := heartbeatCache.shouldUpdateDatabase(nodeID, now, enhancedHeartbeat.Status, enhancedHeartbeat.MCPServers) if needsDBUpdate { - // Verify node exists only when we need to update DB - existingNode, err := storageProvider.GetAgent(ctx, nodeID) + // Verify node exists only when we need to update DB. + // Use the outer-scoped existingNode so it's available for status processing below. + var err error + if enhancedHeartbeat.Version != "" { + existingNode, err = storageProvider.GetAgentVersion(ctx, nodeID, enhancedHeartbeat.Version) + } else { + existingNode, err = storageProvider.GetAgent(ctx, nodeID) + } if err != nil { logger.Logger.Error().Err(err).Msgf("❌ Node %s not found during heartbeat update", nodeID) c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) @@ -711,11 +874,13 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic } if presenceManager != nil { - presenceManager.Touch(nodeID, now) + presenceManager.Touch(nodeID, existingNode.Version, now) } - // Process heartbeat asynchronously to avoid blocking the response - processHeartbeatAsync(storageProvider, uiService, nodeID, cached) + // Process heartbeat asynchronously to avoid blocking the response. + // Use existingNode.Version (resolved from DB) instead of the heartbeat payload version + // to handle old SDKs that may not send version in heartbeats. + processHeartbeatAsync(storageProvider, uiService, nodeID, existingNode.Version, cached) logger.Logger.Debug().Msgf("💓 Heartbeat DB update queued for node: %s at %s", nodeID, now.Format(time.RFC3339)) } else { @@ -736,8 +901,24 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic } if validStatuses[enhancedHeartbeat.Status] { - status := types.AgentLifecycleStatus(enhancedHeartbeat.Status) - lifecycleStatus = &status + // Protect pending_approval: heartbeats cannot override admin-controlled state + if existingNode == nil { + var err error + if enhancedHeartbeat.Version != "" { + existingNode, err = storageProvider.GetAgentVersion(ctx, nodeID, enhancedHeartbeat.Version) + } else { + existingNode, err = storageProvider.GetAgent(ctx, nodeID) + } + if err != nil { + logger.Logger.Error().Err(err).Msgf("❌ Failed to get node %s for pending_approval check", nodeID) + } + } + if existingNode != nil && existingNode.LifecycleStatus == types.AgentStatusPendingApproval { + logger.Logger.Debug().Msgf("⏸️ Ignoring heartbeat status update for node %s: agent is pending_approval (admin action required)", nodeID) + } else { + status := types.AgentLifecycleStatus(enhancedHeartbeat.Status) + lifecycleStatus = &status + } } } @@ -779,8 +960,14 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic } } + // Resolve version from DB record when available, fall back to heartbeat payload + resolvedVersion := enhancedHeartbeat.Version + if existingNode != nil { + resolvedVersion = existingNode.Version + } + // Update status through unified system - if err := statusManager.UpdateFromHeartbeat(ctx, nodeID, lifecycleStatus, mcpStatus); err != nil { + if err := statusManager.UpdateFromHeartbeat(ctx, nodeID, lifecycleStatus, mcpStatus, resolvedVersion); err != nil { logger.Logger.Error().Err(err).Msgf("❌ Failed to update unified status for node %s", nodeID) // Continue processing - don't fail the heartbeat } @@ -791,6 +978,7 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic HealthScore: enhancedHeartbeat.HealthScore, Source: types.StatusSourceHeartbeat, Reason: "health score from heartbeat", + Version: resolvedVersion, } if err := statusManager.UpdateAgentStatus(ctx, nodeID, update); err != nil { @@ -815,14 +1003,20 @@ func HeartbeatHandler(storageProvider storage.StorageProvider, uiService *servic if existingNode == nil { var err error existingNode, err = storageProvider.GetAgent(ctx, nodeID) - if err != nil { + if (err != nil || existingNode == nil) && enhancedHeartbeat.Version != "" { + existingNode, err = storageProvider.GetAgentVersion(ctx, nodeID, enhancedHeartbeat.Version) + } + if err != nil || existingNode == nil { logger.Logger.Error().Err(err).Msgf("❌ Failed to get node %s for lifecycle status update", nodeID) c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } } - if existingNode.LifecycleStatus != newStatus { + // Protect pending_approval: heartbeats cannot override admin-controlled state + if existingNode.LifecycleStatus == types.AgentStatusPendingApproval { + logger.Logger.Debug().Msgf("⏸️ Ignoring legacy heartbeat status for node %s: agent is pending_approval", nodeID) + } else if existingNode.LifecycleStatus != newStatus { if err := storageProvider.UpdateAgentLifecycleStatus(ctx, nodeID, newStatus); err != nil { logger.Logger.Error().Err(err).Msgf("❌ Failed to update lifecycle status for node %s", nodeID) } else { @@ -885,14 +1079,22 @@ func UpdateLifecycleStatusHandler(storageProvider storage.StorageProvider, uiSer } // Verify node exists - _, err := storageProvider.GetAgent(ctx, nodeID) + existingNode, err := storageProvider.GetAgent(ctx, nodeID) if err != nil { c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } - // Prepare status update for unified system + // Protect pending_approval: only admin tag approval can transition out of this state newLifecycleStatus := types.AgentLifecycleStatus(statusUpdate.LifecycleStatus) + if existingNode.LifecycleStatus == types.AgentStatusPendingApproval { + logger.Logger.Debug().Msgf("⏸️ Rejecting lifecycle status update for node %s: agent is pending_approval (admin action required)", nodeID) + c.JSON(http.StatusConflict, gin.H{ + "error": "agent_pending_approval", + "message": "Cannot update lifecycle status: agent is awaiting tag approval. Use admin approval endpoint instead.", + }) + return + } // Prepare MCP status if provided var mcpStatus *types.MCPStatusInfo @@ -921,7 +1123,7 @@ func UpdateLifecycleStatusHandler(storageProvider storage.StorageProvider, uiSer // Update through unified status system if available if statusManager != nil { - if err := statusManager.UpdateFromHeartbeat(ctx, nodeID, &newLifecycleStatus, mcpStatus); err != nil { + if err := statusManager.UpdateFromHeartbeat(ctx, nodeID, &newLifecycleStatus, mcpStatus, ""); err != nil { logger.Logger.Error().Err(err).Msgf("❌ Failed to update unified status for node %s", nodeID) c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update status"}) return @@ -1124,7 +1326,7 @@ func BulkNodeStatusHandler(statusManager *services.StatusManager, storageProvide // RegisterServerlessAgentHandler handles the registration of a serverless agent node // by discovering its capabilities via the /discover endpoint -func RegisterServerlessAgentHandler(storageProvider storage.StorageProvider, uiService *services.UIService, didService *services.DIDService, presenceManager *services.PresenceManager) gin.HandlerFunc { +func RegisterServerlessAgentHandler(storageProvider storage.StorageProvider, uiService *services.UIService, didService *services.DIDService, presenceManager *services.PresenceManager, didWebService *services.DIDWebService) gin.HandlerFunc { return func(c *gin.Context) { ctx := c.Request.Context() @@ -1318,9 +1520,19 @@ func RegisterServerlessAgentHandler(storageProvider storage.StorageProvider, uiS } } + // Create DID:web document so the DID auth middleware can verify this agent. + // This is non-fatal — DID:key registration above is the critical path. + if didWebService != nil { + if _, _, err := didWebService.GetOrCreateDIDDocument(ctx, newNode.ID); err != nil { + logger.Logger.Warn().Err(err).Msgf("⚠️ DID:web document creation failed for serverless agent %s (non-fatal)", newNode.ID) + } else { + logger.Logger.Debug().Msgf("✅ DID:web document ensured for serverless agent %s", newNode.ID) + } + } + // Touch presence manager if presenceManager != nil { - presenceManager.Touch(newNode.ID, time.Now().UTC()) + presenceManager.Touch(newNode.ID, newNode.Version, time.Now().UTC()) } c.JSON(http.StatusCreated, gin.H{ diff --git a/control-plane/internal/handlers/nodes_rest.go b/control-plane/internal/handlers/nodes_rest.go index d8d42626..1774bb9b 100644 --- a/control-plane/internal/handlers/nodes_rest.go +++ b/control-plane/internal/handlers/nodes_rest.go @@ -33,6 +33,7 @@ func NodeStatusLeaseHandler(storageProvider storage.StorageProvider, statusManag var payload struct { Phase string `json:"phase"` + Version string `json:"version"` HealthScore *int `json:"health_score"` // Conditions are accepted for future use but currently ignored by the control plane. Conditions []map[string]interface{} `json:"conditions"` @@ -43,14 +44,37 @@ func NodeStatusLeaseHandler(storageProvider storage.StorageProvider, statusManag return } - agent, err := storageProvider.GetAgent(ctx, nodeID) + var agent *types.AgentNode + var err error + if payload.Version != "" { + agent, err = storageProvider.GetAgentVersion(ctx, nodeID, payload.Version) + } else { + agent, err = storageProvider.GetAgent(ctx, nodeID) + } if err != nil || agent == nil { c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } + // Protect pending_approval from being overwritten by agent status updates. + // Skip all status changes — only renew the lease heartbeat timestamp. + if agent.LifecycleStatus == types.AgentStatusPendingApproval { + logger.Logger.Debug().Str("node_id", nodeID).Msg("ignoring status update: agent is pending_approval") + now := time.Now().UTC() + _ = storageProvider.UpdateAgentHeartbeat(ctx, nodeID, agent.Version, now) + if presenceManager != nil { + presenceManager.Touch(nodeID, agent.Version, now) + } + c.JSON(http.StatusOK, gin.H{ + "lease_seconds": int(leaseTTL.Seconds()), + "next_lease_renewal": now.Add(leaseTTL).Format(time.RFC3339), + }) + return + } + update := &types.AgentStatusUpdate{ - Source: types.StatusSourceManual, + Source: types.StatusSourceManual, + Version: agent.Version, } if payload.HealthScore != nil { @@ -80,12 +104,12 @@ func NodeStatusLeaseHandler(storageProvider storage.StorageProvider, statusManag } now := time.Now().UTC() - if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, now); err != nil { + if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, agent.Version, now); err != nil { logger.Logger.Warn().Err(err).Str("node_id", nodeID).Msg("failed to persist heartbeat during status update") } if presenceManager != nil { - presenceManager.Touch(nodeID, now) + presenceManager.Touch(nodeID, agent.Version, now) } c.JSON(http.StatusOK, gin.H{ @@ -129,7 +153,8 @@ func NodeActionAckHandler(storageProvider storage.StorageProvider, presenceManag return } - if _, err := storageProvider.GetAgent(ctx, nodeID); err != nil { + agent, err := storageProvider.GetAgent(ctx, nodeID) + if err != nil || agent == nil { c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } @@ -142,11 +167,11 @@ func NodeActionAckHandler(storageProvider storage.StorageProvider, presenceManag Msg("action acknowledgement received") now := time.Now().UTC() - if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, now); err != nil { + if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, agent.Version, now); err != nil { logger.Logger.Warn().Err(err).Str("node_id", nodeID).Msg("failed to persist heartbeat during action ack") } if presenceManager != nil { - presenceManager.Touch(nodeID, now) + presenceManager.Touch(nodeID, agent.Version, now) } c.JSON(http.StatusOK, gin.H{ @@ -186,17 +211,18 @@ func ClaimActionsHandler(storageProvider storage.StorageProvider, presenceManage payload.MaxItems = 1 } - if _, err := storageProvider.GetAgent(ctx, payload.NodeID); err != nil { + agent, err := storageProvider.GetAgent(ctx, payload.NodeID) + if err != nil || agent == nil { c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) return } now := time.Now().UTC() - if err := storageProvider.UpdateAgentHeartbeat(ctx, payload.NodeID, now); err != nil { + if err := storageProvider.UpdateAgentHeartbeat(ctx, payload.NodeID, agent.Version, now); err != nil { logger.Logger.Warn().Err(err).Str("node_id", payload.NodeID).Msg("failed to persist heartbeat during claim") } if presenceManager != nil { - presenceManager.Touch(payload.NodeID, now) + presenceManager.Touch(payload.NodeID, agent.Version, now) } nextPoll := payload.WaitSeconds @@ -223,22 +249,30 @@ func NodeShutdownHandler(storageProvider storage.StorageProvider, statusManager return } - if _, err := storageProvider.GetAgent(ctx, nodeID); err != nil { - c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) - return - } - var payload struct { Reason string `json:"reason"` + Version string `json:"version"` ExpectedRestart string `json:"expected_restart"` } _ = c.ShouldBindJSON(&payload) // best-effort parse; optional fields + var agent *types.AgentNode + var err error + if payload.Version != "" { + agent, err = storageProvider.GetAgentVersion(ctx, nodeID, payload.Version) + } else { + agent, err = storageProvider.GetAgent(ctx, nodeID) + } + if err != nil || agent == nil { + c.JSON(http.StatusNotFound, gin.H{"error": "node not found"}) + return + } + now := time.Now().UTC() if presenceManager != nil { presenceManager.Forget(nodeID) } - if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, now); err != nil { + if err := storageProvider.UpdateAgentHeartbeat(ctx, nodeID, agent.Version, now); err != nil { logger.Logger.Warn().Err(err).Str("node_id", nodeID).Msg("failed to persist heartbeat during shutdown") } @@ -250,6 +284,7 @@ func NodeShutdownHandler(storageProvider storage.StorageProvider, statusManager LifecycleStatus: &lifecycle, Source: types.StatusSourceManual, Reason: "agent shutdown", + Version: agent.Version, } if err := statusManager.UpdateAgentStatus(ctx, nodeID, update); err != nil { logger.Logger.Error().Err(err).Str("node_id", nodeID).Msg("failed to update status during shutdown") diff --git a/control-plane/internal/handlers/test_helpers_test.go b/control-plane/internal/handlers/test_helpers_test.go index 978410b4..2a4bf1af 100644 --- a/control-plane/internal/handlers/test_helpers_test.go +++ b/control-plane/internal/handlers/test_helpers_test.go @@ -45,6 +45,10 @@ func (s *testExecutionStorage) GetAgent(ctx context.Context, id string) (*types. return nil, nil } +func (s *testExecutionStorage) ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) { + return nil, nil +} + func (s *testExecutionStorage) StoreWorkflowExecution(ctx context.Context, execution *types.WorkflowExecution) error { s.mu.Lock() defer s.mu.Unlock() diff --git a/control-plane/internal/handlers/ui/api_test.go b/control-plane/internal/handlers/ui/api_test.go index 681a207c..f802e187 100644 --- a/control-plane/internal/handlers/ui/api_test.go +++ b/control-plane/internal/handlers/ui/api_test.go @@ -3,6 +3,7 @@ package ui import ( "context" "encoding/json" + "fmt" "net/http" "net/http/httptest" "strings" @@ -99,11 +100,11 @@ func TestGetNodeDetailsHandler_Structure(t *testing.T) { router := gin.New() router.GET("/api/ui/v1/nodes/:nodeId", handler.GetNodeDetailsHandler) - // Test with missing nodeId (should return 400) + // Test with missing nodeId - Gin returns 404 because the route doesn't match req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/nodes/", nil) resp := httptest.NewRecorder() router.ServeHTTP(resp, req) - assert.Equal(t, http.StatusBadRequest, resp.Code) + assert.Equal(t, http.StatusNotFound, resp.Code) // Test with nodeId (should return 404 if not found, but handler works) req = httptest.NewRequest(http.MethodGet, "/api/ui/v1/nodes/node-1", nil) @@ -137,6 +138,7 @@ func TestGetNodeStatusHandler_Structure(t *testing.T) { mockAgentClient := &MockAgentClientForUI{} mockAgentService := &MockAgentServiceForUI{} + mockAgentClient.On("GetAgentStatus", mock.Anything, "node-1").Return(nil, fmt.Errorf("agent not found")) statusManager := services.NewStatusManager(realStorage, services.StatusManagerConfig{}, nil, mockAgentClient) uiService := services.NewUIService(realStorage, mockAgentClient, mockAgentService, statusManager) @@ -175,8 +177,17 @@ func TestRefreshNodeStatusHandler_Structure(t *testing.T) { require.NoError(t, err) defer realStorage.Close(ctx) + // Register the agent in storage so status lookups succeed + require.NoError(t, realStorage.RegisterAgent(ctx, &types.AgentNode{ + ID: "node-1", + BaseURL: "http://localhost:9999", + })) + mockAgentClient := &MockAgentClientForUI{} mockAgentService := &MockAgentServiceForUI{} + // Configure mock to return an error when GetAgentStatus is called during refresh. + // A failed health check marks the agent as inactive but does NOT fail the request. + mockAgentClient.On("GetAgentStatus", mock.Anything, "node-1").Return(nil, fmt.Errorf("agent not found")) statusManager := services.NewStatusManager(realStorage, services.StatusManagerConfig{}, nil, mockAgentClient) uiService := services.NewUIService(realStorage, mockAgentClient, mockAgentService, statusManager) @@ -189,8 +200,14 @@ func TestRefreshNodeStatusHandler_Structure(t *testing.T) { router.ServeHTTP(resp, req) - // Should handle request - assert.True(t, resp.Code >= http.StatusBadRequest) // Any response is valid + // RefreshNodeStatus succeeds even when health check fails — the agent is marked + // as inactive rather than causing an HTTP error. Verify we get a valid response. + assert.Equal(t, http.StatusOK, resp.Code) + + var result map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &result)) + // The status should reflect the agent being inactive after failed health check + assert.Contains(t, result, "state") } // TestBulkNodeStatusHandler_Validation tests bulk node status handler request validation @@ -217,9 +234,15 @@ func TestBulkNodeStatusHandler_Validation(t *testing.T) { mockAgentClient := &MockAgentClientForUI{} mockAgentService := &MockAgentServiceForUI{} + // Set up mock to handle any GetAgentStatus calls (health check returns error → agent marked inactive) + mockAgentClient.On("GetAgentStatus", mock.Anything, mock.Anything).Return(nil, fmt.Errorf("agent not reachable")) statusManager := services.NewStatusManager(realStorage, services.StatusManagerConfig{}, nil, mockAgentClient) uiService := services.NewUIService(realStorage, mockAgentClient, mockAgentService, statusManager) + // Register agents in storage so status lookups succeed + require.NoError(t, realStorage.RegisterAgent(ctx, &types.AgentNode{ID: "node-1", BaseURL: "http://localhost:9991"})) + require.NoError(t, realStorage.RegisterAgent(ctx, &types.AgentNode{ID: "node-2", BaseURL: "http://localhost:9992"})) + handler := NewNodesHandler(uiService) router := gin.New() router.POST("/api/ui/v1/nodes/status/bulk", handler.BulkNodeStatusHandler) @@ -246,8 +269,8 @@ func TestBulkNodeStatusHandler_Validation(t *testing.T) { resp = httptest.NewRecorder() router.ServeHTTP(resp, req) - // Should process request (may return error if nodes don't exist, but handler works) - assert.True(t, resp.Code >= http.StatusOK) + // Should process request successfully (agents exist, health checks fail gracefully) + assert.Equal(t, http.StatusOK, resp.Code) } // TestGetDashboardSummaryHandler_Structure tests dashboard handler structure diff --git a/control-plane/internal/handlers/ui/authorization.go b/control-plane/internal/handlers/ui/authorization.go new file mode 100644 index 00000000..4ea563d4 --- /dev/null +++ b/control-plane/internal/handlers/ui/authorization.go @@ -0,0 +1,68 @@ +package ui + +import ( + "net/http" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/internal/storage" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" +) + +// AuthorizationHandler handles authorization-related UI endpoints. +type AuthorizationHandler struct { + storage storage.StorageProvider +} + +// NewAuthorizationHandler creates a new authorization handler. +func NewAuthorizationHandler(storage storage.StorageProvider) *AuthorizationHandler { + return &AuthorizationHandler{storage: storage} +} + +// AgentTagSummaryResponse is the per-agent response for the authorization agents list. +type AgentTagSummaryResponse struct { + AgentID string `json:"agent_id"` + ProposedTags []string `json:"proposed_tags"` + ApprovedTags []string `json:"approved_tags"` + LifecycleStatus string `json:"lifecycle_status"` + RegisteredAt string `json:"registered_at"` +} + +// GetAgentsWithTagsHandler returns all agents with their tag data. +// GET /api/ui/v1/authorization/agents +func (h *AuthorizationHandler) GetAgentsWithTagsHandler(c *gin.Context) { + agents, err := h.storage.ListAgents(c.Request.Context(), types.AgentFilters{}) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to list agents for authorization view") + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "list_failed", + "message": "Failed to list agents", + }) + return + } + + responses := make([]AgentTagSummaryResponse, 0, len(agents)) + for _, agent := range agents { + proposed := agent.ProposedTags + if proposed == nil { + proposed = []string{} + } + approved := agent.ApprovedTags + if approved == nil { + approved = []string{} + } + + responses = append(responses, AgentTagSummaryResponse{ + AgentID: agent.ID, + ProposedTags: proposed, + ApprovedTags: approved, + LifecycleStatus: string(agent.LifecycleStatus), + RegisteredAt: agent.RegisteredAt.Format("2006-01-02T15:04:05Z"), + }) + } + + c.JSON(http.StatusOK, gin.H{ + "agents": responses, + "total": len(responses), + }) +} diff --git a/control-plane/internal/handlers/ui/config_test.go b/control-plane/internal/handlers/ui/config_test.go index b2aa1b91..0ef0de28 100644 --- a/control-plane/internal/handlers/ui/config_test.go +++ b/control-plane/internal/handlers/ui/config_test.go @@ -242,6 +242,22 @@ func (m *MockStorageProvider) GetAgent(ctx context.Context, id string) (*types.A return args.Get(0).(*types.AgentNode), args.Error(1) } +func (m *MockStorageProvider) GetAgentVersion(ctx context.Context, id string, version string) (*types.AgentNode, error) { + args := m.Called(ctx, id, version) + if args.Get(0) == nil { + return nil, args.Error(1) + } + return args.Get(0).(*types.AgentNode), args.Error(1) +} + +func (m *MockStorageProvider) ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) { + args := m.Called(ctx, id) + if args.Get(0) == nil { + return nil, args.Error(1) + } + return args.Get(0).([]*types.AgentNode), args.Error(1) +} + func (m *MockStorageProvider) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) { args := m.Called(ctx, filters) if args.Get(0) == nil { @@ -260,8 +276,8 @@ func (m *MockStorageProvider) UpdateAgentHealthAtomic(ctx context.Context, id st return args.Error(0) } -func (m *MockStorageProvider) UpdateAgentHeartbeat(ctx context.Context, id string, heartbeatTime time.Time) error { - args := m.Called(ctx, id, heartbeatTime) +func (m *MockStorageProvider) UpdateAgentHeartbeat(ctx context.Context, id string, version string, heartbeatTime time.Time) error { + args := m.Called(ctx, id, version, heartbeatTime) return args.Error(0) } diff --git a/control-plane/internal/handlers/ui/sse_test.go b/control-plane/internal/handlers/ui/sse_test.go index 02ac83d0..d7e59aba 100644 --- a/control-plane/internal/handlers/ui/sse_test.go +++ b/control-plane/internal/handlers/ui/sse_test.go @@ -54,6 +54,8 @@ func TestStreamExecutionEventsHandler(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() // Start handler in goroutine with timeout @@ -85,7 +87,7 @@ func TestStreamExecutionEventsHandler(t *testing.T) { time.Sleep(50 * time.Millisecond) // Cancel context to close connection (simulates client disconnect) - req.Context().Done() + cancel() // Wait for handler to finish select { @@ -94,8 +96,6 @@ func TestStreamExecutionEventsHandler(t *testing.T) { case <-time.After(500 * time.Millisecond): // Handler may still be running, that's okay for SSE } - - // Real storage doesn't need expectations } // TestStreamExecutionEventsHandler_Headers tests that SSE headers are set correctly @@ -175,6 +175,8 @@ func TestSSEEventDelivery(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() done := make(chan bool) @@ -203,14 +205,12 @@ func TestSSEEventDelivery(t *testing.T) { time.Sleep(50 * time.Millisecond) // Cancel connection - req.Context().Done() + cancel() select { case <-done: case <-time.After(200 * time.Millisecond): } - - // Real storage doesn't need expectations } // TestSSEHeartbeatMechanism tests that heartbeats keep connection alive @@ -223,6 +223,8 @@ func TestSSEHeartbeatMechanism(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() done := make(chan bool) @@ -242,7 +244,7 @@ func TestSSEHeartbeatMechanism(t *testing.T) { time.Sleep(50 * time.Millisecond) // Cancel - req.Context().Done() + cancel() select { case <-done: @@ -260,13 +262,15 @@ func TestSSEMultipleConnections(t *testing.T) { router := gin.New() router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) - // Create multiple connections + // Create multiple connections with a shared cancel connections := 3 + ctx, cancel := context.WithCancel(context.Background()) done := make(chan bool, connections) for i := 0; i < connections; i++ { go func() { req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + req = req.WithContext(ctx) resp := httptest.NewRecorder() router.ServeHTTP(resp, req) done <- true @@ -288,8 +292,16 @@ func TestSSEMultipleConnections(t *testing.T) { time.Sleep(50 * time.Millisecond) - // All connections should have been established - // (In real scenario, we'd verify all received the event) + // Cancel all connections + cancel() + + // Wait for all to finish + for i := 0; i < connections; i++ { + select { + case <-done: + case <-time.After(500 * time.Millisecond): + } + } } // TestSSEErrorHandling tests error handling in SSE handlers @@ -303,6 +315,8 @@ func TestSSEErrorHandling(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() // Test that handler works correctly with valid storage @@ -316,7 +330,7 @@ func TestSSEErrorHandling(t *testing.T) { // Verify headers are set assert.Equal(t, "text/event-stream", resp.Header().Get("Content-Type")) - req.Context().Done() + cancel() select { case <-done: case <-time.After(100 * time.Millisecond): @@ -345,15 +359,32 @@ func TestSSERequestValidation(t *testing.T) { for _, tt := range tests { t.Run(tt.method, func(t *testing.T) { req := httptest.NewRequest(tt.method, tt.path, nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() - router.ServeHTTP(resp, req) + done := make(chan bool, 1) + go func() { + router.ServeHTTP(resp, req) + done <- true + }() if tt.method == "GET" { - // GET should set SSE headers + // Wait for SSE handler to set headers + time.Sleep(20 * time.Millisecond) assert.Equal(t, "text/event-stream", resp.Header().Get("Content-Type")) + cancel() + select { + case <-done: + case <-time.After(200 * time.Millisecond): + } } else { - // Other methods should return 404 or method not allowed + // Non-GET methods return immediately (404) + select { + case <-done: + case <-time.After(200 * time.Millisecond): + } + cancel() assert.NotEqual(t, http.StatusOK, resp.Code) } }) @@ -407,6 +438,8 @@ func TestSSEConcurrentEvents(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() done := make(chan bool) @@ -442,8 +475,11 @@ func TestSSEConcurrentEvents(t *testing.T) { // Handler still running, which is good } - req.Context().Done() - time.Sleep(50 * time.Millisecond) + cancel() + select { + case <-done: + case <-time.After(200 * time.Millisecond): + } } // Helper function to verify SSE response format @@ -464,6 +500,8 @@ func TestSSEResponseFormat(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() go func() { @@ -481,7 +519,7 @@ func TestSSEResponseFormat(t *testing.T) { assert.Contains(t, []string{"*", "null"}, corsOrigin) } - req.Context().Done() + cancel() time.Sleep(20 * time.Millisecond) } @@ -496,6 +534,8 @@ func TestSSEWithQueryParameters(t *testing.T) { // Test with query parameters (should be ignored but not cause errors) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events?filter=test&limit=10", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() go func() { @@ -507,7 +547,7 @@ func TestSSEWithQueryParameters(t *testing.T) { // Should still set SSE headers verifySSEHeaders(t, resp) - req.Context().Done() + cancel() time.Sleep(20 * time.Millisecond) } @@ -555,6 +595,8 @@ func TestSSEWithInvalidStorage(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() // Test that handler works correctly with valid storage @@ -568,7 +610,7 @@ func TestSSEWithInvalidStorage(t *testing.T) { // Verify headers are set correctly assert.Equal(t, "text/event-stream", resp.Header().Get("Content-Type")) - req.Context().Done() + cancel() select { case <-done: case <-time.After(100 * time.Millisecond): @@ -586,6 +628,8 @@ func TestSSEPerformance(t *testing.T) { router.GET("/api/ui/v1/executions/events", handler.StreamExecutionEventsHandler) req := httptest.NewRequest(http.MethodGet, "/api/ui/v1/executions/events", nil) + ctx, cancel := context.WithCancel(req.Context()) + req = req.WithContext(ctx) resp := httptest.NewRecorder() start := time.Now() @@ -614,7 +658,7 @@ func TestSSEPerformance(t *testing.T) { // Should handle events quickly (not block) assert.Less(t, elapsed, 200*time.Millisecond, "SSE should handle events quickly") - req.Context().Done() + cancel() select { case <-done: case <-time.After(100 * time.Millisecond): diff --git a/control-plane/internal/server/middleware/auth.go b/control-plane/internal/server/middleware/auth.go index 0b4b08cc..bd81d81a 100644 --- a/control-plane/internal/server/middleware/auth.go +++ b/control-plane/internal/server/middleware/auth.go @@ -1,6 +1,7 @@ package middleware import ( + "crypto/subtle" "net/http" "strings" @@ -46,6 +47,12 @@ func APIKeyAuth(config AuthConfig) gin.HandlerFunc { return } + // Allow public DID document resolution (did:web spec requires public access) + if strings.HasPrefix(c.Request.URL.Path, "/api/v1/did/document/") || strings.HasPrefix(c.Request.URL.Path, "/api/v1/did/resolve/") { + c.Next() + return + } + apiKey := "" // Preferred: X-API-Key header @@ -64,7 +71,7 @@ func APIKeyAuth(config AuthConfig) gin.HandlerFunc { apiKey = c.Query("api_key") } - if apiKey != config.APIKey { + if subtle.ConstantTimeCompare([]byte(apiKey), []byte(config.APIKey)) != 1 { c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ "error": "unauthorized", "message": "invalid or missing API key", @@ -75,3 +82,28 @@ func APIKeyAuth(config AuthConfig) gin.HandlerFunc { c.Next() } } + +// AdminTokenAuth enforces a separate admin token for admin routes. +// If adminToken is empty, the middleware is a no-op (falls back to global API key auth). +// Admin tokens must be sent via the X-Admin-Token header only (not Bearer) to avoid +// collision with the API key Bearer token namespace. +func AdminTokenAuth(adminToken string) gin.HandlerFunc { + return func(c *gin.Context) { + if adminToken == "" { + c.Next() + return + } + + token := c.GetHeader("X-Admin-Token") + + if subtle.ConstantTimeCompare([]byte(token), []byte(adminToken)) != 1 { + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "forbidden", + "message": "admin token required for this operation (use X-Admin-Token header)", + }) + return + } + + c.Next() + } +} diff --git a/control-plane/internal/server/middleware/connector_auth.go b/control-plane/internal/server/middleware/connector_auth.go new file mode 100644 index 00000000..b5e97103 --- /dev/null +++ b/control-plane/internal/server/middleware/connector_auth.go @@ -0,0 +1,43 @@ +package middleware + +import ( + "crypto/subtle" + "net/http" + + "github.com/gin-gonic/gin" +) + +// ConnectorTokenAuth enforces the connector token for connector routes. +// It validates the X-Connector-Token header and injects audit correlation +// metadata (X-Command-ID, X-Command-Source) into the gin context. +func ConnectorTokenAuth(connectorToken string) gin.HandlerFunc { + return func(c *gin.Context) { + if connectorToken == "" { + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "forbidden", + "message": "connector is not configured (no token set)", + }) + return + } + + token := c.GetHeader("X-Connector-Token") + + if subtle.ConstantTimeCompare([]byte(token), []byte(connectorToken)) != 1 { + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "forbidden", + "message": "connector token required for this operation (use X-Connector-Token header)", + }) + return + } + + // Inject audit correlation metadata from the connector + if cmdID := c.GetHeader("X-Command-ID"); cmdID != "" { + c.Set("connector_command_id", cmdID) + } + if cmdSource := c.GetHeader("X-Command-Source"); cmdSource != "" { + c.Set("connector_command_source", cmdSource) + } + + c.Next() + } +} diff --git a/control-plane/internal/server/middleware/connector_capability.go b/control-plane/internal/server/middleware/connector_capability.go new file mode 100644 index 00000000..671ddb52 --- /dev/null +++ b/control-plane/internal/server/middleware/connector_capability.go @@ -0,0 +1,38 @@ +package middleware + +import ( + "net/http" + + "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/gin-gonic/gin" +) + +// ConnectorCapabilityCheck enforces that a specific capability is enabled for the +// connector token and respects read_only mode by rejecting write HTTP methods. +// This is the CP-side security boundary — even if the connector is compromised, +// requests for disabled or read-only capabilities are rejected here. +func ConnectorCapabilityCheck(capName string, capabilities map[string]config.ConnectorCapability) gin.HandlerFunc { + return func(c *gin.Context) { + cap, exists := capabilities[capName] + if !exists || !cap.Enabled { + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "capability_disabled", + "message": "capability " + capName + " is not enabled for this connector", + }) + return + } + + if cap.ReadOnly { + switch c.Request.Method { + case http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch: + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "read_only", + "message": "capability " + capName + " is read-only; write operations are not permitted", + }) + return + } + } + + c.Next() + } +} diff --git a/control-plane/internal/server/middleware/did_auth.go b/control-plane/internal/server/middleware/did_auth.go new file mode 100644 index 00000000..35e642b0 --- /dev/null +++ b/control-plane/internal/server/middleware/did_auth.go @@ -0,0 +1,338 @@ +package middleware + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "fmt" + "io" + "net/http" + "strconv" + "strings" + "sync" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/gin-gonic/gin" +) + +// DIDWebServiceInterface defines the methods required for DID verification. +// This interface allows the middleware to work with any DID service implementation. +type DIDWebServiceInterface interface { + VerifyDIDOwnership(ctx context.Context, did string, message []byte, signature []byte) (bool, error) +} + +// DIDAuthConfig holds configuration for DID authentication middleware. +type DIDAuthConfig struct { + // Enabled determines if DID authentication is active + Enabled bool + // TimestampWindowSeconds is the allowed time drift for signature timestamps (default: 300) + TimestampWindowSeconds int64 + // SkipPaths are paths that bypass DID authentication + SkipPaths []string +} + +// ContextKey is the type for context keys used by this middleware. +type ContextKey string + +const ( + // VerifiedCallerDIDKey is the context key for the verified caller DID. + VerifiedCallerDIDKey ContextKey = "verified_caller_did" + // DIDAuthSkippedKey is set when DID auth was skipped (no DID claimed). + DIDAuthSkippedKey ContextKey = "did_auth_skipped" + + // maxDIDLength is the maximum allowed DID length to prevent abuse. + maxDIDLength = 512 + + // maxBodySize is the maximum request body size for DID auth verification (1MB). + maxBodySize = 1 << 20 +) + +// signatureCache provides replay protection by tracking recently seen signatures. +// A single global instance is shared across all middleware instances to prevent +// replay attacks that target different route groups. +type signatureCache struct { + mu sync.Mutex + entries map[string]time.Time + ttl time.Duration + stop chan struct{} +} + +var ( + globalReplayCache *signatureCache + globalReplayCacheOnce sync.Once +) + +// getGlobalReplayCache returns the shared replay cache singleton. +// The TTL is set by the first caller; subsequent calls reuse the same instance. +func getGlobalReplayCache(ttl time.Duration) *signatureCache { + globalReplayCacheOnce.Do(func() { + globalReplayCache = &signatureCache{ + entries: make(map[string]time.Time), + ttl: ttl, + stop: make(chan struct{}), + } + go globalReplayCache.cleanup() + }) + return globalReplayCache +} + +// Close stops the background cleanup goroutine. +func (sc *signatureCache) Close() { + close(sc.stop) +} + +// seen returns true if this signature has been seen before (replay). +// If not seen, records it and returns false. +func (sc *signatureCache) seen(sig string) bool { + sc.mu.Lock() + defer sc.mu.Unlock() + + if expiry, exists := sc.entries[sig]; exists { + if time.Now().Before(expiry) { + return true // Replay detected + } + // Entry expired, allow reuse + delete(sc.entries, sig) + } + + sc.entries[sig] = time.Now().Add(sc.ttl) + return false +} + +// cleanup periodically removes expired entries to prevent unbounded growth. +func (sc *signatureCache) cleanup() { + ticker := time.NewTicker(sc.ttl) + defer ticker.Stop() + for { + select { + case <-ticker.C: + sc.mu.Lock() + now := time.Now() + for sig, expiry := range sc.entries { + if now.After(expiry) { + delete(sc.entries, sig) + } + } + sc.mu.Unlock() + case <-sc.stop: + return + } + } +} + +// DIDAuthMiddleware creates a gin middleware that verifies DID-based authentication. +// +// The middleware extracts X-Caller-DID, X-DID-Signature, and X-DID-Timestamp headers +// from incoming requests. If a caller DID is present, it verifies the signature +// against the caller's DID document public key. +// +// Authentication flow: +// 1. If no X-Caller-DID header is present, the request proceeds without DID auth +// 2. If X-Caller-DID is present, X-DID-Signature and X-DID-Timestamp are required +// 3. The timestamp must be within the configured time window (default: 5 minutes) +// 4. The signature is verified against: timestamp + ":" + SHA256(body) +// 5. Replay protection rejects signatures seen within the timestamp window +// 6. On successful verification, the verified DID is stored in the gin context +// +// This middleware should be applied AFTER API key authentication and BEFORE +// routes that need to know the caller's identity. +func DIDAuthMiddleware(didService DIDWebServiceInterface, config DIDAuthConfig) gin.HandlerFunc { + // Set defaults + if config.TimestampWindowSeconds <= 0 { + config.TimestampWindowSeconds = 300 // 5 minutes + } + + skipPathSet := make(map[string]struct{}, len(config.SkipPaths)) + for _, p := range config.SkipPaths { + skipPathSet[p] = struct{}{} + } + + // Use the global replay cache shared across all middleware instances + replayCache := getGlobalReplayCache(time.Duration(config.TimestampWindowSeconds) * time.Second) + + return func(c *gin.Context) { + // Skip if DID auth is disabled + if !config.Enabled { + c.Set(string(DIDAuthSkippedKey), true) + c.Next() + return + } + + // Skip explicit paths + if _, ok := skipPathSet[c.Request.URL.Path]; ok { + c.Set(string(DIDAuthSkippedKey), true) + c.Next() + return + } + + // Extract headers + callerDID := c.GetHeader("X-Caller-DID") + signature := c.GetHeader("X-DID-Signature") + timestamp := c.GetHeader("X-DID-Timestamp") + nonce := c.GetHeader("X-DID-Nonce") + + // If no DID claimed, proceed without DID auth + // This allows unauthenticated requests when DID is optional + if callerDID == "" { + c.Set(string(DIDAuthSkippedKey), true) + c.Next() + return + } + + // DID format validation with length limit to prevent abuse/log injection + if !strings.HasPrefix(callerDID, "did:") || len(callerDID) < 8 || len(callerDID) > maxDIDLength { + c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{ + "error": "invalid_did_format", + "message": "X-Caller-DID must be a valid DID", + }) + return + } + + // DID claimed - signature and timestamp are now required + if signature == "" || timestamp == "" { + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "did_auth_required", + "message": "DID claimed but signature or timestamp missing", + "details": "When X-Caller-DID is provided, X-DID-Signature and X-DID-Timestamp headers are required", + }) + return + } + + // Parse and verify timestamp (prevent replay attacks) + ts, err := strconv.ParseInt(timestamp, 10, 64) + if err != nil { + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "invalid_timestamp", + "message": "X-DID-Timestamp must be a valid Unix timestamp", + }) + return + } + + timeDiff := abs(time.Now().Unix() - ts) + if timeDiff > config.TimestampWindowSeconds { + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "timestamp_expired", + "message": "Timestamp too old or too far in future", + "details": fmt.Sprintf("Timestamp must be within %d seconds of server time", config.TimestampWindowSeconds), + }) + return + } + + // Read and restore request body for signature verification (with size limit) + bodyBytes, err := io.ReadAll(io.LimitReader(c.Request.Body, maxBodySize+1)) + if err != nil { + c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{ + "error": "body_read_error", + "message": "Failed to read request body", + }) + return + } + if len(bodyBytes) > maxBodySize { + c.AbortWithStatusJSON(http.StatusRequestEntityTooLarge, gin.H{ + "error": "body_too_large", + "message": fmt.Sprintf("Request body exceeds %d bytes limit for DID authentication", maxBodySize), + }) + return + } + // Restore body for downstream handlers + c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) + + // Build verification payload: timestamp[:nonce]:SHA256(body) + // When X-DID-Nonce header is present, include it in the payload to match + // the signing format used by SDKs (prevents replay with deterministic Ed25519) + bodyHash := sha256.Sum256(bodyBytes) + var payload string + if nonce != "" { + payload = fmt.Sprintf("%s:%s:%x", timestamp, nonce, bodyHash) + } else { + payload = fmt.Sprintf("%s:%x", timestamp, bodyHash) + } + + // Decode base64 signature + sigBytes, err := base64.StdEncoding.DecodeString(signature) + if err != nil { + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "invalid_signature_encoding", + "message": "X-DID-Signature must be valid base64", + }) + return + } + + // Replay protection: check if this signature was already used + sigHash := sha256.Sum256(sigBytes) + sigKey := hex.EncodeToString(sigHash[:]) + if replayCache.seen(sigKey) { + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "replay_detected", + "message": "This signature has already been used", + }) + return + } + + // Verify signature against DID document + valid, err := didService.VerifyDIDOwnership( + c.Request.Context(), + callerDID, + []byte(payload), + sigBytes, + ) + + if err != nil { + logger.Logger.Warn().Err(err).Str("caller_did", callerDID).Msg("DID signature verification error") + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "verification_error", + "message": "Failed to verify DID signature", + }) + return + } + + if !valid { + logger.Logger.Warn(). + Str("caller_did", callerDID). + Str("path", c.Request.URL.Path). + Msg("DID signature verification failed") + c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{ + "error": "invalid_signature", + "message": "DID signature verification failed", + "details": "The signature does not match the claimed DID's public key", + }) + return + } + + // DID verified successfully - store in context + c.Set(string(VerifiedCallerDIDKey), callerDID) + c.Next() + } +} + +// GetVerifiedCallerDID extracts the verified caller DID from the gin context. +// Returns empty string if no verified DID is present. +func GetVerifiedCallerDID(c *gin.Context) string { + if did, exists := c.Get(string(VerifiedCallerDIDKey)); exists { + if didStr, ok := did.(string); ok { + return didStr + } + } + return "" +} + +// IsDIDAuthSkipped returns true if DID authentication was skipped for this request. +func IsDIDAuthSkipped(c *gin.Context) bool { + if skipped, exists := c.Get(string(DIDAuthSkippedKey)); exists { + if skippedBool, ok := skipped.(bool); ok { + return skippedBool + } + } + return false +} + +// abs returns the absolute value of an int64. +func abs(n int64) int64 { + if n < 0 { + return -n + } + return n +} diff --git a/control-plane/internal/server/middleware/did_auth_test.go b/control-plane/internal/server/middleware/did_auth_test.go new file mode 100644 index 00000000..a09ff9c9 --- /dev/null +++ b/control-plane/internal/server/middleware/did_auth_test.go @@ -0,0 +1,368 @@ +package middleware + +import ( + "context" + "crypto/sha256" + "encoding/base64" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" +) + +// mockDIDService implements DIDWebServiceInterface for testing. +type mockDIDService struct { + verifyFunc func(ctx context.Context, did string, message []byte, signature []byte) (bool, error) +} + +func (m *mockDIDService) VerifyDIDOwnership(ctx context.Context, did string, message []byte, signature []byte) (bool, error) { + if m.verifyFunc != nil { + return m.verifyFunc(ctx, did, message, signature) + } + return true, nil +} + +// resetReplayCache resets the global replay cache between tests. +func resetReplayCache() { + globalReplayCacheOnce = sync.Once{} + globalReplayCache = nil +} + +// sigCounter generates unique signature bytes per call to avoid replay collisions. +var sigCounter atomic.Int64 + +func uniqueSig() string { + n := sigCounter.Add(1) + return base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("sig-%d", n))) +} + +func newDIDAuthRouter(service DIDWebServiceInterface, config DIDAuthConfig) *gin.Engine { + router := gin.New() + router.Use(DIDAuthMiddleware(service, config)) + router.POST("/execute/:target", func(c *gin.Context) { + did := GetVerifiedCallerDID(c) + skipped := IsDIDAuthSkipped(c) + c.JSON(http.StatusOK, gin.H{"did": did, "skipped": skipped}) + }) + return router +} + +func TestDIDAuth_Disabled(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: false}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestDIDAuth_NoDIDHeader_Skipped(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), `"skipped":true`) +} + +func TestDIDAuth_InvalidDIDFormat(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + tests := []struct { + name string + did string + }{ + {"no did: prefix", "web:example.com"}, + {"too short", "did:x"}, + {"too long", "did:" + strings.Repeat("x", 520)}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", tt.did) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + assert.Equal(t, http.StatusBadRequest, w.Code) + assert.Contains(t, w.Body.String(), "invalid_did_format") + }) + } +} + +func TestDIDAuth_MissingSignature(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "did_auth_required") +} + +func TestDIDAuth_InvalidTimestamp(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", "not-a-number") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "invalid_timestamp") +} + +func TestDIDAuth_ExpiredTimestamp(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + }) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix()-600)) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "timestamp_expired") +} + +func TestDIDAuth_FutureTimestamp(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + }) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix()+600)) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "timestamp_expired") +} + +func TestDIDAuth_InvalidBase64Signature(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", "not-valid-base64!!!") + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix())) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "invalid_signature_encoding") +} + +func TestDIDAuth_VerificationError(t *testing.T) { + resetReplayCache() + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, _ []byte, _ []byte) (bool, error) { + return false, fmt.Errorf("DID document not found") + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix())) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "verification_error") +} + +func TestDIDAuth_InvalidSignature(t *testing.T) { + resetReplayCache() + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, _ []byte, _ []byte) (bool, error) { + return false, nil + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix())) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusUnauthorized, w.Code) + assert.Contains(t, w.Body.String(), "invalid_signature") +} + +func TestDIDAuth_ValidSignature(t *testing.T) { + resetReplayCache() + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, _ []byte, _ []byte) (bool, error) { + return true, nil + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix())) + req.Header.Set("X-DID-Nonce", fmt.Sprintf("%d", time.Now().UnixNano())) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), "did:web:example.com:agents:test") +} + +func TestDIDAuth_ReplayDetection(t *testing.T) { + resetReplayCache() + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, _ []byte, _ []byte) (bool, error) { + return true, nil + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + sig := uniqueSig() + ts := fmt.Sprintf("%d", time.Now().Unix()) + + // First request should succeed + req1 := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req1.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req1.Header.Set("X-DID-Signature", sig) + req1.Header.Set("X-DID-Timestamp", ts) + w1 := httptest.NewRecorder() + router.ServeHTTP(w1, req1) + assert.Equal(t, http.StatusOK, w1.Code) + + // Same signature should be rejected + req2 := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader("{}")) + req2.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req2.Header.Set("X-DID-Signature", sig) + req2.Header.Set("X-DID-Timestamp", ts) + w2 := httptest.NewRecorder() + router.ServeHTTP(w2, req2) + assert.Equal(t, http.StatusUnauthorized, w2.Code) + assert.Contains(t, w2.Body.String(), "replay_detected") +} + +func TestDIDAuth_BodyTooLarge(t *testing.T) { + resetReplayCache() + router := newDIDAuthRouter(&mockDIDService{}, DIDAuthConfig{Enabled: true}) + + largeBody := strings.Repeat("x", maxBodySize+1) + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader(largeBody)) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", fmt.Sprintf("%d", time.Now().Unix())) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusRequestEntityTooLarge, w.Code) + assert.Contains(t, w.Body.String(), "body_too_large") +} + +func TestDIDAuth_SkipPath(t *testing.T) { + resetReplayCache() + router := gin.New() + router.Use(DIDAuthMiddleware(&mockDIDService{}, DIDAuthConfig{ + Enabled: true, + SkipPaths: []string{"/health"}, + })) + router.GET("/health", func(c *gin.Context) { + c.JSON(http.StatusOK, gin.H{"skipped": IsDIDAuthSkipped(c)}) + }) + + req := httptest.NewRequest(http.MethodGet, "/health", nil) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Contains(t, w.Body.String(), `"skipped":true`) +} + +func TestDIDAuth_PayloadFormat_WithNonce(t *testing.T) { + resetReplayCache() + var capturedMessage []byte + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, message []byte, _ []byte) (bool, error) { + capturedMessage = message + return true, nil + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + body := `{"input":"test"}` + ts := fmt.Sprintf("%d", time.Now().Unix()) + nonce := "test-nonce-123" + bodyHash := sha256.Sum256([]byte(body)) + expectedPayload := fmt.Sprintf("%s:%s:%x", ts, nonce, bodyHash) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader(body)) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", ts) + req.Header.Set("X-DID-Nonce", nonce) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Equal(t, expectedPayload, string(capturedMessage)) +} + +func TestDIDAuth_PayloadFormat_WithoutNonce(t *testing.T) { + resetReplayCache() + var capturedMessage []byte + svc := &mockDIDService{ + verifyFunc: func(_ context.Context, _ string, message []byte, _ []byte) (bool, error) { + capturedMessage = message + return true, nil + }, + } + router := newDIDAuthRouter(svc, DIDAuthConfig{Enabled: true}) + + body := `{"input":"test"}` + ts := fmt.Sprintf("%d", time.Now().Unix()) + bodyHash := sha256.Sum256([]byte(body)) + expectedPayload := fmt.Sprintf("%s:%x", ts, bodyHash) + + req := httptest.NewRequest(http.MethodPost, "/execute/agent.func", strings.NewReader(body)) + req.Header.Set("X-Caller-DID", "did:web:example.com:agents:test") + req.Header.Set("X-DID-Signature", uniqueSig()) + req.Header.Set("X-DID-Timestamp", ts) + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) + assert.Equal(t, expectedPayload, string(capturedMessage)) +} diff --git a/control-plane/internal/server/middleware/permission.go b/control-plane/internal/server/middleware/permission.go new file mode 100644 index 00000000..e19e59ff --- /dev/null +++ b/control-plane/internal/server/middleware/permission.go @@ -0,0 +1,281 @@ +package middleware + +import ( + "bytes" + "context" + "encoding/json" + "io" + "net/http" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" +) + +// AgentResolverInterface provides methods for resolving agent information. +type AgentResolverInterface interface { + GetAgent(ctx context.Context, agentID string) (*types.AgentNode, error) +} + +// DIDResolverInterface provides methods for resolving agent DIDs. +type DIDResolverInterface interface { + GenerateDIDWeb(agentID string) string + // ResolveAgentIDByDID looks up the agent ID associated with a DID. + // Returns empty string if the DID cannot be resolved. + ResolveAgentIDByDID(ctx context.Context, did string) string +} + +// AccessPolicyServiceInterface defines the methods required for tag-based policy evaluation. +type AccessPolicyServiceInterface interface { + EvaluateAccess(callerTags, targetTags []string, functionName string, inputParams map[string]any) *types.PolicyEvaluationResult +} + +// TagVCVerifierInterface defines the methods required for verifying Agent Tag VCs. +type TagVCVerifierInterface interface { + VerifyAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCDocument, error) +} + +// PermissionConfig holds configuration for permission checking. +type PermissionConfig struct { + // Enabled determines if permission checking is active + Enabled bool +} + +// PermissionCheckResult contains the result of a permission check. +type PermissionCheckResult struct { + Allowed bool + RequiresPermission bool + Error error +} + +const ( + // PermissionCheckResultKey is the context key for storing permission check results. + PermissionCheckResultKey ContextKey = "permission_check_result" + // TargetAgentKey is the context key for storing the resolved target agent. + TargetAgentKey ContextKey = "target_agent" + // TargetDIDKey is the context key for storing the target agent's DID. + TargetDIDKey ContextKey = "target_did" +) + +// PermissionCheckMiddleware creates a middleware that checks permissions before allowing +// requests to protected agents. +// +// This middleware should be applied AFTER DIDAuthMiddleware so that the verified +// caller DID is available in the context. +// +// The middleware: +// 1. Extracts the verified caller DID from context (set by DIDAuthMiddleware) +// 2. Resolves the target agent from the request path +// 3. Evaluates access policies based on caller/target tags +// 4. If a policy denies access, returns 403 Forbidden +// 5. If no policy matches, allows the request (backward compat for untagged agents) +func PermissionCheckMiddleware( + policyService AccessPolicyServiceInterface, + tagVCVerifier TagVCVerifierInterface, + agentResolver AgentResolverInterface, + didResolver DIDResolverInterface, + config PermissionConfig, +) gin.HandlerFunc { + return func(c *gin.Context) { + // Skip if permission checking is disabled + if !config.Enabled { + c.Next() + return + } + + // Extract target from path parameter + target := c.Param("target") + if target == "" { + // No target specified - let the handler deal with it + c.Next() + return + } + + // Parse target (format: "agent_id.reasoner_name") + agentID, _, err := parseTargetParam(target) + if err != nil { + c.Next() + return + } + + // Resolve the target agent + ctx := c.Request.Context() + agent, err := agentResolver.GetAgent(ctx, agentID) + if err != nil { + // Fail closed if target resolution fails to avoid bypass on transient backend errors. + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "target_resolution_failed", + "message": "Unable to resolve target agent for permission enforcement", + "target_agent_id": agentID, + }) + return + } + if agent == nil { + // Agent not found - let the handler deal with the error + c.Next() + return + } + + // Store the resolved agent in context for downstream use + c.Set(string(TargetAgentKey), agent) + + // Block calls to agents in pending_approval status + if agent.LifecycleStatus == types.AgentStatusPendingApproval { + c.AbortWithStatusJSON(http.StatusServiceUnavailable, gin.H{ + "error": "agent_pending_approval", + "message": "Target agent is awaiting tag approval and cannot receive calls", + "target_agent_id": agentID, + }) + return + } + + // Generate target DID + targetDID := didResolver.GenerateDIDWeb(agentID) + c.Set(string(TargetDIDKey), targetDID) + + // Get canonical plain tags for permission matching. + tags := services.CanonicalAgentTags(agent) + + // Extract caller DID (needed for policy evaluation). + callerDID := GetVerifiedCallerDID(c) + + // Parse function name from target param for policy evaluation. + _, functionName, _ := parseTargetParam(target) + + // Resolve caller agent identity (used by both policy evaluation and anonymous check). + var callerAgentID string + if callerDID != "" { + callerAgentID = didResolver.ResolveAgentIDByDID(ctx, callerDID) + } + if callerAgentID == "" { + callerAgentID = c.GetHeader("X-Caller-Agent-ID") + if callerAgentID == "" { + callerAgentID = c.GetHeader("X-Agent-Node-ID") + } + } + + // --- Tag-based policy evaluation --- + if policyService != nil { + var callerTags []string + + if callerAgentID != "" { + // Try to get VC-verified tags first (cryptographic proof of approved tags) + vcChecked := false + if tagVCVerifier != nil { + tagVC, vcErr := tagVCVerifier.VerifyAgentTagVC(ctx, callerAgentID) + if vcErr == nil && tagVC != nil { + callerTags = tagVC.CredentialSubject.Permissions.Tags + vcChecked = true + } else if vcErr != nil { + // VC exists but verification failed (revoked, expired, invalid signature). + // Fail closed: use empty tags so policies requiring caller tags won't match. + logger.Logger.Warn().Err(vcErr).Str("caller_agent_id", callerAgentID).Msg("Caller tag VC verification failed, using empty tags (fail-closed)") + vcChecked = true + } + } + // Fall back to registration tags only when no VC was found at all. + // This covers auto-approved agents that haven't received a Tag VC yet. + if !vcChecked && len(callerTags) == 0 { + if callerAgent, agentErr := agentResolver.GetAgent(ctx, callerAgentID); agentErr == nil && callerAgent != nil { + callerTags = services.CanonicalAgentTags(callerAgent) + } + } + } + + // Read input params from request body (peek without consuming). + // Always restore the body regardless of read success. + var inputParams map[string]any + if c.Request.Body != nil { + body, readErr := io.ReadAll(c.Request.Body) + if readErr == nil && len(body) > 0 { + c.Request.Body = io.NopCloser(bytes.NewBuffer(body)) + json.Unmarshal(body, &inputParams) //nolint:errcheck + } else if readErr == nil { + c.Request.Body = io.NopCloser(bytes.NewBuffer(body)) + } + } + + // Unwrap the "input" envelope so constraint evaluation sees flat params. + // Execute requests send {"input": {"limit": 500, ...}} but constraints + // reference parameter names directly (e.g. "limit"). + if nested, ok := inputParams["input"].(map[string]any); ok { + inputParams = nested + } + + logger.Logger.Debug(). + Str("target", target). + Str("function", functionName). + Str("caller_did", callerDID). + Str("caller_agent_id", callerAgentID). + Strs("caller_tags", callerTags). + Strs("target_tags", tags). + Msg("Permission middleware: evaluating policy") + + policyResult := policyService.EvaluateAccess(callerTags, tags, functionName, inputParams) + if policyResult.Matched { + result := &PermissionCheckResult{ + Allowed: policyResult.Allowed, + RequiresPermission: true, + } + c.Set(string(PermissionCheckResultKey), result) + + if !policyResult.Allowed { + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "access_denied", + "message": "Access denied by policy", + }) + return + } + + // Policy allows — proceed + c.Next() + return + } + } + + // No policy matched — allow (backward compat for untagged agents) + c.Set(string(PermissionCheckResultKey), &PermissionCheckResult{Allowed: true}) + c.Next() + } +} + +// GetPermissionCheckResult extracts the permission check result from the gin context. +func GetPermissionCheckResult(c *gin.Context) *PermissionCheckResult { + if result, exists := c.Get(string(PermissionCheckResultKey)); exists { + if r, ok := result.(*PermissionCheckResult); ok { + return r + } + } + return nil +} + +// GetTargetAgent extracts the resolved target agent from the gin context. +func GetTargetAgent(c *gin.Context) *types.AgentNode { + if agent, exists := c.Get(string(TargetAgentKey)); exists { + if a, ok := agent.(*types.AgentNode); ok { + return a + } + } + return nil +} + +// GetTargetDID extracts the target DID from the gin context. +func GetTargetDID(c *gin.Context) string { + if did, exists := c.Get(string(TargetDIDKey)); exists { + if d, ok := did.(string); ok { + return d + } + } + return "" +} + +// parseTargetParam parses a target parameter in the format "agent_id.reasoner_name". +func parseTargetParam(target string) (agentID, reasonerName string, err error) { + for i := 0; i < len(target); i++ { + if target[i] == '.' { + return target[:i], target[i+1:], nil + } + } + return target, "", nil +} diff --git a/control-plane/internal/server/middleware/permission_middleware_test.go b/control-plane/internal/server/middleware/permission_middleware_test.go new file mode 100644 index 00000000..fb34a135 --- /dev/null +++ b/control-plane/internal/server/middleware/permission_middleware_test.go @@ -0,0 +1,225 @@ +package middleware + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/sha256" + "encoding/base64" + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" +) + +// --- Test Mocks --- + +type testAgentResolver struct { + agents map[string]*types.AgentNode +} + +func (r *testAgentResolver) GetAgent(_ context.Context, agentID string) (*types.AgentNode, error) { + if a, ok := r.agents[agentID]; ok { + return a, nil + } + return &types.AgentNode{ID: agentID, ApprovedTags: []string{"public"}}, nil +} + +type failingAgentResolver struct{} + +func (r *failingAgentResolver) GetAgent(_ context.Context, _ string) (*types.AgentNode, error) { + return nil, fmt.Errorf("storage unavailable") +} + +type testDIDResolver struct{} + +func (r *testDIDResolver) GenerateDIDWeb(agentID string) string { + return "did:web:localhost%3A8080:agents:" + agentID +} + +func (r *testDIDResolver) ResolveAgentIDByDID(_ context.Context, _ string) string { + return "" +} + +type testDIDWebService struct { + publicKeys map[string]ed25519.PublicKey +} + +func (s *testDIDWebService) VerifyDIDOwnership(_ context.Context, did string, message []byte, signature []byte) (bool, error) { + pub, ok := s.publicKeys[did] + if !ok { + return false, fmt.Errorf("did not found") + } + return ed25519.Verify(pub, message, signature), nil +} + +type testPolicyService struct { + result *types.PolicyEvaluationResult +} + +func (s *testPolicyService) EvaluateAccess(callerTags, targetTags []string, functionName string, inputParams map[string]any) *types.PolicyEvaluationResult { + if s.result != nil { + return s.result + } + return &types.PolicyEvaluationResult{Matched: false} +} + +func signRequestBody(body []byte, did string, privateKey ed25519.PrivateKey, ts time.Time) (map[string]string, error) { + timestamp := fmt.Sprintf("%d", ts.Unix()) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + return map[string]string{ + "X-Caller-DID": did, + "X-DID-Signature": base64.StdEncoding.EncodeToString(signature), + "X-DID-Timestamp": timestamp, + }, nil +} + +// --- Test Helpers --- + +func setupTestRoute(policyService AccessPolicyServiceInterface, didService DIDWebServiceInterface, resolver AgentResolverInterface) *gin.Engine { + return setupTestRouteWithConfig(policyService, didService, resolver, PermissionConfig{Enabled: true}) +} + +func setupTestRouteWithConfig(policyService AccessPolicyServiceInterface, didService DIDWebServiceInterface, resolver AgentResolverInterface, config PermissionConfig) *gin.Engine { + gin.SetMode(gin.TestMode) + router := gin.New() + router.Use(DIDAuthMiddleware(didService, DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + if resolver == nil { + resolver = &testAgentResolver{} + } + router.Use(PermissionCheckMiddleware( + policyService, + nil, // tagVCVerifier + resolver, + &testDIDResolver{}, + config, + )) + router.POST("/api/v1/execute/:target", func(c *gin.Context) { + c.JSON(http.StatusOK, gin.H{"ok": true}) + }) + return router +} + +// --- Tests --- + +func TestPermission_PolicyAllows(t *testing.T) { + policy := &testPolicyService{result: &types.PolicyEvaluationResult{ + Matched: true, + Allowed: true, + PolicyName: "allow-analytics", + }} + router := setupTestRoute(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/target-agent.query", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestPermission_PolicyDenies(t *testing.T) { + policy := &testPolicyService{result: &types.PolicyEvaluationResult{ + Matched: true, + Allowed: false, + PolicyName: "deny-delete", + Reason: "delete_* functions denied", + }} + router := setupTestRoute(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/target-agent.delete_records", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusForbidden, w.Code) + assert.Contains(t, w.Body.String(), "access_denied") +} + +func TestPermission_NoPolicyMatchAllows(t *testing.T) { + policy := &testPolicyService{result: &types.PolicyEvaluationResult{Matched: false}} + router := setupTestRoute(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/open-agent.reasoner", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestPermission_NilPolicyServiceAllows(t *testing.T) { + router := setupTestRoute(nil, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/any-agent.reasoner", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestPermission_TargetResolutionErrorDenied(t *testing.T) { + policy := &testPolicyService{} + router := setupTestRoute(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, &failingAgentResolver{}) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/some-agent.reasoner", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusForbidden, w.Code) + assert.Contains(t, w.Body.String(), "target_resolution_failed") +} + +func TestPermission_PendingApprovalBlocked(t *testing.T) { + resolver := &testAgentResolver{agents: map[string]*types.AgentNode{ + "pending-agent": {ID: "pending-agent", LifecycleStatus: types.AgentStatusPendingApproval}, + }} + policy := &testPolicyService{} + router := setupTestRoute(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, resolver) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/pending-agent.reasoner", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusServiceUnavailable, w.Code) + assert.Contains(t, w.Body.String(), "agent_pending_approval") +} + +func TestPermission_AnonymousAllowedWhenNoPolicyMatches(t *testing.T) { + policy := &testPolicyService{result: &types.PolicyEvaluationResult{Matched: false}} + router := setupTestRouteWithConfig(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil, + PermissionConfig{Enabled: true}) + + // Request without any caller identity — allowed when no policy matches + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/target-agent.query", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} + +func TestPermission_DisabledAllowsAll(t *testing.T) { + policy := &testPolicyService{result: &types.PolicyEvaluationResult{Matched: true, Allowed: false}} + router := setupTestRouteWithConfig(policy, &testDIDWebService{publicKeys: map[string]ed25519.PublicKey{}}, nil, PermissionConfig{Enabled: false}) + + req := httptest.NewRequest(http.MethodPost, "/api/v1/execute/any-agent.reasoner", bytes.NewReader([]byte(`{"x":1}`))) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, http.StatusOK, w.Code) +} diff --git a/control-plane/internal/server/server.go b/control-plane/internal/server/server.go index 0cd61871..3e34a219 100644 --- a/control-plane/internal/server/server.go +++ b/control-plane/internal/server/server.go @@ -4,6 +4,7 @@ import ( "context" "crypto/sha256" "encoding/hex" + "encoding/json" "errors" "fmt" "net" @@ -16,9 +17,12 @@ import ( "github.com/Agent-Field/agentfield/control-plane/internal/config" "github.com/Agent-Field/agentfield/control-plane/internal/core/interfaces" + "github.com/Agent-Field/agentfield/control-plane/internal/encryption" coreservices "github.com/Agent-Field/agentfield/control-plane/internal/core/services" // Core services "github.com/Agent-Field/agentfield/control-plane/internal/events" // Event system "github.com/Agent-Field/agentfield/control-plane/internal/handlers" // Agent handlers + "github.com/Agent-Field/agentfield/control-plane/internal/handlers/admin" // Admin handlers + connectorpkg "github.com/Agent-Field/agentfield/control-plane/internal/handlers/connector" // Connector handlers "github.com/Agent-Field/agentfield/control-plane/internal/handlers/ui" // UI handlers "github.com/Agent-Field/agentfield/control-plane/internal/infrastructure/communication" "github.com/Agent-Field/agentfield/control-plane/internal/infrastructure/process" @@ -57,20 +61,24 @@ type AgentFieldServer struct { storageHealthOverride func(context.Context) gin.H cacheHealthOverride func(context.Context) gin.H // DID Services - keystoreService *services.KeystoreService - didService *services.DIDService - vcService *services.VCService - didRegistry *services.DIDRegistry - agentfieldHome string + keystoreService *services.KeystoreService + didService *services.DIDService + vcService *services.VCService + didRegistry *services.DIDRegistry + didWebService *services.DIDWebService + accessPolicyService *services.AccessPolicyService + tagApprovalService *services.TagApprovalService + tagVCVerifier *services.TagVCVerifier + agentfieldHome string // Cleanup service - cleanupService *handlers.ExecutionCleanupService - payloadStore services.PayloadStore - registryWatcherCancel context.CancelFunc - adminGRPCServer *grpc.Server - adminListener net.Listener - adminGRPCPort int - webhookDispatcher services.WebhookDispatcher - observabilityForwarder services.ObservabilityForwarder + cleanupService *handlers.ExecutionCleanupService + payloadStore services.PayloadStore + registryWatcherCancel context.CancelFunc + adminGRPCServer *grpc.Server + adminListener net.Listener + adminGRPCPort int + webhookDispatcher services.WebhookDispatcher + observabilityForwarder services.ObservabilityForwarder } // NewAgentFieldServer creates a new instance of the AgentFieldServer. @@ -180,6 +188,10 @@ func NewAgentFieldServer(cfg *config.Config) (*AgentFieldServer, error) { fmt.Println("📋 Creating DID registry...") didRegistry = services.NewDIDRegistryWithStorage(storageProvider) + if passphrase := cfg.Features.DID.Keystore.EncryptionPassphrase; passphrase != "" { + didRegistry.SetEncryptionService(encryption.NewEncryptionService(passphrase)) + fmt.Println("🔐 Master seed encryption enabled") + } fmt.Println("🆔 Creating DID service...") didService = services.NewDIDService(&cfg.Features.DID, keystoreService, didRegistry) @@ -230,6 +242,118 @@ func NewAgentFieldServer(cfg *config.Config) (*AgentFieldServer, error) { fmt.Println("⚠️ DID and VC services are DISABLED in configuration") } + // Initialize DIDWebService if DID is enabled + var didWebService *services.DIDWebService + + if cfg.Features.DID.Enabled && didService != nil { + // Determine domain for did:web identifiers + domain := cfg.Features.DID.Authorization.Domain + if domain == "" { + domain = fmt.Sprintf("localhost:%d", cfg.AgentField.Port) + } + + // Create DIDWebService + fmt.Printf("🌐 Creating DID Web service with domain: %s\n", domain) + didWebService = services.NewDIDWebService(domain, didService, storageProvider) + + if cfg.Features.DID.Authorization.Enabled { + if cfg.Features.DID.Authorization.AdminToken == "" { + logger.Logger.Error().Msg("⚠️ SECURITY WARNING: Authorization is enabled but no admin_token is configured! Admin routes (tag approval, policy management) are unprotected. Set AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN for production use.") + } + if cfg.Features.DID.Authorization.TagApprovalRules.DefaultMode == "" || cfg.Features.DID.Authorization.TagApprovalRules.DefaultMode == "auto" { + logger.Logger.Warn().Msg("⚠️ Tag approval default_mode is 'auto' — all agent tags will be auto-approved. Set tag_approval_rules.default_mode to 'manual' for production.") + } + } + } + + // Initialize tag approval service (uses config-based rules) + var tagApprovalService *services.TagApprovalService + if cfg.Features.DID.Authorization.Enabled { + tagApprovalService = services.NewTagApprovalService( + cfg.Features.DID.Authorization.TagApprovalRules, + storageProvider, + ) + if tagApprovalService.IsEnabled() { + logger.Logger.Info().Msg("🏷️ Tag approval service enabled with rules") + } + } + + // Initialize access policy service (tag-based authorization) + var accessPolicyService *services.AccessPolicyService + if cfg.Features.DID.Authorization.Enabled { + accessPolicyService = services.NewAccessPolicyService(storageProvider) + if err := accessPolicyService.Initialize(context.Background()); err != nil { + logger.Logger.Warn().Err(err).Msg("Failed to initialize access policy service") + } else { + logger.Logger.Info().Msg("📋 Access policy service initialized") + } + + // Seed access policies from config file + if len(cfg.Features.DID.Authorization.AccessPolicies) > 0 { + ctx := context.Background() + seededCount := 0 + for _, policyCfg := range cfg.Features.DID.Authorization.AccessPolicies { + desc := "" + if policyCfg.Name != "" { + desc = "Seeded from config" + } + constraints := make(map[string]types.AccessConstraint) + for k, v := range policyCfg.Constraints { + constraints[k] = types.AccessConstraint{ + Operator: v.Operator, + Value: v.Value, + } + } + _, err := accessPolicyService.AddPolicy(ctx, &types.AccessPolicyRequest{ + Name: policyCfg.Name, + CallerTags: policyCfg.CallerTags, + TargetTags: policyCfg.TargetTags, + AllowFunctions: policyCfg.AllowFunctions, + DenyFunctions: policyCfg.DenyFunctions, + Constraints: constraints, + Action: policyCfg.Action, + Priority: policyCfg.Priority, + Description: desc, + }) + if err != nil { + logger.Logger.Debug(). + Err(err). + Str("policy_name", policyCfg.Name). + Msg("Failed to seed access policy from config (may already exist)") + } else { + seededCount++ + } + } + if seededCount > 0 { + logger.Logger.Info(). + Int("seeded_count", seededCount). + Int("total_config_policies", len(cfg.Features.DID.Authorization.AccessPolicies)). + Msg("Seeded access policies from config") + } + } + } + + // Initialize tag VC verifier for cryptographic tag verification at call time + var tagVCVerifier *services.TagVCVerifier + if cfg.Features.DID.Authorization.Enabled && vcService != nil { + tagVCVerifier = services.NewTagVCVerifier(storageProvider, vcService) + logger.Logger.Info().Msg("🔐 Tag VC verifier initialized") + } + + // Wire VC service into tag approval service for VC issuance on approval + if tagApprovalService != nil && vcService != nil { + tagApprovalService.SetVCService(vcService) + logger.Logger.Info().Msg("🏷️ Tag approval service configured for VC issuance") + } + + // Wire revocation callback to clear status cache and presence lease + if tagApprovalService != nil { + tagApprovalService.SetOnRevokeCallback(func(ctx context.Context, agentID string) { + presenceManager.Forget(agentID) + _ = statusManager.RefreshAgentStatus(ctx, agentID) + }) + } + payloadStore := services.NewFilePayloadStore(dirs.PayloadsDir) webhookDispatcher := services.NewWebhookDispatcher(storageProvider, services.WebhookDispatcherConfig{ @@ -270,28 +394,32 @@ func NewAgentFieldServer(cfg *config.Config) (*AgentFieldServer, error) { } return &AgentFieldServer{ - storage: storageProvider, - cache: cacheProvider, - Router: Router, - uiService: uiService, - executionsUIService: executionsUIService, - healthMonitor: healthMonitor, - presenceManager: presenceManager, - statusManager: statusManager, - agentService: agentService, - agentClient: agentClient, - config: cfg, - keystoreService: keystoreService, - didService: didService, - vcService: vcService, - didRegistry: didRegistry, - agentfieldHome: agentfieldHome, - cleanupService: cleanupService, - payloadStore: payloadStore, - webhookDispatcher: webhookDispatcher, - observabilityForwarder: observabilityForwarder, - registryWatcherCancel: nil, - adminGRPCPort: adminPort, + storage: storageProvider, + cache: cacheProvider, + Router: Router, + uiService: uiService, + executionsUIService: executionsUIService, + healthMonitor: healthMonitor, + presenceManager: presenceManager, + statusManager: statusManager, + agentService: agentService, + agentClient: agentClient, + config: cfg, + keystoreService: keystoreService, + didService: didService, + vcService: vcService, + didRegistry: didRegistry, + didWebService: didWebService, + accessPolicyService: accessPolicyService, + tagApprovalService: tagApprovalService, + tagVCVerifier: tagVCVerifier, + agentfieldHome: agentfieldHome, + cleanupService: cleanupService, + payloadStore: payloadStore, + webhookDispatcher: webhookDispatcher, + observabilityForwarder: observabilityForwarder, + registryWatcherCancel: nil, + adminGRPCPort: adminPort, }, nil } @@ -304,15 +432,14 @@ func (s *AgentFieldServer) Start() error { go s.statusManager.Start() if s.presenceManager != nil { - go s.presenceManager.Start() + // Recover presence leases BEFORE starting the sweep loop so the first + // sweep sees all previously-registered agents instead of an empty map. + ctx := context.Background() + if err := s.presenceManager.RecoverFromDatabase(ctx, s.storage); err != nil { + logger.Logger.Error().Err(err).Msg("Failed to recover presence leases from database") + } - // Recover presence leases from database - go func() { - ctx := context.Background() - if err := s.presenceManager.RecoverFromDatabase(ctx, s.storage); err != nil { - logger.Logger.Error().Err(err).Msg("Failed to recover presence leases from database") - } - }() + go s.presenceManager.Start() } // Start health monitor service in background @@ -539,6 +666,80 @@ func (s *AgentFieldServer) healthCheckHandler(c *gin.Context) { c.JSON(http.StatusOK, healthStatus) } +// handleDIDWebServerDocument serves the server's root DID document per W3C did:web spec. +// GET /.well-known/did.json -> resolves did:web:{domain} +func (s *AgentFieldServer) handleDIDWebServerDocument(c *gin.Context) { + serverID, err := s.didService.GetAgentFieldServerID() + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": "server DID not available"}) + return + } + registry, err := s.didService.GetRegistry(serverID) + if err != nil || registry == nil || registry.RootDID == "" { + c.JSON(http.StatusNotFound, gin.H{"error": "server DID not found"}) + return + } + s.serveDIDDocument(c, registry.RootDID) +} + +// handleDIDWebAgentDocument serves an agent's DID document per W3C did:web spec. +// GET /agents/:agentID/did.json -> resolves did:web:{domain}:agents:{agentID} +func (s *AgentFieldServer) handleDIDWebAgentDocument(c *gin.Context) { + agentID := c.Param("agentID") + if agentID == "" { + c.JSON(http.StatusBadRequest, gin.H{"error": "agent ID is required"}) + return + } + did := s.didWebService.GenerateDIDWeb(agentID) + s.serveDIDDocument(c, did) +} + +// serveDIDDocument resolves a DID and returns a W3C-compliant DID document. +// It tries did:web resolution (database) first, then falls back to did:key (in-memory). +func (s *AgentFieldServer) serveDIDDocument(c *gin.Context, did string) { + // Try did:web resolution via DIDWebService (stored in database) + if s.didWebService != nil && strings.HasPrefix(did, "did:web:") { + result, err := s.didWebService.ResolveDID(c.Request.Context(), did) + if err == nil && result.DIDDocument != nil { + c.JSON(http.StatusOK, result.DIDDocument) + return + } + if err == nil && result.DIDResolutionMetadata.Error == "deactivated" { + c.JSON(http.StatusGone, gin.H{"error": "DID has been revoked"}) + return + } + } + + // Fall back to did:key resolution via DIDService (in-memory registry) + identity, err := s.didService.ResolveDID(did) + if err != nil { + c.JSON(http.StatusNotFound, gin.H{"error": "DID not found"}) + return + } + + var publicKeyJWK map[string]interface{} + if err := json.Unmarshal([]byte(identity.PublicKeyJWK), &publicKeyJWK); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to parse public key"}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "@context": []string{ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/ed25519-2020/v1", + }, + "id": did, + "verificationMethod": []gin.H{{ + "id": did + "#key-1", + "type": "Ed25519VerificationKey2020", + "controller": did, + "publicKeyJwk": publicKeyJWK, + }}, + "authentication": []string{did + "#key-1"}, + "assertionMethod": []string{did + "#key-1"}, + }) +} + // checkStorageHealth performs storage-specific health checks func (s *AgentFieldServer) checkStorageHealth(ctx context.Context) gin.H { if s.storageHealthOverride != nil { @@ -667,12 +868,35 @@ func (s *AgentFieldServer) setupRoutes() { logger.Logger.Info().Msg("🔐 API key authentication enabled") } + // DID authentication middleware (applied globally, but only validates when headers present) + if s.config.Features.DID.Enabled && s.config.Features.DID.Authorization.DIDAuthEnabled && s.didWebService != nil { + didAuthConfig := middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: s.config.Features.DID.Authorization.TimestampWindowSeconds, + SkipPaths: []string{ + "/health", + "/metrics", + "/api/v1/health", + }, + } + s.Router.Use(middleware.DIDAuthMiddleware(s.didWebService, didAuthConfig)) + logger.Logger.Info().Msg("🆔 DID authentication middleware enabled") + } + // Expose Prometheus metrics s.Router.GET("/metrics", gin.WrapH(promhttp.Handler())) // Public health check endpoint for load balancers and container orchestration (e.g., Railway, K8s) s.Router.GET("/health", s.healthCheckHandler) + // W3C did:web resolution endpoints (spec: https://w3c-ccg.github.io/did-method-web/) + // did:web:{domain} resolves to GET /.well-known/did.json + // did:web:{domain}:agents:{agentID} resolves to GET /agents/{agentID}/did.json + if s.config.Features.DID.Enabled && s.didWebService != nil { + s.Router.GET("/.well-known/did.json", s.handleDIDWebServerDocument) + s.Router.GET("/agents/:agentID/did.json", s.handleDIDWebAgentDocument) + } + // Serve UI files - embedded or filesystem based on availability if s.config.UI.Enabled { // Check if UI is embedded in the binary @@ -898,6 +1122,13 @@ func (s *AgentFieldServer) setupRoutes() { // Identity & Trust endpoints (DID Explorer and Credentials) identityHandler := ui.NewIdentityHandlers(s.storage) identityHandler.RegisterRoutes(uiAPI) + + // Authorization UI endpoints + authorization := uiAPI.Group("/authorization") + { + authorizationHandler := ui.NewAuthorizationHandler(s.storage) + authorization.GET("/agents", authorizationHandler.GetAgentsWithTagsHandler) + } } uiAPIV2 := s.Router.Group("/api/ui/v2") @@ -921,9 +1152,9 @@ func (s *AgentFieldServer) setupRoutes() { } // Node management endpoints - agentAPI.POST("/nodes/register", handlers.RegisterNodeHandler(s.storage, s.uiService, s.didService, s.presenceManager)) - agentAPI.POST("/nodes", handlers.RegisterNodeHandler(s.storage, s.uiService, s.didService, s.presenceManager)) - agentAPI.POST("/nodes/register-serverless", handlers.RegisterServerlessAgentHandler(s.storage, s.uiService, s.didService, s.presenceManager)) + agentAPI.POST("/nodes/register", handlers.RegisterNodeHandler(s.storage, s.uiService, s.didService, s.presenceManager, s.didWebService, s.tagApprovalService)) + agentAPI.POST("/nodes", handlers.RegisterNodeHandler(s.storage, s.uiService, s.didService, s.presenceManager, s.didWebService, s.tagApprovalService)) + agentAPI.POST("/nodes/register-serverless", handlers.RegisterServerlessAgentHandler(s.storage, s.uiService, s.didService, s.presenceManager, s.didWebService)) agentAPI.GET("/nodes", handlers.ListNodesHandler(s.storage)) agentAPI.GET("/nodes/:node_id", handlers.GetNodeHandler(s.storage)) agentAPI.POST("/nodes/:node_id/heartbeat", handlers.HeartbeatHandler(s.storage, s.uiService, s.healthMonitor, s.statusManager, s.presenceManager)) @@ -946,15 +1177,54 @@ func (s *AgentFieldServer) setupRoutes() { // TODO: Add other node routes (DeleteNode) - // Reasoner execution endpoints (legacy) - agentAPI.POST("/reasoners/:reasoner_id", handlers.ExecuteReasonerHandler(s.storage)) - - // Skill execution endpoints (legacy) - agentAPI.POST("/skills/:skill_id", handlers.ExecuteSkillHandler(s.storage)) + // Reasoner and skill execution endpoints (legacy) + // When authorization is enabled, these require the same permission middleware + // as the unified execute endpoints to prevent policy bypass. + if s.config.Features.DID.Authorization.Enabled && s.accessPolicyService != nil && s.didWebService != nil { + legacyReasonerGroup := agentAPI.Group("/reasoners") + legacySkillGroup := agentAPI.Group("/skills") + permConfigLegacy := middleware.PermissionConfig{ + Enabled: true, + } + legacyMiddleware := middleware.PermissionCheckMiddleware( + s.accessPolicyService, + s.tagVCVerifier, + s.storage, + s.didWebService, + permConfigLegacy, + ) + legacyReasonerGroup.Use(legacyMiddleware) + legacySkillGroup.Use(legacyMiddleware) + legacyReasonerGroup.POST("/:reasoner_id", handlers.ExecuteReasonerHandler(s.storage)) + legacySkillGroup.POST("/:skill_id", handlers.ExecuteSkillHandler(s.storage)) + logger.Logger.Info().Msg("🔒 Permission checking enabled on legacy reasoner/skill endpoints") + } else { + agentAPI.POST("/reasoners/:reasoner_id", handlers.ExecuteReasonerHandler(s.storage)) + agentAPI.POST("/skills/:skill_id", handlers.ExecuteSkillHandler(s.storage)) + } // Unified execution endpoints (path-based) - agentAPI.POST("/execute/:target", handlers.ExecuteHandler(s.storage, s.payloadStore, s.webhookDispatcher, s.config.AgentField.ExecutionQueue.AgentCallTimeout)) - agentAPI.POST("/execute/async/:target", handlers.ExecuteAsyncHandler(s.storage, s.payloadStore, s.webhookDispatcher, s.config.AgentField.ExecutionQueue.AgentCallTimeout)) + // These routes may have permission middleware applied if authorization is enabled + executeGroup := agentAPI.Group("/execute") + { + // Apply permission middleware if authorization is enabled + if s.config.Features.DID.Authorization.Enabled && s.accessPolicyService != nil && s.didWebService != nil { + permConfig := middleware.PermissionConfig{ + Enabled: true, + } + executeGroup.Use(middleware.PermissionCheckMiddleware( + s.accessPolicyService, + s.tagVCVerifier, + s.storage, + s.didWebService, + permConfig, + )) + logger.Logger.Info().Msg("🔒 Permission checking enabled on execute endpoints") + } + + executeGroup.POST("/:target", handlers.ExecuteHandler(s.storage, s.payloadStore, s.webhookDispatcher, s.config.AgentField.ExecutionQueue.AgentCallTimeout, s.config.Features.DID.Authorization.InternalToken)) + executeGroup.POST("/async/:target", handlers.ExecuteAsyncHandler(s.storage, s.payloadStore, s.webhookDispatcher, s.config.AgentField.ExecutionQueue.AgentCallTimeout, s.config.Features.DID.Authorization.InternalToken)) + } agentAPI.GET("/executions/:execution_id", handlers.GetExecutionStatusHandler(s.storage)) agentAPI.POST("/executions/batch-status", handlers.BatchExecutionStatusHandler(s.storage)) agentAPI.POST("/executions/:execution_id/status", handlers.UpdateExecutionStatusHandler(s.storage, s.payloadStore, s.webhookDispatcher, s.config.AgentField.ExecutionQueue.AgentCallTimeout)) @@ -1000,6 +1270,9 @@ func (s *AgentFieldServer) setupRoutes() { logger.Logger.Debug().Msg("Registering DID routes - all conditions met") // Create DID handlers instance with services didHandlers := handlers.NewDIDHandlers(s.didService, s.vcService) + if s.didWebService != nil { + didHandlers.SetDIDWebService(s.didWebService) + } // Register service-backed DID routes didHandlers.RegisterRoutes(agentAPI) @@ -1057,6 +1330,153 @@ func (s *AgentFieldServer) setupRoutes() { } // Note: Removed unused/unimplemented DID endpoint placeholders for system simplification + // Agent Tag VC endpoint (for agents to download their own verified tag credential) + if s.tagVCVerifier != nil { + agentAPI.GET("/agents/:agentId/tag-vc", func(c *gin.Context) { + agentID := c.Param("agentId") + if agentID == "" { + c.JSON(http.StatusBadRequest, gin.H{"error": "agent_id is required"}) + return + } + record, err := s.storage.GetAgentTagVC(c.Request.Context(), agentID) + if err != nil { + c.JSON(http.StatusNotFound, gin.H{ + "error": "tag_vc_not_found", + "message": fmt.Sprintf("No tag VC found for agent %s", agentID), + }) + return + } + if record.RevokedAt != nil { + c.JSON(http.StatusGone, gin.H{ + "error": "tag_vc_revoked", + "message": "Agent tag VC has been revoked", + }) + return + } + c.JSON(http.StatusOK, gin.H{ + "agent_id": record.AgentID, + "agent_did": record.AgentDID, + "vc_id": record.VCID, + "vc_document": json.RawMessage(record.VCDocument), + "issued_at": record.IssuedAt, + "expires_at": record.ExpiresAt, + }) + }) + logger.Logger.Info().Msg("🔐 Agent tag VC endpoint registered") + } + + // Decentralized verification endpoints (for SDK local verification) + // Policy distribution endpoint — agents cache these for local policy evaluation + if s.accessPolicyService != nil { + agentAPI.GET("/policies", func(c *gin.Context) { + policies, err := s.accessPolicyService.ListPolicies(c.Request.Context()) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "failed_to_list_policies", + "message": "Failed to list policies", + }) + return + } + c.JSON(http.StatusOK, gin.H{ + "policies": policies, + "total": len(policies), + "fetched_at": time.Now().UTC().Format(time.RFC3339), + }) + }) + logger.Logger.Info().Msg("📋 Policy distribution endpoint registered (GET /api/v1/policies)") + } + + // Revocation list endpoint — agents cache revoked DIDs for local verification + if s.didWebService != nil { + agentAPI.GET("/revocations", func(c *gin.Context) { + docs, err := s.storage.ListDIDDocuments(c.Request.Context()) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "failed_to_list_revocations", + "message": "Failed to list revocations", + }) + return + } + revokedDIDs := make([]string, 0) + for _, doc := range docs { + if doc.IsRevoked() { + revokedDIDs = append(revokedDIDs, doc.DID) + } + } + c.JSON(http.StatusOK, gin.H{ + "revoked_dids": revokedDIDs, + "total": len(revokedDIDs), + "fetched_at": time.Now().UTC().Format(time.RFC3339), + }) + }) + logger.Logger.Info().Msg("🚫 Revocation list endpoint registered (GET /api/v1/revocations)") + } + + // Registered DIDs endpoint — agents cache this set for local verification + // to ensure only known/registered DIDs are accepted on direct calls. + agentAPI.GET("/registered-dids", func(c *gin.Context) { + agentDIDs, err := s.storage.ListAgentDIDs(c.Request.Context()) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "failed_to_list_registered_dids", + "message": "Failed to list registered DIDs", + }) + return + } + registeredDIDs := make([]string, 0, len(agentDIDs)) + for _, info := range agentDIDs { + if info.Status == types.AgentDIDStatusActive { + registeredDIDs = append(registeredDIDs, info.DID) + } + } + c.JSON(http.StatusOK, gin.H{ + "registered_dids": registeredDIDs, + "total": len(registeredDIDs), + "fetched_at": time.Now().UTC().Format(time.RFC3339), + }) + }) + logger.Logger.Info().Msg("✅ Registered DIDs endpoint registered (GET /api/v1/registered-dids)") + + // Issuer public key endpoint — agents use this for offline VC signature verification. + // Registered at /did/issuer-public-key (public, semantic path) and + // /admin/public-key (legacy alias for backward compatibility). + if s.didService != nil { + publicKeyHandler := func(c *gin.Context) { + issuerDID, err := s.didService.GetControlPlaneIssuerDID() + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "issuer_did_unavailable", + "message": "Issuer DID unavailable", + }) + return + } + identity, err := s.didService.ResolveDID(issuerDID) + if err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "public_key_unavailable", + "message": "Public key unavailable", + }) + return + } + var publicKeyJWK map[string]interface{} + if err := json.Unmarshal([]byte(identity.PublicKeyJWK), &publicKeyJWK); err != nil { + c.JSON(http.StatusInternalServerError, gin.H{ + "error": "public_key_parse_error", + "message": "Failed to parse public key JWK", + }) + return + } + c.JSON(http.StatusOK, gin.H{ + "issuer_did": issuerDID, + "public_key_jwk": publicKeyJWK, + "fetched_at": time.Now().UTC().Format(time.RFC3339), + }) + } + agentAPI.GET("/did/issuer-public-key", publicKeyHandler) + agentAPI.GET("/admin/public-key", publicKeyHandler) // legacy alias + logger.Logger.Info().Msg("🔑 Issuer public key endpoint registered (GET /api/v1/did/issuer-public-key)") + } + // Settings API routes (observability webhook configuration) settings := agentAPI.Group("/settings") { @@ -1069,6 +1489,44 @@ func (s *AgentFieldServer) setupRoutes() { settings.GET("/observability-webhook/dlq", obsHandler.GetDeadLetterQueueHandler) settings.DELETE("/observability-webhook/dlq", obsHandler.ClearDeadLetterQueueHandler) } + + // Admin routes for tag approval and access policy management (VC-based authorization) + if s.config.Features.DID.Authorization.Enabled { + adminGroup := agentAPI.Group("") + adminGroup.Use(middleware.AdminTokenAuth(s.config.Features.DID.Authorization.AdminToken)) + + // Tag approval admin routes + if s.tagApprovalService != nil { + tagApprovalHandlers := admin.NewTagApprovalHandlers(s.tagApprovalService, s.storage) + tagApprovalHandlers.RegisterRoutes(adminGroup) + } + + // Access policy admin routes + if s.accessPolicyService != nil { + accessPolicyHandlers := admin.NewAccessPolicyHandlers(s.accessPolicyService) + accessPolicyHandlers.RegisterRoutes(adminGroup) + } + + logger.Logger.Info().Msg("📋 Authorization admin routes registered") + } + + // Connector routes (authenticated with separate connector token) + if s.config.Features.Connector.Enabled && s.config.Features.Connector.Token != "" { + connectorGroup := agentAPI.Group("/connector") + connectorGroup.Use(middleware.ConnectorTokenAuth(s.config.Features.Connector.Token)) + + connectorHandlers := connectorpkg.NewHandlers( + s.config.Features.Connector, + s.storage, + s.statusManager, + s.accessPolicyService, + s.tagApprovalService, + s.didService, + ) + connectorHandlers.RegisterRoutes(connectorGroup) + + logger.Logger.Info().Msg("🔌 Connector routes registered") + } } // SPA fallback - serve index.html for all /ui/* routes that don't match static files diff --git a/control-plane/internal/server/server_routes_test.go b/control-plane/internal/server/server_routes_test.go index dad093e9..825fd7c3 100644 --- a/control-plane/internal/server/server_routes_test.go +++ b/control-plane/internal/server/server_routes_test.go @@ -192,6 +192,12 @@ func (s *stubStorage) GetLockStatus(ctx context.Context, key string) (*types.Dis // Agent registry func (s *stubStorage) RegisterAgent(ctx context.Context, agent *types.AgentNode) error { return nil } +func (s *stubStorage) GetAgentVersion(ctx context.Context, id string, version string) (*types.AgentNode, error) { + return nil, nil +} +func (s *stubStorage) ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) { + return nil, nil +} func (s *stubStorage) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) { return nil, nil } @@ -201,12 +207,27 @@ func (s *stubStorage) UpdateAgentHealth(ctx context.Context, id string, status t func (s *stubStorage) UpdateAgentHealthAtomic(ctx context.Context, id string, status types.HealthStatus, expectedLastHeartbeat *time.Time) error { return nil } -func (s *stubStorage) UpdateAgentHeartbeat(ctx context.Context, id string, heartbeatTime time.Time) error { +func (s *stubStorage) UpdateAgentHeartbeat(ctx context.Context, id string, version string, heartbeatTime time.Time) error { return nil } func (s *stubStorage) UpdateAgentLifecycleStatus(ctx context.Context, id string, status types.AgentLifecycleStatus) error { return nil } +func (s *stubStorage) UpdateAgentVersion(ctx context.Context, id string, version string) error { + return nil +} +func (s *stubStorage) DeleteAgentVersion(ctx context.Context, id string, version string) error { + return nil +} +func (s *stubStorage) UpdateAgentTrafficWeight(ctx context.Context, id string, version string, weight int) error { + return nil +} +func (s *stubStorage) ListAgentsByGroup(ctx context.Context, groupID string) ([]*types.AgentNode, error) { + return nil, nil +} +func (s *stubStorage) ListAgentGroups(ctx context.Context, teamID string) ([]types.AgentGroupSummary, error) { + return nil, nil +} // Configuration func (s *stubStorage) SetConfig(ctx context.Context, key string, value interface{}) error { return nil } @@ -365,6 +386,53 @@ func (s *stubStorage) GetDeadLetterQueue(ctx context.Context, limit, offset int) func (s *stubStorage) DeleteFromDeadLetterQueue(ctx context.Context, ids []int64) error { return nil } func (s *stubStorage) ClearDeadLetterQueue(ctx context.Context) error { return nil } +// DID document operations +func (s *stubStorage) StoreDIDDocument(ctx context.Context, record *types.DIDDocumentRecord) error { + return nil +} +func (s *stubStorage) GetDIDDocument(ctx context.Context, did string) (*types.DIDDocumentRecord, error) { + return nil, nil +} +func (s *stubStorage) GetDIDDocumentByAgentID(ctx context.Context, agentID string) (*types.DIDDocumentRecord, error) { + return nil, nil +} +func (s *stubStorage) RevokeDIDDocument(ctx context.Context, did string) error { return nil } +func (s *stubStorage) ListDIDDocuments(ctx context.Context) ([]*types.DIDDocumentRecord, error) { + return nil, nil +} + +// Agent lifecycle stub +func (s *stubStorage) ListAgentsByLifecycleStatus(ctx context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) { + return nil, nil +} + +// Access policy stubs +func (s *stubStorage) GetAccessPolicies(ctx context.Context) ([]*types.AccessPolicy, error) { + return nil, nil +} +func (s *stubStorage) GetAccessPolicyByID(ctx context.Context, id int64) (*types.AccessPolicy, error) { + return nil, nil +} +func (s *stubStorage) CreateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error { + return nil +} +func (s *stubStorage) UpdateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error { + return nil +} +func (s *stubStorage) DeleteAccessPolicy(ctx context.Context, id int64) error { return nil } + +// Agent Tag VC stubs +func (s *stubStorage) StoreAgentTagVC(ctx context.Context, agentID, agentDID, vcID, vcDocument, signature string, issuedAt time.Time, expiresAt *time.Time) error { + return nil +} +func (s *stubStorage) GetAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCRecord, error) { + return nil, nil +} +func (s *stubStorage) RevokeAgentTagVC(ctx context.Context, agentID string) error { return nil } +func (s *stubStorage) ListAgentTagVCs(ctx context.Context) ([]*types.AgentTagVCRecord, error) { + return nil, nil +} + // stubPayloadStore implements services.PayloadStore type stubPayloadStore struct{} diff --git a/control-plane/internal/services/access_policy_service.go b/control-plane/internal/services/access_policy_service.go new file mode 100644 index 00000000..73fd415a --- /dev/null +++ b/control-plane/internal/services/access_policy_service.go @@ -0,0 +1,424 @@ +package services + +import ( + "context" + "encoding/json" + "fmt" + "sort" + "strings" + "sync" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" +) + +// AccessPolicyStorage defines the storage interface subset for access policies. +type AccessPolicyStorage interface { + GetAccessPolicies(ctx context.Context) ([]*types.AccessPolicy, error) + GetAccessPolicyByID(ctx context.Context, id int64) (*types.AccessPolicy, error) + CreateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error + UpdateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error + DeleteAccessPolicy(ctx context.Context, id int64) error +} + +// AccessPolicyService handles tag-based access policy evaluation and management. +type AccessPolicyService struct { + storage AccessPolicyStorage + mu sync.RWMutex + policies []*types.AccessPolicy // in-memory cache, sorted by priority desc +} + +// NewAccessPolicyService creates a new access policy service instance. +func NewAccessPolicyService(storage AccessPolicyStorage) *AccessPolicyService { + return &AccessPolicyService{ + storage: storage, + policies: make([]*types.AccessPolicy, 0), + } +} + +// Initialize loads access policies from storage into memory. +func (s *AccessPolicyService) Initialize(ctx context.Context) error { + policies, err := s.storage.GetAccessPolicies(ctx) + if err != nil { + return fmt.Errorf("failed to load access policies: %w", err) + } + + // Sort by priority descending (highest first), stable to ensure deterministic ordering + sort.SliceStable(policies, func(i, j int) bool { + if policies[i].Priority != policies[j].Priority { + return policies[i].Priority > policies[j].Priority + } + return policies[i].ID < policies[j].ID // tie-break by ID for determinism + }) + + s.mu.Lock() + s.policies = policies + s.mu.Unlock() + + logger.Logger.Info(). + Int("policies_count", len(policies)). + Msg("Loaded access policies") + + return nil +} + +// EvaluateAccess evaluates access policies for a cross-agent call. +// Returns a PolicyEvaluationResult indicating whether access is allowed, denied, or no policy matched. +func (s *AccessPolicyService) EvaluateAccess( + callerTags, targetTags []string, + functionName string, + inputParams map[string]any, +) *types.PolicyEvaluationResult { + s.mu.RLock() + policies := s.policies + s.mu.RUnlock() + + // Normalize tags for comparison + normalizedCallerTags := normalizeTags(callerTags) + normalizedTargetTags := normalizeTags(targetTags) + + for _, policy := range policies { + if !policy.Enabled { + continue + } + + // 1. Check caller tag intersection + if !tagsIntersect(policy.CallerTags, normalizedCallerTags) { + continue + } + + // 2. Check target tag intersection + if !tagsIntersect(policy.TargetTags, normalizedTargetTags) { + continue + } + + // 3. Check function against deny list first (deny takes precedence) + if len(policy.DenyFunctions) > 0 { + if functionName != "" && functionMatchesAny(functionName, policy.DenyFunctions) { + return &types.PolicyEvaluationResult{ + Allowed: false, + Matched: true, + PolicyName: policy.Name, + PolicyID: policy.ID, + Reason: fmt.Sprintf("Function %q is denied by policy %q", functionName, policy.Name), + } + } + } + + // 4. Check function against allow list — if allow list is set but function name + // is empty or not in the list, this policy doesn't match (fail closed) + if len(policy.AllowFunctions) > 0 { + if functionName == "" || !functionMatchesAny(functionName, policy.AllowFunctions) { + continue // Function not in allow list, try next policy + } + } + + // 5. Evaluate constraints — fail closed when constraints exist but inputParams is nil + if len(policy.Constraints) > 0 { + if inputParams == nil { + return &types.PolicyEvaluationResult{ + Allowed: false, + Matched: true, + PolicyName: policy.Name, + PolicyID: policy.ID, + Reason: fmt.Sprintf("Policy %q requires parameter constraints but no input parameters provided", policy.Name), + } + } + constraintViolation := evaluateConstraints(policy.Constraints, inputParams) + if constraintViolation != "" { + return &types.PolicyEvaluationResult{ + Allowed: false, + Matched: true, + PolicyName: policy.Name, + PolicyID: policy.ID, + Reason: constraintViolation, + } + } + } + + // All checks passed — policy matches + allowed := strings.ToLower(policy.Action) == "allow" + reason := fmt.Sprintf("Policy %q matched: action=%s", policy.Name, policy.Action) + if !allowed { + reason = fmt.Sprintf("Policy %q explicitly denies access", policy.Name) + } + + return &types.PolicyEvaluationResult{ + Allowed: allowed, + Matched: true, + PolicyName: policy.Name, + PolicyID: policy.ID, + Reason: reason, + } + } + + // No policy matched + return &types.PolicyEvaluationResult{ + Matched: false, + Reason: "No access policy matched", + } +} + +// validConstraintOperators defines the allowed constraint operator set. +var validConstraintOperators = map[string]bool{ + "<=": true, ">=": true, "==": true, "!=": true, "<": true, ">": true, +} + +// validatePolicyRequest validates policy fields before creation/update. +func validatePolicyRequest(req *types.AccessPolicyRequest) error { + action := strings.ToLower(strings.TrimSpace(req.Action)) + if action != "allow" && action != "deny" { + return fmt.Errorf("invalid policy action %q: must be 'allow' or 'deny'", req.Action) + } + req.Action = action // normalize + + for paramName, constraint := range req.Constraints { + if !validConstraintOperators[constraint.Operator] { + return fmt.Errorf("invalid constraint operator %q for parameter %q: must be one of <=, >=, ==, !=, <, >", constraint.Operator, paramName) + } + } + return nil +} + +// AddPolicy creates a new access policy and refreshes the cache. +func (s *AccessPolicyService) AddPolicy(ctx context.Context, req *types.AccessPolicyRequest) (*types.AccessPolicy, error) { + if err := validatePolicyRequest(req); err != nil { + return nil, err + } + + now := time.Now() + policy := &types.AccessPolicy{ + Name: req.Name, + CallerTags: req.CallerTags, + TargetTags: req.TargetTags, + AllowFunctions: req.AllowFunctions, + DenyFunctions: req.DenyFunctions, + Constraints: req.Constraints, + Action: req.Action, + Priority: req.Priority, + Enabled: true, + CreatedAt: now, + UpdatedAt: now, + } + if req.Description != "" { + policy.Description = &req.Description + } + + if err := s.storage.CreateAccessPolicy(ctx, policy); err != nil { + return nil, fmt.Errorf("failed to create access policy: %w", err) + } + + // Reload cache — propagate failure so caller knows enforcement may be stale + if err := s.Initialize(ctx); err != nil { + logger.Logger.Error().Err(err).Msg("Failed to reload policies after adding new policy — cache may be stale") + return policy, fmt.Errorf("policy created but cache reload failed: %w", err) + } + + return policy, nil +} + +// UpdatePolicy updates an existing access policy and refreshes the cache. +func (s *AccessPolicyService) UpdatePolicy(ctx context.Context, id int64, req *types.AccessPolicyRequest) (*types.AccessPolicy, error) { + if err := validatePolicyRequest(req); err != nil { + return nil, err + } + + policy, err := s.storage.GetAccessPolicyByID(ctx, id) + if err != nil { + return nil, fmt.Errorf("access policy not found: %w", err) + } + + policy.Name = req.Name + policy.CallerTags = req.CallerTags + policy.TargetTags = req.TargetTags + policy.AllowFunctions = req.AllowFunctions + policy.DenyFunctions = req.DenyFunctions + policy.Constraints = req.Constraints + policy.Action = req.Action + policy.Priority = req.Priority + policy.UpdatedAt = time.Now() + if req.Description != "" { + policy.Description = &req.Description + } + + if err := s.storage.UpdateAccessPolicy(ctx, policy); err != nil { + return nil, fmt.Errorf("failed to update access policy: %w", err) + } + + // Reload cache — propagate failure so caller knows enforcement may be stale + if err := s.Initialize(ctx); err != nil { + logger.Logger.Error().Err(err).Msg("Failed to reload policies after updating policy — cache may be stale") + return policy, fmt.Errorf("policy updated but cache reload failed: %w", err) + } + + return policy, nil +} + +// RemovePolicy deletes an access policy and refreshes the cache. +func (s *AccessPolicyService) RemovePolicy(ctx context.Context, id int64) error { + if err := s.storage.DeleteAccessPolicy(ctx, id); err != nil { + return fmt.Errorf("failed to delete access policy: %w", err) + } + + // Reload cache — propagate failure so caller knows enforcement may be stale + if err := s.Initialize(ctx); err != nil { + logger.Logger.Error().Err(err).Msg("Failed to reload policies after removing policy — cache may be stale") + return fmt.Errorf("policy deleted but cache reload failed: %w", err) + } + + return nil +} + +// ListPolicies returns all access policies from storage. +func (s *AccessPolicyService) ListPolicies(ctx context.Context) ([]*types.AccessPolicy, error) { + return s.storage.GetAccessPolicies(ctx) +} + +// GetPolicyByID returns a single access policy by ID. +func (s *AccessPolicyService) GetPolicyByID(ctx context.Context, id int64) (*types.AccessPolicy, error) { + return s.storage.GetAccessPolicyByID(ctx, id) +} + +// ============================================================================ +// Internal helpers +// ============================================================================ + +// normalizeTags lowercases and trims all tags. +func normalizeTags(tags []string) []string { + normalized := make([]string, 0, len(tags)) + for _, tag := range tags { + if t := normalizeTag(tag); t != "" { + normalized = append(normalized, t) + } + } + return normalized +} + +// tagsIntersect returns true if at least one policy tag matches at least one agent tag. +// Empty policy tags are treated as wildcard (match any agent tags). +// Policy tags support wildcards via matchesPattern. +func tagsIntersect(policyTags, agentTags []string) bool { + if len(policyTags) == 0 { + return true // empty policy tags = wildcard, matches any agent + } + for _, pt := range policyTags { + normalizedPT := normalizeTag(pt) + for _, at := range agentTags { + if matchesPattern(normalizedPT, at) { + return true + } + } + } + return false +} + +// functionMatchesAny returns true if the function name matches any of the patterns. +func functionMatchesAny(functionName string, patterns []string) bool { + normalized := strings.ToLower(strings.TrimSpace(functionName)) + for _, pattern := range patterns { + if matchesPattern(strings.ToLower(strings.TrimSpace(pattern)), normalized) { + return true + } + } + return false +} + +// evaluateConstraints checks all constraints against input parameters. +// Returns empty string if all pass, or a violation description if any fail. +func evaluateConstraints(constraints map[string]types.AccessConstraint, inputParams map[string]any) string { + for paramName, constraint := range constraints { + paramValue, exists := inputParams[paramName] + if !exists { + // Fail closed: constraint references a parameter not in input + return fmt.Sprintf("Constraint violation: parameter %q not found in input", paramName) + } + + if !evaluateConstraint(paramValue, constraint) { + return fmt.Sprintf("Constraint violation: %s %s %v (actual: %v)", + paramName, constraint.Operator, constraint.Value, paramValue) + } + } + return "" +} + +// evaluateConstraint checks a single parameter value against a constraint. +func evaluateConstraint(paramValue any, constraint types.AccessConstraint) bool { + // Try numeric comparison + paramNum, paramOK := toFloat64(paramValue) + constraintNum, constraintOK := toFloat64(constraint.Value) + + if paramOK && constraintOK { + switch constraint.Operator { + case "<=": + return paramNum <= constraintNum + case ">=": + return paramNum >= constraintNum + case "<": + return paramNum < constraintNum + case ">": + return paramNum > constraintNum + case "==": + return paramNum == constraintNum + case "!=": + return paramNum != constraintNum + } + } + + // Fall back to string comparison for == and != + paramStr := fmt.Sprintf("%v", paramValue) + constraintStr := fmt.Sprintf("%v", constraint.Value) + + switch constraint.Operator { + case "==": + return paramStr == constraintStr + case "!=": + return paramStr != constraintStr + } + + // Unsupported operator for non-numeric types — fail closed + return false +} + +// toFloat64 attempts to convert a value to float64. +func toFloat64(v any) (float64, bool) { + switch n := v.(type) { + case float64: + return n, true + case float32: + return float64(n), true + case int: + return float64(n), true + case int64: + return float64(n), true + case int32: + return float64(n), true + case json.Number: + f, err := n.Float64() + return f, err == nil + case string: + // Don't parse strings as numbers + return 0, false + default: + return 0, false + } +} + +// matchesPattern checks if a value matches a pattern (supports wildcards). +func matchesPattern(pattern, value string) bool { + if pattern == value { + return true + } + if pattern == "*" { + return true + } + if strings.HasSuffix(pattern, "*") { + prefix := strings.TrimSuffix(pattern, "*") + return strings.HasPrefix(value, prefix) + } + if strings.HasPrefix(pattern, "*") { + suffix := strings.TrimPrefix(pattern, "*") + return strings.HasSuffix(value, suffix) + } + return false +} diff --git a/control-plane/internal/services/access_policy_service_test.go b/control-plane/internal/services/access_policy_service_test.go new file mode 100644 index 00000000..bbc3ddb8 --- /dev/null +++ b/control-plane/internal/services/access_policy_service_test.go @@ -0,0 +1,628 @@ +package services + +import ( + "context" + "fmt" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mockAccessPolicyStorage is an in-memory mock for AccessPolicyStorage. +type mockAccessPolicyStorage struct { + policies []*types.AccessPolicy + nextID int64 + createErr error + getErr error +} + +func (m *mockAccessPolicyStorage) GetAccessPolicies(_ context.Context) ([]*types.AccessPolicy, error) { + if m.getErr != nil { + return nil, m.getErr + } + // Return copies to prevent test mutation + result := make([]*types.AccessPolicy, len(m.policies)) + copy(result, m.policies) + return result, nil +} + +func (m *mockAccessPolicyStorage) GetAccessPolicyByID(_ context.Context, id int64) (*types.AccessPolicy, error) { + for _, p := range m.policies { + if p.ID == id { + return p, nil + } + } + return nil, fmt.Errorf("policy %d not found", id) +} + +func (m *mockAccessPolicyStorage) CreateAccessPolicy(_ context.Context, policy *types.AccessPolicy) error { + if m.createErr != nil { + return m.createErr + } + m.nextID++ + policy.ID = m.nextID + m.policies = append(m.policies, policy) + return nil +} + +func (m *mockAccessPolicyStorage) UpdateAccessPolicy(_ context.Context, policy *types.AccessPolicy) error { + for i, p := range m.policies { + if p.ID == policy.ID { + m.policies[i] = policy + return nil + } + } + return fmt.Errorf("policy %d not found", policy.ID) +} + +func (m *mockAccessPolicyStorage) DeleteAccessPolicy(_ context.Context, id int64) error { + for i, p := range m.policies { + if p.ID == id { + m.policies = append(m.policies[:i], m.policies[i+1:]...) + return nil + } + } + return fmt.Errorf("policy %d not found", id) +} + +func newTestPolicy(id int64, name string, callerTags, targetTags []string, action string, priority int) *types.AccessPolicy { + return &types.AccessPolicy{ + ID: id, + Name: name, + CallerTags: callerTags, + TargetTags: targetTags, + Action: action, + Priority: priority, + Enabled: true, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } +} + +// ============================================================================ +// EvaluateAccess — core policy evaluation +// ============================================================================ + +func TestEvaluateAccess_NoMatchReturnsNotMatched(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "finance_to_billing", []string{"finance"}, []string{"billing"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"support"}, []string{"billing"}, "get_balance", nil) + assert.False(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "No access policy matched") +} + +func TestEvaluateAccess_SimpleAllow(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "finance_to_billing", []string{"finance"}, []string{"billing"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + assert.Equal(t, "finance_to_billing", result.PolicyName) + assert.Equal(t, int64(1), result.PolicyID) +} + +func TestEvaluateAccess_SimpleDeny(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "block_support", []string{"support"}, []string{"admin"}, "deny", 10), + } + + result := svc.EvaluateAccess([]string{"support"}, []string{"admin"}, "delete_user", nil) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "explicitly denies") +} + +func TestEvaluateAccess_DisabledPolicySkipped(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "disabled_policy", []string{"finance"}, []string{"billing"}, "allow", 10) + policy.Enabled = false + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", nil) + assert.False(t, result.Matched) +} + +func TestEvaluateAccess_PriorityOrdering(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "high_priority_deny", []string{"finance"}, []string{"billing"}, "deny", 100), + newTestPolicy(2, "low_priority_allow", []string{"finance"}, []string{"billing"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", nil) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Equal(t, "high_priority_deny", result.PolicyName) +} + +func TestEvaluateAccess_EmptyCallerTagsWildcard(t *testing.T) { + // Empty caller_tags on a policy means "match any caller" + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "any_to_public", []string{}, []string{"public"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"random-tag"}, []string{"public"}, "get", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) +} + +func TestEvaluateAccess_EmptyTargetTagsWildcard(t *testing.T) { + // Empty target_tags on a policy means "match any target" + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "admin_to_any", []string{"admin"}, []string{}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"admin"}, []string{"whatever"}, "anything", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) +} + +func TestEvaluateAccess_TagsAreCaseInsensitive(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "case_test", []string{"Finance"}, []string{"Billing"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"FINANCE"}, []string{"billing"}, "charge", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) +} + +// ============================================================================ +// Function allow/deny lists +// ============================================================================ + +func TestEvaluateAccess_AllowFunctionList(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "allow_specific", []string{"finance"}, []string{"billing"}, "allow", 10) + policy.AllowFunctions = []string{"charge_*", "get_*"} + svc.policies = []*types.AccessPolicy{policy} + + t.Run("allowed function matches prefix", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge_customer", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + }) + + t.Run("disallowed function skips policy", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "delete_account", nil) + assert.False(t, result.Matched) // Policy doesn't match, falls through + }) + + t.Run("empty function name skips policy with allow list", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "", nil) + assert.False(t, result.Matched) + }) +} + +func TestEvaluateAccess_DenyFunctionList(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "deny_specific", []string{"finance"}, []string{"billing"}, "allow", 10) + policy.DenyFunctions = []string{"delete_*", "admin_*"} + svc.policies = []*types.AccessPolicy{policy} + + t.Run("denied function is blocked", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "delete_user", nil) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "denied") + }) + + t.Run("non-denied function allowed", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge_customer", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + }) +} + +func TestEvaluateAccess_DenyTakesPrecedenceOverAllow(t *testing.T) { + // A function in both allow and deny lists should be denied + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "mixed", []string{"finance"}, []string{"billing"}, "allow", 10) + policy.AllowFunctions = []string{"*"} + policy.DenyFunctions = []string{"delete_*"} + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "delete_user", nil) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) +} + +// ============================================================================ +// Constraint evaluation +// ============================================================================ + +func TestEvaluateAccess_NumericConstraints(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "constrained", []string{"finance"}, []string{"billing"}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "amount": {Operator: "<=", Value: float64(10000)}, + } + svc.policies = []*types.AccessPolicy{policy} + + t.Run("within limit", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", + map[string]any{"amount": float64(5000)}) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + }) + + t.Run("at limit", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", + map[string]any{"amount": float64(10000)}) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + }) + + t.Run("over limit", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", + map[string]any{"amount": float64(15000)}) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "Constraint violation") + }) +} + +func TestEvaluateAccess_AllNumericOperators(t *testing.T) { + tests := []struct { + operator string + value float64 + param float64 + expect bool + }{ + {"<=", 100, 50, true}, + {"<=", 100, 100, true}, + {"<=", 100, 101, false}, + {">=", 100, 150, true}, + {">=", 100, 100, true}, + {">=", 100, 99, false}, + {"<", 100, 99, true}, + {"<", 100, 100, false}, + {">", 100, 101, true}, + {">", 100, 100, false}, + {"==", 100, 100, true}, + {"==", 100, 99, false}, + {"!=", 100, 99, true}, + {"!=", 100, 100, false}, + } + + for _, tc := range tests { + t.Run(fmt.Sprintf("%v%s%v", tc.param, tc.operator, tc.value), func(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "op_test", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "val": {Operator: tc.operator, Value: tc.value}, + } + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"val": tc.param}) + assert.Equal(t, tc.expect, result.Allowed, + "expected %v %s %v = %v", tc.param, tc.operator, tc.value, tc.expect) + }) + } +} + +func TestEvaluateAccess_StringEqualityConstraints(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "string_test", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "region": {Operator: "==", Value: "us-east"}, + } + svc.policies = []*types.AccessPolicy{policy} + + t.Run("matching string", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"region": "us-east"}) + assert.True(t, result.Allowed) + }) + + t.Run("non-matching string", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"region": "eu-west"}) + assert.False(t, result.Allowed) + }) +} + +func TestEvaluateAccess_MissingParameterFailsClosed(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "constrained", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "amount": {Operator: "<=", Value: float64(10000)}, + } + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"other_param": float64(5000)}) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "not found in input") +} + +func TestEvaluateAccess_NilInputParamsFailsClosed(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "constrained", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "amount": {Operator: "<=", Value: float64(10000)}, + } + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", nil) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) + assert.Contains(t, result.Reason, "no input parameters provided") +} + +func TestEvaluateAccess_IntegerParameterConversion(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "int_test", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "count": {Operator: "<=", Value: float64(10)}, + } + svc.policies = []*types.AccessPolicy{policy} + + // Go int, int32, int64 should all convert to float64 for comparison + for _, val := range []any{int(5), int32(5), int64(5), float32(5)} { + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"count": val}) + assert.True(t, result.Allowed, "should accept %T(%v)", val, val) + } +} + +func TestEvaluateAccess_NonNumericWithOrderingOperatorFailsClosed(t *testing.T) { + // Strings with < or > operators should fail closed (not comparable) + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + policy := newTestPolicy(1, "fail_closed_test", []string{}, []string{}, "allow", 10) + policy.Constraints = map[string]types.AccessConstraint{ + "name": {Operator: "<=", Value: "some_string"}, + } + svc.policies = []*types.AccessPolicy{policy} + + result := svc.EvaluateAccess([]string{"any"}, []string{"any"}, "fn", + map[string]any{"name": "other_string"}) + assert.True(t, result.Matched) + assert.False(t, result.Allowed) +} + +// ============================================================================ +// Tag wildcard patterns +// ============================================================================ + +func TestEvaluateAccess_WildcardTagPattern(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "fin_wildcard", []string{"fin*"}, []string{"billing"}, "allow", 10), + } + + t.Run("matches prefix", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "charge", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) + }) + + t.Run("doesn't match different prefix", func(t *testing.T) { + result := svc.EvaluateAccess([]string{"support"}, []string{"billing"}, "charge", nil) + assert.False(t, result.Matched) + }) +} + +func TestEvaluateAccess_StarWildcardMatchesAll(t *testing.T) { + svc := NewAccessPolicyService(&mockAccessPolicyStorage{}) + svc.policies = []*types.AccessPolicy{ + newTestPolicy(1, "star_wildcard", []string{"*"}, []string{"*"}, "allow", 10), + } + + result := svc.EvaluateAccess([]string{"anything"}, []string{"whatever"}, "fn", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) +} + +// ============================================================================ +// Initialize — loading and sorting +// ============================================================================ + +func TestInitialize_SortsByPriorityDescThenIDDesc(t *testing.T) { + storage := &mockAccessPolicyStorage{ + policies: []*types.AccessPolicy{ + newTestPolicy(3, "low", []string{"a"}, []string{"a"}, "allow", 1), + newTestPolicy(1, "high", []string{"a"}, []string{"a"}, "deny", 100), + newTestPolicy(2, "medium", []string{"a"}, []string{"a"}, "allow", 50), + }, + } + svc := NewAccessPolicyService(storage) + err := svc.Initialize(context.Background()) + require.NoError(t, err) + + // Verify policies are sorted: high(100), medium(50), low(1) + assert.Equal(t, "high", svc.policies[0].Name) + assert.Equal(t, "medium", svc.policies[1].Name) + assert.Equal(t, "low", svc.policies[2].Name) +} + +func TestInitialize_SamePriorityDeterministicByID(t *testing.T) { + storage := &mockAccessPolicyStorage{ + policies: []*types.AccessPolicy{ + newTestPolicy(5, "later", []string{}, []string{}, "deny", 10), + newTestPolicy(2, "earlier", []string{}, []string{}, "allow", 10), + }, + } + svc := NewAccessPolicyService(storage) + err := svc.Initialize(context.Background()) + require.NoError(t, err) + + // Same priority → lower ID first (stable, deterministic) + assert.Equal(t, "earlier", svc.policies[0].Name) + assert.Equal(t, "later", svc.policies[1].Name) +} + +func TestInitialize_StorageError(t *testing.T) { + storage := &mockAccessPolicyStorage{getErr: fmt.Errorf("db down")} + svc := NewAccessPolicyService(storage) + err := svc.Initialize(context.Background()) + assert.Error(t, err) + assert.Contains(t, err.Error(), "failed to load access policies") +} + +// ============================================================================ +// AddPolicy / UpdatePolicy / RemovePolicy — CRUD with cache refresh +// ============================================================================ + +func TestAddPolicy_ValidatesAction(t *testing.T) { + storage := &mockAccessPolicyStorage{} + svc := NewAccessPolicyService(storage) + + _, err := svc.AddPolicy(context.Background(), &types.AccessPolicyRequest{ + Name: "bad", + CallerTags: []string{"a"}, + TargetTags: []string{"b"}, + Action: "maybe", + }) + assert.Error(t, err) + assert.Contains(t, err.Error(), "invalid policy action") +} + +func TestAddPolicy_ValidatesConstraintOperator(t *testing.T) { + storage := &mockAccessPolicyStorage{} + svc := NewAccessPolicyService(storage) + + _, err := svc.AddPolicy(context.Background(), &types.AccessPolicyRequest{ + Name: "bad_op", + CallerTags: []string{"a"}, + TargetTags: []string{"b"}, + Action: "allow", + Constraints: map[string]types.AccessConstraint{ + "amount": {Operator: "~=", Value: 100}, + }, + }) + assert.Error(t, err) + assert.Contains(t, err.Error(), "invalid constraint operator") +} + +func TestAddPolicy_SuccessAndCacheRefresh(t *testing.T) { + storage := &mockAccessPolicyStorage{} + svc := NewAccessPolicyService(storage) + + policy, err := svc.AddPolicy(context.Background(), &types.AccessPolicyRequest{ + Name: "test_policy", + CallerTags: []string{"finance"}, + TargetTags: []string{"billing"}, + Action: "allow", + Priority: 10, + }) + require.NoError(t, err) + assert.Equal(t, "test_policy", policy.Name) + assert.True(t, policy.Enabled) + + // Verify the cache was refreshed (policy is now in the in-memory list) + result := svc.EvaluateAccess([]string{"finance"}, []string{"billing"}, "fn", nil) + assert.True(t, result.Matched) + assert.True(t, result.Allowed) +} + +func TestRemovePolicy_RemovesFromCacheAndStorage(t *testing.T) { + storage := &mockAccessPolicyStorage{ + policies: []*types.AccessPolicy{ + newTestPolicy(1, "to_remove", []string{"a"}, []string{"b"}, "allow", 10), + }, + } + svc := NewAccessPolicyService(storage) + require.NoError(t, svc.Initialize(context.Background())) + + // Verify it exists + result := svc.EvaluateAccess([]string{"a"}, []string{"b"}, "fn", nil) + assert.True(t, result.Matched) + + // Remove + err := svc.RemovePolicy(context.Background(), 1) + require.NoError(t, err) + + // Verify it's gone + result = svc.EvaluateAccess([]string{"a"}, []string{"b"}, "fn", nil) + assert.False(t, result.Matched) +} + +// ============================================================================ +// Internal helpers +// ============================================================================ + +func TestToFloat64_VariousTypes(t *testing.T) { + tests := []struct { + input any + expected float64 + ok bool + }{ + {float64(42), 42, true}, + {float32(42), 42, true}, + {int(42), 42, true}, + {int64(42), 42, true}, + {int32(42), 42, true}, + {"not a number", 0, false}, + {true, 0, false}, + {nil, 0, false}, + } + + for _, tc := range tests { + t.Run(fmt.Sprintf("%T(%v)", tc.input, tc.input), func(t *testing.T) { + val, ok := toFloat64(tc.input) + assert.Equal(t, tc.ok, ok) + if ok { + assert.Equal(t, tc.expected, val) + } + }) + } +} + +func TestFunctionMatchesAny_Patterns(t *testing.T) { + tests := []struct { + fn string + patterns []string + expect bool + }{ + {"charge_customer", []string{"charge_*"}, true}, + {"get_balance", []string{"get_*", "query_*"}, true}, + {"delete_user", []string{"get_*", "query_*"}, false}, + {"any_function", []string{"*"}, true}, + {"charge_customer", []string{"charge_customer"}, true}, + {"CHARGE_CUSTOMER", []string{"charge_customer"}, true}, // case insensitive + } + + for _, tc := range tests { + t.Run(tc.fn, func(t *testing.T) { + assert.Equal(t, tc.expect, functionMatchesAny(tc.fn, tc.patterns)) + }) + } +} + +func TestTagsIntersect(t *testing.T) { + tests := []struct { + name string + policyTags []string + agentTags []string + expect bool + }{ + {"empty policy tags = wildcard", nil, []string{"anything"}, true}, + {"exact match", []string{"finance"}, []string{"finance", "internal"}, true}, + {"no match", []string{"admin"}, []string{"finance", "internal"}, false}, + {"wildcard pattern", []string{"fin*"}, []string{"finance"}, true}, + {"star matches all", []string{"*"}, []string{"finance"}, true}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, tc.expect, tagsIntersect(tc.policyTags, tc.agentTags)) + }) + } +} diff --git a/control-plane/internal/services/did_registry.go b/control-plane/internal/services/did_registry.go index 2a5e2fd3..e3adcff1 100644 --- a/control-plane/internal/services/did_registry.go +++ b/control-plane/internal/services/did_registry.go @@ -6,15 +6,17 @@ import ( "log" "sync" + "github.com/Agent-Field/agentfield/control-plane/internal/encryption" "github.com/Agent-Field/agentfield/control-plane/internal/storage" "github.com/Agent-Field/agentfield/control-plane/pkg/types" ) // DIDRegistry manages the storage and retrieval of DID registries using database-only operations. type DIDRegistry struct { - mu sync.RWMutex - registries map[string]*types.DIDRegistry - storageProvider storage.StorageProvider + mu sync.RWMutex + registries map[string]*types.DIDRegistry + storageProvider storage.StorageProvider + encryptionService *encryption.EncryptionService } // NewDIDRegistryWithStorage creates a new DID registry instance with database storage. @@ -25,6 +27,11 @@ func NewDIDRegistryWithStorage(storageProvider storage.StorageProvider) *DIDRegi } } +// SetEncryptionService sets the encryption service for encrypting master seeds at rest. +func (r *DIDRegistry) SetEncryptionService(svc *encryption.EncryptionService) { + r.encryptionService = svc +} + // Initialize initializes the DID registry storage. func (r *DIDRegistry) Initialize() error { if r.storageProvider == nil { @@ -228,10 +235,25 @@ func (r *DIDRegistry) loadRegistriesFromDatabase() error { // Create registries for each af server for _, agentfieldServerDIDInfo := range agentfieldServerDIDs { + // Decrypt master seed if encryption is configured + masterSeed := agentfieldServerDIDInfo.MasterSeed + if r.encryptionService != nil { + decrypted, err := r.encryptionService.DecryptBytes(masterSeed) + if err != nil { + // Backward compatibility: if decryption fails, the seed may be stored + // as plaintext from before encryption was configured. Use it as-is and + // it will be encrypted on the next save. + log.Printf("Warning: master seed decryption failed for %s (may be plaintext from before encryption was enabled), using raw bytes", + agentfieldServerDIDInfo.AgentFieldServerID) + decrypted = masterSeed + } + masterSeed = decrypted + } + registry := &types.DIDRegistry{ AgentFieldServerID: agentfieldServerDIDInfo.AgentFieldServerID, RootDID: agentfieldServerDIDInfo.RootDID, - MasterSeed: agentfieldServerDIDInfo.MasterSeed, + MasterSeed: masterSeed, AgentNodes: make(map[string]types.AgentDIDInfo), TotalDIDs: 0, CreatedAt: agentfieldServerDIDInfo.CreatedAt, @@ -310,12 +332,23 @@ func (r *DIDRegistry) saveRegistryToDatabase(registry *types.DIDRegistry) error } ctx := context.Background() + + // Encrypt master seed before storing if encryption is configured + seedToStore := registry.MasterSeed + if r.encryptionService != nil { + encrypted, err := r.encryptionService.EncryptBytes(registry.MasterSeed) + if err != nil { + return fmt.Errorf("failed to encrypt master seed: %w", err) + } + seedToStore = encrypted + } + // Store af server DID information err := r.storageProvider.StoreAgentFieldServerDID( ctx, registry.AgentFieldServerID, registry.RootDID, - registry.MasterSeed, + seedToStore, registry.CreatedAt, registry.LastKeyRotation, ) diff --git a/control-plane/internal/services/did_service.go b/control-plane/internal/services/did_service.go index 66c0ff50..1135e09a 100644 --- a/control-plane/internal/services/did_service.go +++ b/control-plane/internal/services/did_service.go @@ -9,12 +9,14 @@ import ( "encoding/json" "fmt" "hash/fnv" + "io" "time" "github.com/Agent-Field/agentfield/control-plane/internal/config" "github.com/Agent-Field/agentfield/control-plane/internal/logger" "github.com/Agent-Field/agentfield/control-plane/internal/storage" "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "golang.org/x/crypto/hkdf" ) // DIDService handles DID generation, management, and resolution. @@ -97,6 +99,27 @@ func (s *DIDService) getAgentFieldServerID() (string, error) { return s.GetAgentFieldServerID() } +// GetControlPlaneIssuerDID returns the root DID (did:key format) for the +// control plane, suitable for signing VCs. This DID is resolvable via +// ResolveDID(), unlike the did:web URI returned by GenerateDIDWeb(). +func (s *DIDService) GetControlPlaneIssuerDID() (string, error) { + if !s.config.Enabled { + return "", fmt.Errorf("DID system is disabled") + } + agentfieldServerID, err := s.getAgentFieldServerID() + if err != nil { + return "", err + } + registry, err := s.registry.GetRegistry(agentfieldServerID) + if err != nil { + return "", fmt.Errorf("failed to get DID registry: %w", err) + } + if registry.RootDID == "" { + return "", fmt.Errorf("root DID not initialized") + } + return registry.RootDID, nil +} + // validateAgentFieldServerRegistry ensures that the af server registry exists before operations. func (s *DIDService) validateAgentFieldServerRegistry() error { agentfieldServerID, err := s.getAgentFieldServerID() @@ -472,6 +495,28 @@ func (s *DIDService) ResolveDID(did string) (*types.DIDIdentity, error) { return nil, fmt.Errorf("DID not found: %s", did) } +// ResolveAgentIDByDID looks up the agent node ID for any DID (including did:key) +// by searching the in-memory DID registry. Returns empty string if not found. +func (s *DIDService) ResolveAgentIDByDID(did string) string { + if !s.config.Enabled { + return "" + } + agentfieldServerID, err := s.getAgentFieldServerID() + if err != nil { + return "" + } + registry, err := s.registry.GetRegistry(agentfieldServerID) + if err != nil { + return "" + } + for _, agentInfo := range registry.AgentNodes { + if agentInfo.DID == did { + return agentInfo.AgentNodeID + } + } + return "" +} + // generateDIDWithKeys generates a DID with private and public keys from master seed and derivation path. func (s *DIDService) generateDIDWithKeys(masterSeed []byte, derivationPath string) (string, string, string, error) { // Derive private key using simplified BIP32-style derivation @@ -511,15 +556,19 @@ func (s *DIDService) generateDIDFromSeed(masterSeed []byte, derivationPath strin return s.generateDIDKey(publicKey), nil } -// derivePrivateKey derives a private key from master seed using simplified BIP32-style derivation. +// derivePrivateKey derives a private key from master seed using HKDF (RFC 5869). +// Uses domain-separated derivation with SHA-256, the derivation path as info, +// and a fixed salt for domain separation. func (s *DIDService) derivePrivateKey(masterSeed []byte, derivationPath string) (ed25519.PrivateKey, error) { - // Simplified derivation: hash master seed with derivation path - h := sha256.New() - h.Write(masterSeed) - h.Write([]byte(derivationPath)) - derivedSeed := h.Sum(nil) + salt := []byte("agentfield-did-key-derivation-v1") + info := []byte(derivationPath) + + hkdfReader := hkdf.New(sha256.New, masterSeed, salt, info) + derivedSeed := make([]byte, ed25519.SeedSize) // 32 bytes + if _, err := io.ReadFull(hkdfReader, derivedSeed); err != nil { + return nil, fmt.Errorf("HKDF key derivation failed: %w", err) + } - // Generate Ed25519 private key from derived seed privateKey := ed25519.NewKeyFromSeed(derivedSeed) return privateKey, nil } @@ -945,12 +994,35 @@ func (s *DIDService) buildExistingIdentityPackage(existingAgent *types.AgentDIDI agentfieldServerID = "unknown" } + // Retrieve master seed to re-derive private keys for the requesting agent. + // Agents need their private keys to sign cross-agent requests (DID auth). + var masterSeed []byte + registry, err := s.registry.GetRegistry(agentfieldServerID) + if err != nil { + logger.Logger.Error().Err(err).Msg("Failed to get registry for key re-derivation") + } else { + masterSeed = registry.MasterSeed + } + + // Helper to re-derive private key JWK from master seed and derivation path. + rederivePrivKey := func(derivationPath string) string { + if masterSeed == nil || derivationPath == "" { + return "" + } + _, privKeyJWK, _, err := s.generateDIDWithKeys(masterSeed, derivationPath) + if err != nil { + logger.Logger.Error().Err(err).Str("path", derivationPath).Msg("Failed to re-derive private key") + return "" + } + return privKeyJWK + } + // Build reasoner DIDs map reasonerDIDs := make(map[string]types.DIDIdentity) for id, reasonerInfo := range existingAgent.Reasoners { reasonerDIDs[id] = types.DIDIdentity{ DID: reasonerInfo.DID, - PrivateKeyJWK: "", // Don't include private keys in existing package + PrivateKeyJWK: rederivePrivKey(reasonerInfo.DerivationPath), PublicKeyJWK: string(reasonerInfo.PublicKeyJWK), DerivationPath: reasonerInfo.DerivationPath, ComponentType: "reasoner", @@ -963,7 +1035,7 @@ func (s *DIDService) buildExistingIdentityPackage(existingAgent *types.AgentDIDI for id, skillInfo := range existingAgent.Skills { skillDIDs[id] = types.DIDIdentity{ DID: skillInfo.DID, - PrivateKeyJWK: "", // Don't include private keys in existing package + PrivateKeyJWK: rederivePrivKey(skillInfo.DerivationPath), PublicKeyJWK: string(skillInfo.PublicKeyJWK), DerivationPath: skillInfo.DerivationPath, ComponentType: "skill", @@ -974,7 +1046,7 @@ func (s *DIDService) buildExistingIdentityPackage(existingAgent *types.AgentDIDI return types.DIDIdentityPackage{ AgentDID: types.DIDIdentity{ DID: existingAgent.DID, - PrivateKeyJWK: "", // Don't include private keys in existing package + PrivateKeyJWK: rederivePrivKey(existingAgent.DerivationPath), PublicKeyJWK: string(existingAgent.PublicKeyJWK), DerivationPath: existingAgent.DerivationPath, ComponentType: "agent", diff --git a/control-plane/internal/services/did_web_service.go b/control-plane/internal/services/did_web_service.go new file mode 100644 index 00000000..0810bc9f --- /dev/null +++ b/control-plane/internal/services/did_web_service.go @@ -0,0 +1,385 @@ +package services + +import ( + "context" + "crypto/ed25519" + "encoding/base64" + "encoding/json" + "fmt" + "strings" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" +) + +// DIDWebService handles did:web generation, storage, and resolution. +type DIDWebService struct { + domain string + didService *DIDService + storage DIDWebStorage +} + +// DIDWebStorage defines the storage interface for DID documents. +type DIDWebStorage interface { + StoreDIDDocument(ctx context.Context, record *types.DIDDocumentRecord) error + GetDIDDocument(ctx context.Context, did string) (*types.DIDDocumentRecord, error) + GetDIDDocumentByAgentID(ctx context.Context, agentID string) (*types.DIDDocumentRecord, error) + RevokeDIDDocument(ctx context.Context, did string) error + ListDIDDocuments(ctx context.Context) ([]*types.DIDDocumentRecord, error) +} + +// NewDIDWebService creates a new did:web service instance. +func NewDIDWebService(domain string, didService *DIDService, storage DIDWebStorage) *DIDWebService { + return &DIDWebService{ + domain: domain, + didService: didService, + storage: storage, + } +} + +// GenerateDIDWeb creates a did:web identifier for an agent. +// Format: did:web:{domain}:agents:{agentID} +func (s *DIDWebService) GenerateDIDWeb(agentID string) string { + // URL-encode the domain (replace : with %3A for port numbers) + encodedDomain := strings.ReplaceAll(s.domain, ":", "%3A") + return fmt.Sprintf("did:web:%s:agents:%s", encodedDomain, agentID) +} + +// ResolveAgentIDByDID looks up the agent ID for any DID format. +// It first queries the stored DID documents (covers did:web), then falls back +// to the DID service's in-memory registry (covers did:key). +// Returns empty string if the DID is not found. +func (s *DIDWebService) ResolveAgentIDByDID(ctx context.Context, did string) string { + // Try storage lookup first (works for did:web) + record, err := s.storage.GetDIDDocument(ctx, did) + if err == nil && record != nil { + return record.AgentID + } + // Fall back to DID service registry (works for did:key) + if s.didService != nil { + return s.didService.ResolveAgentIDByDID(did) + } + return "" +} + +// ParseDIDWeb extracts the agent ID from a did:web identifier. +// Returns the agent ID or an error if the DID format is invalid. +func (s *DIDWebService) ParseDIDWeb(did string) (string, error) { + // Expected format: did:web:{domain}:agents:{agentID} + if !strings.HasPrefix(did, "did:web:") { + return "", fmt.Errorf("invalid did:web format: must start with 'did:web:'") + } + + parts := strings.Split(did, ":") + if len(parts) < 5 { + return "", fmt.Errorf("invalid did:web format: expected at least 5 parts") + } + + // Find the "agents" part and extract the agent ID + for i, part := range parts { + if part == "agents" && i+1 < len(parts) { + return parts[i+1], nil + } + } + + return "", fmt.Errorf("invalid did:web format: missing 'agents' segment") +} + +// CreateDIDDocument creates and stores a DID document for an agent. +func (s *DIDWebService) CreateDIDDocument(ctx context.Context, agentID string, publicKeyJWK json.RawMessage) (*types.DIDWebDocument, error) { + // Generate the did:web identifier + did := s.GenerateDIDWeb(agentID) + + // Create the DID document + didDoc := types.NewDIDWebDocument(did, publicKeyJWK) + + // Serialize the document for storage + docBytes, err := json.Marshal(didDoc) + if err != nil { + return nil, fmt.Errorf("failed to marshal DID document: %w", err) + } + + // Create the storage record + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: string(publicKeyJWK), + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + // Store the record + if err := s.storage.StoreDIDDocument(ctx, record); err != nil { + return nil, fmt.Errorf("failed to store DID document: %w", err) + } + + logger.Logger.Info(). + Str("did", did). + Str("agent_id", agentID). + Msg("Created DID document for agent") + + return didDoc, nil +} + +// ResolveDID resolves a did:web identifier to its DID document. +// Returns the DID document or an error if not found or revoked. +func (s *DIDWebService) ResolveDID(ctx context.Context, did string) (*types.DIDResolutionResult, error) { + // Get the DID document record + record, err := s.storage.GetDIDDocument(ctx, did) + if err != nil { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{ + Error: "notFound", + }, + }, nil + } + + // Check if revoked + if record.IsRevoked() { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{ + Error: "deactivated", + }, + DIDDocumentMetadata: types.DIDDocumentMetadata{ + Deactivated: true, + }, + }, nil + } + + // Parse the stored DID document + var didDoc types.DIDWebDocument + if err := json.Unmarshal(record.DIDDocument, &didDoc); err != nil { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{ + Error: "invalidDidDocument", + }, + }, nil + } + + return &types.DIDResolutionResult{ + DIDDocument: &didDoc, + DIDResolutionMetadata: types.DIDResolutionMetadata{ + ContentType: "application/did+ld+json", + }, + DIDDocumentMetadata: types.DIDDocumentMetadata{ + Created: record.CreatedAt.Format(time.RFC3339), + Updated: record.UpdatedAt.Format(time.RFC3339), + }, + }, nil +} + +// ResolveDIDByAgentID resolves a DID document by agent ID. +func (s *DIDWebService) ResolveDIDByAgentID(ctx context.Context, agentID string) (*types.DIDResolutionResult, error) { + did := s.GenerateDIDWeb(agentID) + return s.ResolveDID(ctx, did) +} + +// RevokeDID revokes a did:web identifier, making it invalid. +func (s *DIDWebService) RevokeDID(ctx context.Context, did string) error { + if err := s.storage.RevokeDIDDocument(ctx, did); err != nil { + return fmt.Errorf("failed to revoke DID: %w", err) + } + + logger.Logger.Info(). + Str("did", did). + Msg("Revoked DID document") + + return nil +} + +// IsDIDRevoked checks if a DID has been revoked. +// Returns true if revoked, false if active or not found. +// On storage errors (other than not-found), returns true to fail closed. +func (s *DIDWebService) IsDIDRevoked(ctx context.Context, did string) bool { + record, err := s.storage.GetDIDDocument(ctx, did) + if err != nil { + // Check if this is a "not found" error vs a real storage failure. + // Not found means the DID was never registered — treat as not revoked. + // Any other error (DB timeout, connection failure) — fail closed. + if strings.Contains(err.Error(), "not found") || strings.Contains(err.Error(), "no rows") { + return false + } + logger.Logger.Warn().Err(err).Str("did", did).Msg("Storage error checking DID revocation, failing closed") + return true + } + return record.IsRevoked() +} + +// GetOrCreateDIDDocument gets an existing DID document or creates a new one. +// This is useful when registering agents - we want to reuse existing DIDs if the agent +// has the same ID, or create new ones for new agents. +func (s *DIDWebService) GetOrCreateDIDDocument(ctx context.Context, agentID string) (*types.DIDWebDocument, string, error) { + // Try to get existing DID document + did := s.GenerateDIDWeb(agentID) + record, err := s.storage.GetDIDDocument(ctx, did) + if err == nil && !record.IsRevoked() { + // Parse and return existing document + var didDoc types.DIDWebDocument + if err := json.Unmarshal(record.DIDDocument, &didDoc); err != nil { + return nil, "", fmt.Errorf("failed to parse existing DID document: %w", err) + } + return &didDoc, did, nil + } + + // Generate new key pair for the agent + publicKeyJWK, err := s.generatePublicKeyJWK(agentID) + if err != nil { + return nil, "", fmt.Errorf("failed to generate public key: %w", err) + } + + // Create new DID document + didDoc, err := s.CreateDIDDocument(ctx, agentID, publicKeyJWK) + if err != nil { + return nil, "", fmt.Errorf("failed to create DID document: %w", err) + } + + return didDoc, did, nil +} + +// generatePublicKeyJWK generates a new Ed25519 public key JWK for an agent. +// This uses the DID service's key derivation to ensure deterministic keys. +func (s *DIDWebService) generatePublicKeyJWK(agentID string) (json.RawMessage, error) { + // Get the registry to access the master seed + serverID, err := s.didService.GetAgentFieldServerID() + if err != nil { + return nil, fmt.Errorf("failed to get server ID: %w", err) + } + + registry, err := s.didService.registry.GetRegistry(serverID) + if err != nil { + return nil, fmt.Errorf("failed to get registry: %w", err) + } + + if registry == nil { + return nil, fmt.Errorf("DID registry not initialized") + } + + // Generate derivation path for this agent + // Use the agent ID to create a unique path + derivationPath := fmt.Sprintf("m/44'/web'/%s'", agentID) + + // Derive the public key JWK + publicKeyJWK, err := s.didService.regeneratePublicKeyJWK(registry.MasterSeed, derivationPath) + if err != nil { + return nil, fmt.Errorf("failed to generate public key JWK: %w", err) + } + + return json.RawMessage(publicKeyJWK), nil +} + +// GetPrivateKeyJWK retrieves the private key JWK for signing operations. +// This should only be used by the control plane for signing VCs. +func (s *DIDWebService) GetPrivateKeyJWK(agentID string) (string, error) { + // Get the registry to access the master seed + serverID, err := s.didService.GetAgentFieldServerID() + if err != nil { + return "", fmt.Errorf("failed to get server ID: %w", err) + } + + registry, err := s.didService.registry.GetRegistry(serverID) + if err != nil { + return "", fmt.Errorf("failed to get registry: %w", err) + } + + if registry == nil { + return "", fmt.Errorf("DID registry not initialized") + } + + // Generate derivation path for this agent + derivationPath := fmt.Sprintf("m/44'/web'/%s'", agentID) + + // Derive the private key JWK + privateKeyJWK, err := s.didService.regeneratePrivateKeyJWK(registry.MasterSeed, derivationPath) + if err != nil { + return "", fmt.Errorf("failed to generate private key JWK: %w", err) + } + + return privateKeyJWK, nil +} + +// GetDomain returns the configured domain for did:web identifiers. +func (s *DIDWebService) GetDomain() string { + return s.domain +} + +// VerifyDIDOwnership verifies that a signature was created by the private key +// corresponding to a did:web identifier. +func (s *DIDWebService) VerifyDIDOwnership(ctx context.Context, did string, message []byte, signature []byte) (bool, error) { + // Handle did:key self-resolution: public key is encoded directly in the DID. + if strings.HasPrefix(did, "did:key:z") { + pubKey, err := decodeDIDKeyPublicKey(did) + if err != nil { + return false, fmt.Errorf("failed to decode did:key public key: %w", err) + } + return ed25519.Verify(pubKey, message, signature), nil + } + + // Resolve did:web (or other methods) via stored DID documents. + result, err := s.ResolveDID(ctx, did) + if err != nil { + return false, fmt.Errorf("failed to resolve DID: %w", err) + } + + if result.DIDDocument == nil { + return false, fmt.Errorf("DID not found or deactivated") + } + + if len(result.DIDDocument.VerificationMethod) == 0 { + return false, fmt.Errorf("no verification method in DID document") + } + + // Get the public key from the verification method + vm := result.DIDDocument.VerificationMethod[0] + + // Parse the JWK to extract the public key + var jwk struct { + X string `json:"x"` + } + if err := json.Unmarshal(vm.PublicKeyJwk, &jwk); err != nil { + return false, fmt.Errorf("failed to parse public key JWK: %w", err) + } + + // Decode the public key + publicKeyBytes, err := base64RawURLDecode(jwk.X) + if err != nil { + return false, fmt.Errorf("failed to decode public key: %w", err) + } + + // Verify the signature + publicKey := ed25519.PublicKey(publicKeyBytes) + return ed25519.Verify(publicKey, message, signature), nil +} + +// decodeDIDKeyPublicKey extracts the Ed25519 public key from a did:key identifier. +// Format: did:key:z +func decodeDIDKeyPublicKey(did string) (ed25519.PublicKey, error) { + const prefix = "did:key:z" + if !strings.HasPrefix(did, prefix) { + return nil, fmt.Errorf("invalid did:key format") + } + + encoded := did[len(prefix):] + decoded, err := base64.RawURLEncoding.DecodeString(encoded) + if err != nil { + return nil, fmt.Errorf("failed to base64url decode did:key: %w", err) + } + + // Verify multicodec prefix (0xed, 0x01 for Ed25519) + if len(decoded) < 2 || decoded[0] != 0xed || decoded[1] != 0x01 { + return nil, fmt.Errorf("unsupported multicodec prefix in did:key") + } + + pubKeyBytes := decoded[2:] + if len(pubKeyBytes) != ed25519.PublicKeySize { + return nil, fmt.Errorf("invalid Ed25519 public key length: got %d, want %d", len(pubKeyBytes), ed25519.PublicKeySize) + } + + return ed25519.PublicKey(pubKeyBytes), nil +} + +// base64RawURLDecode decodes a base64 raw URL encoded string. +func base64RawURLDecode(s string) ([]byte, error) { + return base64.RawURLEncoding.DecodeString(s) +} diff --git a/control-plane/internal/services/health_monitor.go b/control-plane/internal/services/health_monitor.go index 76d2e6dd..725b4af1 100644 --- a/control-plane/internal/services/health_monitor.go +++ b/control-plane/internal/services/health_monitor.go @@ -111,7 +111,7 @@ func (hm *HealthMonitor) RegisterAgent(nodeID, baseURL string) { } if hm.presence != nil { - hm.presence.Touch(nodeID, seenAt) + hm.presence.Touch(nodeID, "", seenAt) } logger.Logger.Debug().Msgf("🏥 Registered agent %s for HTTP health monitoring", nodeID) @@ -345,6 +345,27 @@ func (hm *HealthMonitor) checkAgentHealth(nodeID string) { // Only mark inactive after reaching the consecutive failure threshold if activeAgent.ConsecutiveFailures >= hm.config.ConsecutiveFailures { + // HEARTBEAT GATE: Before marking inactive, check if the agent has sent + // a recent heartbeat. Heartbeats are direct proof of agent liveness — + // if the agent is sending heartbeats, HTTP check failures are transient + // and should not trigger an inactive transition. We check the storage + // heartbeat timestamp rather than the presence lease because the presence + // lease is also set by RegisterAgent (not just heartbeats). + if hm.statusManager != nil { + staleThreshold := hm.statusManager.config.HeartbeatStaleThreshold + if staleThreshold == 0 { + staleThreshold = 60 * time.Second + } + if agent, err := hm.storage.GetAgent(context.Background(), nodeID); err == nil && agent != nil { + if time.Since(agent.LastHeartbeat) < staleThreshold { + logger.Logger.Debug().Msgf("🏥 Agent %s has %d HTTP failures but heartbeat is fresh (%v ago) — not marking inactive", + nodeID, activeAgent.ConsecutiveFailures, time.Since(agent.LastHeartbeat)) + hm.agentsMutex.Unlock() + return + } + } + } + if activeAgent.LastStatus != types.HealthStatusInactive { activeAgent.LastStatus = types.HealthStatusInactive activeAgent.LastTransition = time.Now() @@ -383,7 +404,7 @@ func (hm *HealthMonitor) markAgentActive(nodeID string) { } if hm.presence != nil { - hm.presence.Touch(nodeID, time.Now()) + hm.presence.Touch(nodeID, "", time.Now()) } // Check MCP health for active agents @@ -400,7 +421,7 @@ func (hm *HealthMonitor) markAgentActive(nodeID string) { if updatedAgent, err := hm.storage.GetAgent(ctx, nodeID); err == nil { events.PublishNodeOnline(nodeID, updatedAgent) if hm.presence != nil { - hm.presence.Touch(nodeID, time.Now()) + hm.presence.Touch(nodeID, "", time.Now()) } events.PublishNodeHealthChanged(nodeID, string(types.HealthStatusActive), updatedAgent) if hm.uiService != nil { diff --git a/control-plane/internal/services/health_monitor_test.go b/control-plane/internal/services/health_monitor_test.go index 0ee9ef34..e5a456cc 100644 --- a/control-plane/internal/services/health_monitor_test.go +++ b/control-plane/internal/services/health_monitor_test.go @@ -1290,7 +1290,7 @@ func TestIntegration_NoFlapping_HeartbeatsDuringTransientFailures(t *testing.T) // Register with health monitor and presence hm.RegisterAgent(nodeID, "http://localhost:9999") - presenceManager.Touch(nodeID, time.Now()) + presenceManager.Touch(nodeID, "", time.Now()) // --- Start all 3 services concurrently (like production) --- go hm.Start() @@ -1323,8 +1323,8 @@ func TestIntegration_NoFlapping_HeartbeatsDuringTransientFailures(t *testing.T) for i := 0; i < 30; i++ { // 30 heartbeats over ~3 seconds <-ticker.C readyStatus := types.AgentStatusReady - _ = statusManager.UpdateFromHeartbeat(ctx, nodeID, &readyStatus, nil) - presenceManager.Touch(nodeID, time.Now()) + _ = statusManager.UpdateFromHeartbeat(ctx, nodeID, &readyStatus, nil, "") + presenceManager.Touch(nodeID, "", time.Now()) // Record current state snap, err := statusManager.GetAgentStatusSnapshot(ctx, nodeID, nil) @@ -1443,7 +1443,7 @@ func TestIntegration_ProperInactiveWhenHeartbeatsStop(t *testing.T) { mockClient.setStatusResponse(nodeID, "running") hm.RegisterAgent(nodeID, "http://localhost:9998") - presenceManager.Touch(nodeID, time.Now()) + presenceManager.Touch(nodeID, "", time.Now()) // Start all services go hm.Start() @@ -1526,7 +1526,7 @@ func TestIntegration_RecoveryAfterGenuineOutage(t *testing.T) { mockClient.setStatusResponse(nodeID, "running") hm.RegisterAgent(nodeID, "http://localhost:9997") - presenceManager.Touch(nodeID, time.Now()) + presenceManager.Touch(nodeID, "", time.Now()) // Start all services go hm.Start() @@ -1555,11 +1555,11 @@ func TestIntegration_RecoveryAfterGenuineOutage(t *testing.T) { // Re-register with health monitor (agent would re-register on reconnect) hm.RegisterAgent(nodeID, "http://localhost:9997") - presenceManager.Touch(nodeID, time.Now()) + presenceManager.Touch(nodeID, "", time.Now()) // Send a heartbeat to signal recovery readyStatus := types.AgentStatusReady - err = statusManager.UpdateFromHeartbeat(ctx, nodeID, &readyStatus, nil) + err = statusManager.UpdateFromHeartbeat(ctx, nodeID, &readyStatus, nil, "") require.NoError(t, err) // Wait for health check cycle + debounce diff --git a/control-plane/internal/services/presence_manager.go b/control-plane/internal/services/presence_manager.go index 8cc7c9a6..4b7e4828 100644 --- a/control-plane/internal/services/presence_manager.go +++ b/control-plane/internal/services/presence_manager.go @@ -20,6 +20,7 @@ type presenceLease struct { LastSeen time.Time LastExpired time.Time MarkedOffline bool + Version string } type PresenceManager struct { @@ -66,7 +67,7 @@ func (pm *PresenceManager) Stop() { }) } -func (pm *PresenceManager) Touch(nodeID string, seenAt time.Time) { +func (pm *PresenceManager) Touch(nodeID string, version string, seenAt time.Time) { pm.mu.Lock() lease, exists := pm.leases[nodeID] if !exists { @@ -75,6 +76,9 @@ func (pm *PresenceManager) Touch(nodeID string, seenAt time.Time) { } lease.LastSeen = seenAt lease.MarkedOffline = false + if version != "" { + lease.Version = version + } pm.mu.Unlock() } @@ -91,6 +95,19 @@ func (pm *PresenceManager) HasLease(nodeID string) bool { return exists } +// HasFreshLease returns true if the agent has a lease with a heartbeat +// received within the HeartbeatTTL. This is used by the health monitor +// to avoid marking agents inactive when heartbeats are still flowing. +func (pm *PresenceManager) HasFreshLease(nodeID string) bool { + pm.mu.RLock() + defer pm.mu.RUnlock() + lease, exists := pm.leases[nodeID] + if !exists { + return false + } + return !lease.MarkedOffline && time.Since(lease.LastSeen) < pm.config.HeartbeatTTL +} + func (pm *PresenceManager) SetExpireCallback(fn func(string)) { pm.mu.Lock() pm.expireCallback = fn @@ -125,6 +142,7 @@ func (pm *PresenceManager) RecoverFromDatabase(ctx context.Context, storageProvi pm.leases[node.ID] = &presenceLease{ LastSeen: node.LastHeartbeat, MarkedOffline: time.Since(node.LastHeartbeat) > pm.config.HeartbeatTTL, + Version: node.Version, } } @@ -174,6 +192,23 @@ func (pm *PresenceManager) markInactive(nodeID string) { return } + // Re-check lease freshness under lock. Between collecting expired nodes in + // checkExpirations() and calling this callback, a Touch() may have refreshed + // the lease (e.g., agent re-registered). If so, skip the inactive transition. + pm.mu.RLock() + lease, ok := pm.leases[nodeID] + if !ok { + pm.mu.RUnlock() + return + } + if !lease.MarkedOffline { + // Lease was refreshed by Touch() after we collected it as expired + pm.mu.RUnlock() + return + } + version := lease.Version + pm.mu.RUnlock() + ctx := context.Background() inactive := types.AgentStateInactive zero := 0 @@ -182,6 +217,7 @@ func (pm *PresenceManager) markInactive(nodeID string) { HealthScore: &zero, Source: types.StatusSourcePresence, Reason: "presence lease expired", + Version: version, } if err := pm.statusManager.UpdateAgentStatus(ctx, nodeID, update); err != nil { diff --git a/control-plane/internal/services/presence_manager_test.go b/control-plane/internal/services/presence_manager_test.go index 2895d8b6..6856923b 100644 --- a/control-plane/internal/services/presence_manager_test.go +++ b/control-plane/internal/services/presence_manager_test.go @@ -86,7 +86,7 @@ func TestPresenceManager_Touch(t *testing.T) { nodeID := "node-touch-1" now := time.Now() - pm.Touch(nodeID, now) + pm.Touch(nodeID, "", now) // Verify lease exists require.True(t, pm.HasLease(nodeID)) @@ -97,11 +97,11 @@ func TestPresenceManager_Touch_UpdateExisting(t *testing.T) { nodeID := "node-touch-update" now1 := time.Now() - pm.Touch(nodeID, now1) + pm.Touch(nodeID, "", now1) time.Sleep(10 * time.Millisecond) now2 := time.Now() - pm.Touch(nodeID, now2) + pm.Touch(nodeID, "", now2) // Verify lease still exists require.True(t, pm.HasLease(nodeID)) @@ -111,7 +111,7 @@ func TestPresenceManager_Forget(t *testing.T) { pm, _ := setupPresenceManagerTest(t) nodeID := "node-forget-1" - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) require.True(t, pm.HasLease(nodeID)) pm.Forget(nodeID) @@ -124,7 +124,7 @@ func TestPresenceManager_HasLease(t *testing.T) { nodeID := "node-lease-1" require.False(t, pm.HasLease(nodeID)) - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) require.True(t, pm.HasLease(nodeID)) pm.Forget(nodeID) @@ -132,34 +132,55 @@ func TestPresenceManager_HasLease(t *testing.T) { } func TestPresenceManager_SetExpireCallback(t *testing.T) { - pm, _ := setupPresenceManagerTest(t) + pm, provider := setupPresenceManagerTest(t) + // Register the agent in storage so UpdateAgentStatus can look up its status. + // Without this, markInactive → UpdateAgentStatus → GetAgentStatusSnapshot → GetAgent + // fails and returns early before invoking the callback. + ctx := context.Background() + nodeID := "node-callback-1" + require.NoError(t, provider.RegisterAgent(ctx, &types.AgentNode{ + ID: nodeID, + BaseURL: "http://localhost:9999", + LastHeartbeat: time.Now(), + })) + + var mu sync.Mutex var callbackInvoked bool var callbackNodeID string - callback := func(nodeID string) { + callback := func(id string) { + mu.Lock() callbackInvoked = true - callbackNodeID = nodeID + callbackNodeID = id + mu.Unlock() } pm.SetExpireCallback(callback) require.NotNil(t, pm.expireCallback) + // Use shorter intervals for faster test execution + pm.config.HeartbeatTTL = 500 * time.Millisecond + pm.config.SweepInterval = 200 * time.Millisecond + // Start the presence manager to trigger expiration pm.Start() - // Touch a node - nodeID := "node-callback-1" - pm.Touch(nodeID, time.Now().Add(-10*time.Second)) // Touch in the past + // Touch a node in the past so it's already expired + pm.Touch(nodeID, "", time.Now().Add(-10*time.Second)) - // Wait for expiration - time.Sleep(2 * time.Second) + // Wait for sweep to detect the expired node (generous margin for CI) + require.Eventually(t, func() bool { + mu.Lock() + defer mu.Unlock() + return callbackInvoked + }, 5*time.Second, 100*time.Millisecond, "expire callback should have been invoked") pm.Stop() - // Callback should have been invoked - require.True(t, callbackInvoked) + mu.Lock() require.Equal(t, nodeID, callbackNodeID) + mu.Unlock() } func TestPresenceManager_ExpirationDetection(t *testing.T) { @@ -167,19 +188,22 @@ func TestPresenceManager_ExpirationDetection(t *testing.T) { // Set shorter TTL for testing pm.config.HeartbeatTTL = 500 * time.Millisecond - pm.config.SweepInterval = 100 * time.Millisecond + pm.config.SweepInterval = 200 * time.Millisecond + // Set hard evict TTL short so the lease gets deleted after expiration. + // The sweep first marks offline (MarkedOffline=true) keeping the lease, + // then on the next sweep removes it if HardEvictTTL has elapsed. + pm.config.HardEvictTTL = 1 * time.Second pm.Start() nodeID := "node-expire-1" - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) require.True(t, pm.HasLease(nodeID)) - // Wait for expiration - time.Sleep(700 * time.Millisecond) - - // Node should be marked offline - require.False(t, pm.HasLease(nodeID)) + // Wait for expiration: TTL expires → marked offline → hard evict removes lease + require.Eventually(t, func() bool { + return !pm.HasLease(nodeID) + }, 5*time.Second, 100*time.Millisecond, "node should be removed after TTL + hard evict expiration") pm.Stop() } @@ -198,7 +222,7 @@ func TestPresenceManager_ConcurrentAccess(t *testing.T) { defer wg.Done() for j := 0; j < numNodes; j++ { nodeID := "node-concurrent-" + string(rune('0'+j)) - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) _ = pm.HasLease(nodeID) } }(i) @@ -220,7 +244,7 @@ func TestPresenceManager_StartStop(t *testing.T) { // Verify it's running nodeID := "node-start-stop" - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) require.True(t, pm.HasLease(nodeID)) pm.Stop() @@ -240,7 +264,7 @@ func TestPresenceManager_HardEviction(t *testing.T) { pm.Start() nodeID := "node-hard-evict" - pm.Touch(nodeID, time.Now().Add(-2*time.Second)) // Touch in the past beyond hard evict TTL + pm.Touch(nodeID, "", time.Now().Add(-2*time.Second)) // Touch in the past beyond hard evict TTL // Wait for hard eviction time.Sleep(1 * time.Second) @@ -257,7 +281,7 @@ func TestPresenceManager_MultipleNodes(t *testing.T) { nodeIDs := []string{"node-1", "node-2", "node-3"} for _, nodeID := range nodeIDs { - pm.Touch(nodeID, time.Now()) + pm.Touch(nodeID, "", time.Now()) require.True(t, pm.HasLease(nodeID)) } diff --git a/control-plane/internal/services/status_manager.go b/control-plane/internal/services/status_manager.go index ec99d6bc..5f1d5863 100644 --- a/control-plane/internal/services/status_manager.go +++ b/control-plane/internal/services/status_manager.go @@ -177,13 +177,28 @@ func (sm *StatusManager) GetAgentStatus(ctx context.Context, nodeID string) (*ty // Create status based on health check result now := time.Now() + + // Preserve admin-controlled lifecycle status (e.g., pending_approval) from storage. + // Live health checks prove liveness but must not override admin decisions. + var preservedLifecycle types.AgentLifecycleStatus + agent, agentErr := sm.storage.GetAgent(ctx, nodeID) + if agentErr == nil && agent != nil { + if agent.LifecycleStatus == types.AgentStatusPendingApproval { + preservedLifecycle = types.AgentStatusPendingApproval + } + } + if healthCheckSuccessful && agentStatusResp.Status == "running" { + lifecycle := types.AgentStatusReady + if preservedLifecycle == types.AgentStatusPendingApproval { + lifecycle = types.AgentStatusPendingApproval + } // Agent is active and running status = &types.AgentStatus{ State: types.AgentStateActive, HealthScore: 85, // Good health from live verification LastSeen: now, - LifecycleStatus: types.AgentStatusReady, + LifecycleStatus: lifecycle, HealthStatus: types.HealthStatusActive, LastUpdated: now, LastVerified: &now, // Set when live health check was performed @@ -284,11 +299,40 @@ func (sm *StatusManager) GetAgentStatusSnapshot(ctx context.Context, nodeID stri // UpdateAgentStatus updates the agent status with reconciliation func (sm *StatusManager) UpdateAgentStatus(ctx context.Context, nodeID string, update *types.AgentStatusUpdate) error { + // Resolve the agent node, supporting multi-version agents via the + // composite primary key (id, version). GetAgent only returns + // version="" rows; fall back to GetAgentVersion when a version is + // provided in the update. + resolvedAgent, resolveErr := sm.storage.GetAgent(ctx, nodeID) + if (resolveErr != nil || resolvedAgent == nil) && update.Version != "" { + resolvedAgent, resolveErr = sm.storage.GetAgentVersion(ctx, nodeID, update.Version) + } + + // Protect pending_approval from non-admin updates. The tag approval service + // transitions agents out of pending_approval by modifying storage directly + // (not through UpdateAgentStatus). Therefore ALL updates flowing through this + // method must be blocked when the agent is pending_approval, to prevent + // heartbeats, health checks, lease renewals, and transition timeouts from + // overriding the admin-controlled state. + if resolveErr == nil && resolvedAgent != nil { + if resolvedAgent.LifecycleStatus == types.AgentStatusPendingApproval { + // Allow health score cache updates, but not lifecycle/state changes + if update.HealthScore != nil { + sm.cacheMutex.Lock() + if cached, exists := sm.statusCache[nodeID]; exists && cached.Status != nil { + cached.Status.HealthScore = *update.HealthScore + } + sm.cacheMutex.Unlock() + } + return nil + } + } + // Get current status using snapshot (no live health check) to preserve the true "old" state // for event broadcasting. Using GetAgentStatus here would perform a live health check, // which could return the same state as the update, causing oldStatus == newStatus // and preventing status change events from being broadcast. - currentStatus, err := sm.GetAgentStatusSnapshot(ctx, nodeID, nil) + currentStatus, err := sm.GetAgentStatusSnapshot(ctx, nodeID, resolvedAgent) if err != nil { return fmt.Errorf("failed to get current status: %w", err) } @@ -344,14 +388,25 @@ func (sm *StatusManager) UpdateAgentStatus(ctx context.Context, nodeID string, u newStatus.LastUpdated = time.Now() newStatus.Source = update.Source + // Heartbeats are direct proof of life — always refresh LastSeen so that + // reconciliation (which checks LastHeartbeat staleness) doesn't mark the + // agent inactive while heartbeats are actively flowing. + if update.Source == types.StatusSourceHeartbeat { + newStatus.LastSeen = time.Now() + } + // Update backward compatibility fields newStatus.HealthStatus = newStatus.ToLegacyHealthStatus() if newStatus.LifecycleStatus == "" { newStatus.LifecycleStatus = newStatus.ToLegacyLifecycleStatus() } - // Persist to storage - if err := sm.persistStatus(ctx, nodeID, &newStatus); err != nil { + // Persist to storage — use the resolved agent's version for the composite key + agentVersion := "" + if resolvedAgent != nil { + agentVersion = resolvedAgent.Version + } + if err := sm.persistStatus(ctx, nodeID, agentVersion, &newStatus); err != nil { return fmt.Errorf("failed to persist status: %w", err) } @@ -380,9 +435,12 @@ func (sm *StatusManager) UpdateAgentStatus(ctx context.Context, nodeID string, u return nil } -// UpdateFromHeartbeat updates status based on heartbeat data -func (sm *StatusManager) UpdateFromHeartbeat(ctx context.Context, nodeID string, lifecycleStatus *types.AgentLifecycleStatus, mcpStatus *types.MCPStatusInfo) error { - currentStatus, err := sm.GetAgentStatus(ctx, nodeID) +// UpdateFromHeartbeat updates status based on heartbeat data. +// Uses snapshot (not live health check) to avoid overriding admin-controlled states +// and to prevent the heartbeat handler from contaminating the cache with HTTP check +// results — the heartbeat itself is the proof of life. +func (sm *StatusManager) UpdateFromHeartbeat(ctx context.Context, nodeID string, lifecycleStatus *types.AgentLifecycleStatus, mcpStatus *types.MCPStatusInfo, version string) error { + currentStatus, err := sm.GetAgentStatusSnapshot(ctx, nodeID, nil) if err != nil { // If agent doesn't exist, create new status currentStatus = types.NewAgentStatus(types.AgentStateStarting, types.StatusSourceHeartbeat) @@ -398,12 +456,29 @@ func (sm *StatusManager) UpdateFromHeartbeat(ctx context.Context, nodeID string, // Update from heartbeat currentStatus.UpdateFromHeartbeat(lifecycleStatus, mcpStatus) - // Persist changes + // Persist changes — derive State from lifecycle so UpdateAgentStatus keeps them in sync. update := &types.AgentStatusUpdate{ LifecycleStatus: lifecycleStatus, MCPStatus: mcpStatus, Source: types.StatusSourceHeartbeat, Reason: "heartbeat update", + Version: version, + } + if lifecycleStatus != nil { + var derivedState types.AgentState + switch *lifecycleStatus { + case types.AgentStatusReady: + derivedState = types.AgentStateActive + case types.AgentStatusStarting: + derivedState = types.AgentStateStarting + case types.AgentStatusDegraded: + derivedState = types.AgentStateActive + case types.AgentStatusOffline: + derivedState = types.AgentStateInactive + } + if derivedState != "" { + update.State = &derivedState + } } return sm.UpdateAgentStatus(ctx, nodeID, update) @@ -491,8 +566,10 @@ func (sm *StatusManager) isImmediateTransition(from, to types.AgentState) bool { return !(from == types.AgentStateStarting && to == types.AgentStateActive) } -// persistStatus persists the status to storage -func (sm *StatusManager) persistStatus(ctx context.Context, nodeID string, status *types.AgentStatus) error { +// persistStatus persists the status to storage. +// The version parameter is required for UpdateAgentHeartbeat which uses the composite +// primary key (id, version) to match the correct row. +func (sm *StatusManager) persistStatus(ctx context.Context, nodeID string, version string, status *types.AgentStatus) error { // DEFENSIVE: Enforce lifecycle_status consistency with state before persisting. // This ensures that even if the auto-sync logic didn't run (e.g., state wasn't changing), // the lifecycle_status will be correct in storage. This fixes the bug where offline nodes @@ -537,9 +614,16 @@ func (sm *StatusManager) persistStatus(ctx context.Context, nodeID string, statu return fmt.Errorf("failed to update lifecycle status: %w", err) } - // Update heartbeat timestamp - if err := sm.storage.UpdateAgentHeartbeat(ctx, nodeID, status.LastSeen); err != nil { - return fmt.Errorf("failed to update heartbeat: %w", err) + // Only update the heartbeat timestamp for heartbeat sources. Health checks and + // reconciliation should NOT overwrite LastHeartbeat — it must reflect when the + // agent actually sent a heartbeat, not when a status update was persisted. + // Without this guard, a health check can overwrite a fresh heartbeat timestamp + // with a stale LastSeen from the cached snapshot, causing reconciliation to + // falsely mark the agent inactive. + if status.Source == types.StatusSourceHeartbeat { + if err := sm.storage.UpdateAgentHeartbeat(ctx, nodeID, version, status.LastSeen); err != nil { + return fmt.Errorf("failed to update heartbeat: %w", err) + } } return nil @@ -564,10 +648,9 @@ func (sm *StatusManager) notifyStatusChanged(nodeID string, oldStatus, newStatus // broadcastStatusEvents broadcasts status change events using enhanced event system func (sm *StatusManager) broadcastStatusEvents(nodeID string, oldStatus, newStatus *types.AgentStatus) { - // Get updated agent for events ctx := context.Background() agent, err := sm.storage.GetAgent(ctx, nodeID) - if err != nil { + if err != nil || agent == nil { logger.Logger.Error().Err(err).Str("node_id", nodeID).Msg("❌ Failed to get agent for event broadcasting") return } @@ -661,6 +744,13 @@ func (sm *StatusManager) needsReconciliation(agent *types.AgentNode) bool { return true } + // Agents stuck in "starting" beyond the max transition time should be reconciled. + // Without this, agents that register but never send a "ready" heartbeat stay in + // "starting" forever because the check above only triggers for health_status="active". + if agent.LifecycleStatus == types.AgentStatusStarting && timeSinceHeartbeat > sm.config.MaxTransitionTime { + return true + } + return false } @@ -739,11 +829,18 @@ func (sm *StatusManager) checkTransitionTimeouts() { Dur("duration", now.Sub(transition.StartedAt)). Msg("🔄 Transition timeout, forcing completion") - // Force complete the transition + // Force complete the transition, but not if the agent is now pending_approval + // (e.g., tags were revoked while a transition was in progress). ctx := context.Background() - if status, err := sm.GetAgentStatus(ctx, nodeID); err == nil { + if agent, agentErr := sm.storage.GetAgent(ctx, nodeID); agentErr == nil && agent != nil && agent.LifecycleStatus == types.AgentStatusPendingApproval { + logger.Logger.Debug().Str("node_id", nodeID).Msg("cancelling stale transition: agent is pending_approval") + } else if status, err := sm.GetAgentStatus(ctx, nodeID); err == nil { status.CompleteTransition() - if err := sm.persistStatus(ctx, nodeID, status); err != nil { + ver := "" + if agent != nil { + ver = agent.Version + } + if err := sm.persistStatus(ctx, nodeID, ver, status); err != nil { logger.Logger.Warn(). Err(err). Str("node_id", nodeID). diff --git a/control-plane/internal/services/status_manager_test.go b/control-plane/internal/services/status_manager_test.go index ed8ffc4e..8351c9b7 100644 --- a/control-plane/internal/services/status_manager_test.go +++ b/control-plane/internal/services/status_manager_test.go @@ -522,7 +522,7 @@ func TestStatusManager_UpdateFromHeartbeat_NeverDropped(t *testing.T) { // Now send a heartbeat IMMEDIATELY (within what used to be the 10s drop window). // Previously this heartbeat would be silently ignored. Now it MUST be processed. readyStatus := types.AgentStatusReady - err = sm.UpdateFromHeartbeat(ctx, "node-heartbeat-priority", &readyStatus, nil) + err = sm.UpdateFromHeartbeat(ctx, "node-heartbeat-priority", &readyStatus, nil, "") require.NoError(t, err, "Heartbeat should never be dropped") // Verify the heartbeat was processed — agent should no longer be inactive @@ -569,4 +569,24 @@ func TestStatusManager_Reconciliation_UsesConfiguredThreshold(t *testing.T) { } assert.False(t, sm.needsReconciliation(inactiveAgent), "Already inactive agent should not need reconciliation") + + // Agent stuck in "starting" with stale heartbeat beyond MaxTransitionTime — SHOULD need reconciliation + stuckStartingAgent := &types.AgentNode{ + ID: "node-stuck-starting", + HealthStatus: types.HealthStatusUnknown, + LifecycleStatus: types.AgentStatusStarting, + LastHeartbeat: time.Now().Add(-3 * time.Minute), + } + assert.True(t, sm.needsReconciliation(stuckStartingAgent), + "Agent stuck in 'starting' beyond MaxTransitionTime should need reconciliation") + + // Agent in "starting" with recent heartbeat — should NOT need reconciliation (still initializing) + freshStartingAgent := &types.AgentNode{ + ID: "node-fresh-starting", + HealthStatus: types.HealthStatusUnknown, + LifecycleStatus: types.AgentStatusStarting, + LastHeartbeat: time.Now().Add(-30 * time.Second), + } + assert.False(t, sm.needsReconciliation(freshStartingAgent), + "Agent in 'starting' with recent heartbeat should not need reconciliation yet") } diff --git a/control-plane/internal/services/tag_approval_service.go b/control-plane/internal/services/tag_approval_service.go new file mode 100644 index 00000000..9136ab41 --- /dev/null +++ b/control-plane/internal/services/tag_approval_service.go @@ -0,0 +1,563 @@ +package services + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "strings" + "sync" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/google/uuid" +) + +// ErrNotPendingApproval indicates the agent is not in pending_approval status. +var ErrNotPendingApproval = errors.New("agent is not pending approval") + +// TagApprovalResult holds the outcome of evaluating proposed tags against approval rules. +type TagApprovalResult struct { + AutoApproved []string + ManualReview []string + Forbidden []string + AllAutoApproved bool +} + +// TagApprovalStorage defines storage operations needed by the tag approval service. +type TagApprovalStorage interface { + GetAgent(ctx context.Context, id string) (*types.AgentNode, error) + RegisterAgent(ctx context.Context, node *types.AgentNode) error + ListAgentsByLifecycleStatus(ctx context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) + GetAgentDID(ctx context.Context, agentID string) (*types.AgentDIDInfo, error) + StoreAgentTagVC(ctx context.Context, agentID, agentDID, vcID, vcDocument, signature string, issuedAt time.Time, expiresAt *time.Time) error + RevokeAgentTagVC(ctx context.Context, agentID string) error +} + +// TagApprovalVCService defines the VC signing operations needed by the tag approval service. +type TagApprovalVCService interface { + GetDIDService() *DIDService + SignAgentTagVC(vc *types.AgentTagVCDocument) (*types.VCProof, error) +} + +// TagApprovalService evaluates proposed tags against approval rules and manages +// the tag approval workflow for agents. +type TagApprovalService struct { + config config.TagApprovalRulesConfig + storage TagApprovalStorage + vcService TagApprovalVCService // optional, can be nil + onRevoke func(ctx context.Context, agentID string) + mu sync.RWMutex +} + +// NewTagApprovalService creates a new tag approval service. +func NewTagApprovalService(cfg config.TagApprovalRulesConfig, storage TagApprovalStorage) *TagApprovalService { + defaultMode := cfg.DefaultMode + if defaultMode == "" { + defaultMode = "auto" + } + cfg.DefaultMode = defaultMode + + return &TagApprovalService{ + config: cfg, + storage: storage, + } +} + +// SetOnRevokeCallback sets a callback invoked after tags are revoked, +// used to clear status caches and presence leases. +// Must be called during initialization before any concurrent use. +func (s *TagApprovalService) SetOnRevokeCallback(fn func(ctx context.Context, agentID string)) { + s.onRevoke = fn +} + +// SetVCService sets the VC service for tag VC issuance (optional dependency). +// Must be called during initialization before any concurrent use. +func (s *TagApprovalService) SetVCService(vcService TagApprovalVCService) { + s.mu.Lock() + defer s.mu.Unlock() + s.vcService = vcService +} + +// IsEnabled returns true if any tag approval rules require non-auto behavior. +func (s *TagApprovalService) IsEnabled() bool { + s.mu.RLock() + defer s.mu.RUnlock() + return len(s.config.Rules) > 0 || s.config.DefaultMode != "auto" +} + +// EvaluateTags evaluates a set of proposed tags against the configured approval rules. +func (s *TagApprovalService) EvaluateTags(proposedTags []string) TagApprovalResult { + s.mu.RLock() + defer s.mu.RUnlock() + + result := TagApprovalResult{} + + for _, tag := range proposedTags { + normalized := strings.ToLower(strings.TrimSpace(tag)) + if normalized == "" { + continue + } + + mode := s.getTagApprovalMode(normalized) + switch mode { + case "auto": + result.AutoApproved = append(result.AutoApproved, normalized) + case "manual": + result.ManualReview = append(result.ManualReview, normalized) + case "forbidden": + result.Forbidden = append(result.Forbidden, normalized) + default: + // Unknown mode treated as manual for safety + result.ManualReview = append(result.ManualReview, normalized) + } + } + + result.AllAutoApproved = len(result.ManualReview) == 0 && len(result.Forbidden) == 0 + return result +} + +// getTagApprovalMode returns the approval mode for a specific tag. +func (s *TagApprovalService) getTagApprovalMode(tag string) string { + for _, rule := range s.config.Rules { + for _, ruleTag := range rule.Tags { + normalized := strings.ToLower(strings.TrimSpace(ruleTag)) + if normalized == tag { + return rule.Approval + } + } + } + return s.config.DefaultMode +} + +// CollectAllProposedTags extracts all proposed tags from an agent's reasoners, skills, +// and agent-level ProposedTags field. +func CollectAllProposedTags(agent *types.AgentNode) []string { + seen := make(map[string]struct{}) + var tags []string + + add := func(tag string) { + normalized := strings.ToLower(strings.TrimSpace(tag)) + if normalized == "" { + return + } + if _, exists := seen[normalized]; exists { + return + } + seen[normalized] = struct{}{} + tags = append(tags, normalized) + } + + // Collect agent-level proposed tags (sent by SDKs as top-level proposed_tags). + for _, t := range agent.ProposedTags { + add(t) + } + + for _, r := range agent.Reasoners { + proposed := r.ProposedTags + if len(proposed) == 0 { + proposed = r.Tags + } + for _, t := range proposed { + add(t) + } + } + + for _, sk := range agent.Skills { + proposed := sk.ProposedTags + if len(proposed) == 0 { + proposed = sk.Tags + } + for _, t := range proposed { + add(t) + } + } + + return tags +} + +// ApproveAgentTags approves an agent's tags, setting approved_tags and transitioning +// the lifecycle status from pending_approval to starting. +func (s *TagApprovalService) ApproveAgentTags(ctx context.Context, agentID string, approvedTags []string, approvedBy string) error { + agent, err := s.storage.GetAgent(ctx, agentID) + if err != nil { + return err + } + + if agent.LifecycleStatus != types.AgentStatusPendingApproval { + return fmt.Errorf("%w: agent %s (current status: %s)", ErrNotPendingApproval, agentID, agent.LifecycleStatus) + } + + agent.ApprovedTags = approvedTags + agent.LifecycleStatus = types.AgentStatusStarting + + // Set approved tags on each reasoner and skill + approvedSet := make(map[string]struct{}) + for _, t := range approvedTags { + approvedSet[strings.ToLower(strings.TrimSpace(t))] = struct{}{} + } + + for i := range agent.Reasoners { + var approved []string + proposed := agent.Reasoners[i].ProposedTags + if len(proposed) == 0 { + proposed = agent.Reasoners[i].Tags + } + for _, t := range proposed { + if _, ok := approvedSet[strings.ToLower(strings.TrimSpace(t))]; ok { + approved = append(approved, t) + } + } + agent.Reasoners[i].ApprovedTags = approved + } + + for i := range agent.Skills { + var approved []string + proposed := agent.Skills[i].ProposedTags + if len(proposed) == 0 { + proposed = agent.Skills[i].Tags + } + for _, t := range proposed { + if _, ok := approvedSet[strings.ToLower(strings.TrimSpace(t))]; ok { + approved = append(approved, t) + } + } + agent.Skills[i].ApprovedTags = approved + } + + if err := s.storage.RegisterAgent(ctx, agent); err != nil { + return err + } + + logger.Logger.Info(). + Str("agent_id", agentID). + Strs("approved_tags", approvedTags). + Str("approved_by", approvedBy). + Msg("Agent tags approved") + + // Issue a signed Agent Tag VC (non-fatal on failure) + s.issueTagVC(ctx, agentID, approvedTags, approvedBy) + + return nil +} + +// ApproveAgentTagsPerSkill approves tags at per-skill/per-reasoner granularity. +func (s *TagApprovalService) ApproveAgentTagsPerSkill(ctx context.Context, agentID string, skillTags map[string][]string, reasonerTags map[string][]string, approvedBy string) error { + agent, err := s.storage.GetAgent(ctx, agentID) + if err != nil { + return err + } + + if agent.LifecycleStatus != types.AgentStatusPendingApproval { + return fmt.Errorf("%w: agent %s (current status: %s)", ErrNotPendingApproval, agentID, agent.LifecycleStatus) + } + + for i := range agent.Reasoners { + if tags, ok := reasonerTags[agent.Reasoners[i].ID]; ok { + agent.Reasoners[i].ApprovedTags = tags + } + } + + for i := range agent.Skills { + if tags, ok := skillTags[agent.Skills[i].ID]; ok { + agent.Skills[i].ApprovedTags = tags + } + } + + // Collect all approved tags for the agent-level field + seen := make(map[string]struct{}) + var allApproved []string + for _, r := range agent.Reasoners { + for _, t := range r.ApprovedTags { + normalized := strings.ToLower(strings.TrimSpace(t)) + if _, exists := seen[normalized]; !exists { + seen[normalized] = struct{}{} + allApproved = append(allApproved, normalized) + } + } + } + for _, sk := range agent.Skills { + for _, t := range sk.ApprovedTags { + normalized := strings.ToLower(strings.TrimSpace(t)) + if _, exists := seen[normalized]; !exists { + seen[normalized] = struct{}{} + allApproved = append(allApproved, normalized) + } + } + } + + agent.ApprovedTags = allApproved + agent.LifecycleStatus = types.AgentStatusStarting + + if err := s.storage.RegisterAgent(ctx, agent); err != nil { + return err + } + + logger.Logger.Info(). + Str("agent_id", agentID). + Str("approved_by", approvedBy). + Msg("Agent tags approved (per-skill)") + + // Issue a signed Agent Tag VC (non-fatal on failure) + s.issueTagVC(ctx, agentID, allApproved, approvedBy) + + return nil +} + +// RejectAgentTags rejects an agent's proposed tags. +func (s *TagApprovalService) RejectAgentTags(ctx context.Context, agentID string, rejectedBy string, reason string) error { + agent, err := s.storage.GetAgent(ctx, agentID) + if err != nil { + return err + } + + if agent.LifecycleStatus != types.AgentStatusPendingApproval { + return fmt.Errorf("%w: agent %s (current status: %s)", ErrNotPendingApproval, agentID, agent.LifecycleStatus) + } + + agent.LifecycleStatus = types.AgentStatusOffline + agent.ApprovedTags = nil + + // Clear approved tags on all skills/reasoners + for i := range agent.Reasoners { + agent.Reasoners[i].ApprovedTags = nil + } + for i := range agent.Skills { + agent.Skills[i].ApprovedTags = nil + } + + if err := s.storage.RegisterAgent(ctx, agent); err != nil { + return err + } + + logger.Logger.Info(). + Str("agent_id", agentID). + Str("rejected_by", rejectedBy). + Str("reason", reason). + Msg("Agent tags rejected") + + return nil +} + +// RevokeAgentTags revokes an agent's approved tags, transitions it back to +// pending_approval, and revokes its tag VC. Works on agents in any lifecycle status. +func (s *TagApprovalService) RevokeAgentTags(ctx context.Context, agentID string, revokedBy string, reason string) error { + agent, err := s.storage.GetAgent(ctx, agentID) + if err != nil { + return err + } + + // Revoke the agent tag VC (non-fatal if no VC exists) + if err := s.storage.RevokeAgentTagVC(ctx, agentID); err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Failed to revoke agent tag VC (may not exist)") + } + + // Clear approved tags + agent.ApprovedTags = nil + for i := range agent.Reasoners { + agent.Reasoners[i].ApprovedTags = nil + } + for i := range agent.Skills { + agent.Skills[i].ApprovedTags = nil + } + agent.LifecycleStatus = types.AgentStatusPendingApproval + + if err := s.storage.RegisterAgent(ctx, agent); err != nil { + return err + } + + logger.Logger.Info(). + Str("agent_id", agentID). + Str("revoked_by", revokedBy). + Str("reason", reason). + Msg("Agent tags revoked") + + if s.onRevoke != nil { + s.onRevoke(ctx, agentID) + } + + return nil +} + +// ListPendingAgents returns all agents currently in pending_approval status. +func (s *TagApprovalService) ListPendingAgents(ctx context.Context) ([]*types.AgentNode, error) { + return s.storage.ListAgentsByLifecycleStatus(ctx, types.AgentStatusPendingApproval) +} + +// ProcessRegistrationTags evaluates tags at registration time and returns the result. +// The caller should use this to decide whether to set the agent to pending or auto-approve. +// +// If the agent already carries ApprovedTags (preserved from a previous registration), +// and the proposed tags haven't changed, the existing approval state is kept intact. +// This prevents forcing re-approval after every CP restart or agent reconnect. +func (s *TagApprovalService) ProcessRegistrationTags(agent *types.AgentNode) TagApprovalResult { + allProposed := CollectAllProposedTags(agent) + agent.ProposedTags = allProposed + + result := s.EvaluateTags(allProposed) + + // If the agent already has approved tags (re-registration), check whether the + // proposed tags are still covered by the existing approval. If so, keep the + // current approval state and don't force the agent back to pending_approval. + if len(agent.ApprovedTags) > 0 { + existingApproved := make(map[string]struct{}) + for _, t := range agent.ApprovedTags { + existingApproved[strings.ToLower(strings.TrimSpace(t))] = struct{}{} + } + + // Check that every manual-review tag is already approved. + allCovered := true + for _, t := range result.ManualReview { + if _, ok := existingApproved[strings.ToLower(strings.TrimSpace(t))]; !ok { + allCovered = false + break + } + } + + if allCovered { + // Existing approval still covers all proposed tags — keep it. + // Don't touch agent.ApprovedTags or agent.LifecycleStatus. + return result + } + + // Some new tags need approval. Only require approval for the new ones; + // keep previously-approved tags in the approved set. + for _, t := range result.AutoApproved { + existingApproved[strings.ToLower(strings.TrimSpace(t))] = struct{}{} + } + merged := make([]string, 0, len(existingApproved)) + for t := range existingApproved { + merged = append(merged, t) + } + agent.ApprovedTags = merged + agent.LifecycleStatus = types.AgentStatusPendingApproval + return result + } + + if result.AllAutoApproved { + // Auto-approve: set approved tags immediately + agent.ApprovedTags = result.AutoApproved + for i := range agent.Reasoners { + agent.Reasoners[i].ApprovedTags = agent.Reasoners[i].Tags + if len(agent.Reasoners[i].ApprovedTags) == 0 { + agent.Reasoners[i].ApprovedTags = agent.Reasoners[i].ProposedTags + } + } + for i := range agent.Skills { + agent.Skills[i].ApprovedTags = agent.Skills[i].Tags + if len(agent.Skills[i].ApprovedTags) == 0 { + agent.Skills[i].ApprovedTags = agent.Skills[i].ProposedTags + } + } + } else { + // Needs approval: only auto-approved tags are set + agent.ApprovedTags = result.AutoApproved + agent.LifecycleStatus = types.AgentStatusPendingApproval + } + + return result +} + +// IssueAutoApprovedTagsVC issues a Tag VC for auto-approved agents during registration. +// This must be called AFTER the agent is stored and DID is registered. +func (s *TagApprovalService) IssueAutoApprovedTagsVC(ctx context.Context, agentID string, approvedTags []string) { + s.issueTagVC(ctx, agentID, approvedTags, "system:auto-approved") +} + +// issueTagVC creates and stores a signed Agent Tag VC for an agent. +// This is non-fatal — if VC issuance fails, the tag approval still succeeds. +func (s *TagApprovalService) issueTagVC(ctx context.Context, agentID string, approvedTags []string, approvedBy string) { + s.mu.RLock() + vcSvc := s.vcService + s.mu.RUnlock() + if vcSvc == nil { + return + } + + // Get agent's DID + agentDIDInfo, err := s.storage.GetAgentDID(ctx, agentID) + if err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Cannot issue tag VC: agent DID not found") + return + } + + // Get control plane issuer DID + var issuerDID string + didService := vcSvc.GetDIDService() + if didService != nil { + if rootDID, err := didService.GetControlPlaneIssuerDID(); err == nil { + issuerDID = rootDID + } + } + if issuerDID == "" { + logger.Logger.Warn().Str("agent_id", agentID).Msg("Cannot issue tag VC: no issuer DID available") + return + } + + // Build the VC document + now := time.Now() + vcID := fmt.Sprintf("urn:agentfield:agent-tag-vc:%s", uuid.New().String()) + + vc := &types.AgentTagVCDocument{ + Context: []string{ + "https://www.w3.org/2018/credentials/v1", + }, + Type: []string{ + "VerifiableCredential", + "AgentTagCredential", + }, + ID: vcID, + Issuer: issuerDID, + IssuanceDate: now.Format(time.RFC3339), + CredentialSubject: types.AgentTagVCCredentialSubject{ + ID: agentDIDInfo.DID, + AgentID: agentID, + Permissions: types.AgentTagVCPermissions{ + Tags: approvedTags, + AllowedCallees: []string{"*"}, + }, + ApprovedBy: approvedBy, + ApprovedAt: now.Format(time.RFC3339), + }, + } + + // Sign the VC + proof, err := vcSvc.SignAgentTagVC(vc) + if err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Failed to sign agent tag VC") + return + } + vc.Proof = proof + + // Serialize the VC document + vcDocJSON, err := json.Marshal(vc) + if err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Failed to marshal agent tag VC") + return + } + + // Extract signature value for storage + signature := "" + if proof != nil { + signature = proof.ProofValue + } + + // Store the VC + if err := s.storage.StoreAgentTagVC(ctx, agentID, agentDIDInfo.DID, vcID, string(vcDocJSON), signature, now, nil); err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Failed to store agent tag VC") + return + } + + proofType := "none" + if proof != nil { + proofType = proof.Type + } + logger.Logger.Info(). + Str("agent_id", agentID). + Str("vc_id", vcID). + Str("proof_type", proofType). + Msg("Agent tag VC issued") +} + diff --git a/control-plane/internal/services/tag_approval_service_test.go b/control-plane/internal/services/tag_approval_service_test.go new file mode 100644 index 00000000..51dd2eaf --- /dev/null +++ b/control-plane/internal/services/tag_approval_service_test.go @@ -0,0 +1,522 @@ +package services + +import ( + "context" + "fmt" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/config" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mockTagApprovalStorage implements TagApprovalStorage for testing. +type mockTagApprovalStorage struct { + agents map[string]*types.AgentNode + agentDID map[string]*types.AgentDIDInfo + tagVCs map[string]*types.AgentTagVCRecord + + registerErr error +} + +func newMockTagApprovalStorage() *mockTagApprovalStorage { + return &mockTagApprovalStorage{ + agents: make(map[string]*types.AgentNode), + agentDID: make(map[string]*types.AgentDIDInfo), + tagVCs: make(map[string]*types.AgentTagVCRecord), + } +} + +func (m *mockTagApprovalStorage) GetAgent(_ context.Context, id string) (*types.AgentNode, error) { + agent, ok := m.agents[id] + if !ok { + return nil, fmt.Errorf("agent %s not found", id) + } + return agent, nil +} + +func (m *mockTagApprovalStorage) ListAgentVersions(_ context.Context, id string) ([]*types.AgentNode, error) { + // Mock returns nothing; tests use unversioned agents stored via GetAgent key + return nil, nil +} + +func (m *mockTagApprovalStorage) RegisterAgent(_ context.Context, node *types.AgentNode) error { + if m.registerErr != nil { + return m.registerErr + } + m.agents[node.ID] = node + return nil +} + +func (m *mockTagApprovalStorage) ListAgentsByLifecycleStatus(_ context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) { + var result []*types.AgentNode + for _, agent := range m.agents { + if agent.LifecycleStatus == status { + result = append(result, agent) + } + } + return result, nil +} + +func (m *mockTagApprovalStorage) GetAgentDID(_ context.Context, agentID string) (*types.AgentDIDInfo, error) { + info, ok := m.agentDID[agentID] + if !ok { + return nil, fmt.Errorf("DID not found for agent %s", agentID) + } + return info, nil +} + +func (m *mockTagApprovalStorage) StoreAgentTagVC(_ context.Context, agentID, agentDID, vcID, vcDocument, signature string, issuedAt time.Time, expiresAt *time.Time) error { + m.tagVCs[agentID] = &types.AgentTagVCRecord{ + AgentID: agentID, + AgentDID: agentDID, + VCID: vcID, + VCDocument: vcDocument, + Signature: signature, + IssuedAt: issuedAt, + ExpiresAt: expiresAt, + } + return nil +} + +func (m *mockTagApprovalStorage) RevokeAgentTagVC(_ context.Context, agentID string) error { + delete(m.tagVCs, agentID) + return nil +} + +func testApprovalConfig(rules ...config.TagApprovalRule) config.TagApprovalRulesConfig { + return config.TagApprovalRulesConfig{ + DefaultMode: "manual", + Rules: rules, + } +} + +// ============================================================================ +// EvaluateTags +// ============================================================================ + +func TestEvaluateTags_AutoApprovedTags(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"internal", "beta"}, Approval: "auto"}, + ), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"internal", "beta"}) + assert.Equal(t, []string{"internal", "beta"}, result.AutoApproved) + assert.Empty(t, result.ManualReview) + assert.Empty(t, result.Forbidden) + assert.True(t, result.AllAutoApproved) +} + +func TestEvaluateTags_ManualReviewTags(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"finance"}, Approval: "manual"}, + ), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"finance"}) + assert.Empty(t, result.AutoApproved) + assert.Equal(t, []string{"finance"}, result.ManualReview) + assert.False(t, result.AllAutoApproved) +} + +func TestEvaluateTags_ForbiddenTags(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"root", "superuser"}, Approval: "forbidden"}, + ), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"root"}) + assert.Empty(t, result.AutoApproved) + assert.Empty(t, result.ManualReview) + assert.Equal(t, []string{"root"}, result.Forbidden) + assert.False(t, result.AllAutoApproved) +} + +func TestEvaluateTags_MixedModes(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"internal"}, Approval: "auto"}, + config.TagApprovalRule{Tags: []string{"finance"}, Approval: "manual"}, + config.TagApprovalRule{Tags: []string{"root"}, Approval: "forbidden"}, + ), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"internal", "finance", "root"}) + assert.Equal(t, []string{"internal"}, result.AutoApproved) + assert.Equal(t, []string{"finance"}, result.ManualReview) + assert.Equal(t, []string{"root"}, result.Forbidden) + assert.False(t, result.AllAutoApproved) +} + +func TestEvaluateTags_DefaultModeFallback(t *testing.T) { + // Tags not in any rule should use the default mode + svc := NewTagApprovalService(config.TagApprovalRulesConfig{ + DefaultMode: "manual", + Rules: nil, + }, newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"unknown-tag"}) + assert.Equal(t, []string{"unknown-tag"}, result.ManualReview) + assert.False(t, result.AllAutoApproved) +} + +func TestEvaluateTags_DefaultModeAutoIfEmpty(t *testing.T) { + // If no default mode configured, defaults to "auto" + svc := NewTagApprovalService(config.TagApprovalRulesConfig{}, newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"any-tag"}) + assert.Equal(t, []string{"any-tag"}, result.AutoApproved) + assert.True(t, result.AllAutoApproved) +} + +func TestEvaluateTags_CaseInsensitive(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"Finance"}, Approval: "manual"}, + ), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"FINANCE"}) + assert.Equal(t, []string{"finance"}, result.ManualReview) +} + +func TestEvaluateTags_EmptyAndWhitespaceTags(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig(), newMockTagApprovalStorage()) + + result := svc.EvaluateTags([]string{"", " ", "valid"}) + // Empty/whitespace tags should be skipped; "valid" goes to default mode (manual) + assert.Equal(t, []string{"valid"}, result.ManualReview) + assert.Empty(t, result.AutoApproved) +} + +// ============================================================================ +// IsEnabled +// ============================================================================ + +func TestIsEnabled_WithRules(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"admin"}, Approval: "manual"}, + ), newMockTagApprovalStorage()) + assert.True(t, svc.IsEnabled()) +} + +func TestIsEnabled_WithNonAutoDefault(t *testing.T) { + svc := NewTagApprovalService(config.TagApprovalRulesConfig{ + DefaultMode: "manual", + }, newMockTagApprovalStorage()) + assert.True(t, svc.IsEnabled()) +} + +func TestIsEnabled_DefaultAutoNoRules(t *testing.T) { + svc := NewTagApprovalService(config.TagApprovalRulesConfig{}, newMockTagApprovalStorage()) + assert.False(t, svc.IsEnabled()) +} + +// ============================================================================ +// CollectAllProposedTags +// ============================================================================ + +func TestCollectAllProposedTags_FromReasonersAndSkills(t *testing.T) { + agent := &types.AgentNode{ + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", Tags: []string{"finance"}, ProposedTags: []string{"finance", "internal"}}, + {ID: "r2", Tags: []string{"billing"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", Tags: []string{"payment"}, ProposedTags: []string{"payment"}}, + }, + } + + tags := CollectAllProposedTags(agent) + // Should use ProposedTags when available, fall back to Tags + assert.Contains(t, tags, "finance") + assert.Contains(t, tags, "internal") + assert.Contains(t, tags, "billing") + assert.Contains(t, tags, "payment") +} + +func TestCollectAllProposedTags_DeduplicatesAndNormalizes(t *testing.T) { + agent := &types.AgentNode{ + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", ProposedTags: []string{"Finance", "internal"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"FINANCE", "payment"}}, + }, + } + + tags := CollectAllProposedTags(agent) + // "Finance" and "FINANCE" should deduplicate to one entry + finCount := 0 + for _, t := range tags { + if t == "finance" { + finCount++ + } + } + assert.Equal(t, 1, finCount, "should deduplicate case-insensitive tags") + assert.Len(t, tags, 3) // finance, internal, payment +} + +// ============================================================================ +// ApproveAgentTags +// ============================================================================ + +func TestApproveAgentTags_HappyPath(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"finance", "payment"}, + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", ProposedTags: []string{"finance"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"finance", "payment"}}, + }, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + + err := svc.ApproveAgentTags(context.Background(), "agent-1", []string{"finance", "payment"}, "admin-user") + require.NoError(t, err) + + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusStarting, agent.LifecycleStatus) + assert.Equal(t, []string{"finance", "payment"}, agent.ApprovedTags) + // Per-skill: reasoner r1 proposed ["finance"], approved set has "finance" → approved + assert.Equal(t, []string{"finance"}, agent.Reasoners[0].ApprovedTags) + // Skill s1 proposed ["finance", "payment"], both in approved set + assert.Equal(t, []string{"finance", "payment"}, agent.Skills[0].ApprovedTags) +} + +func TestApproveAgentTags_PartialApproval(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"finance", "admin"}, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"finance", "admin"}}, + }, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + + // Admin approves only "finance", not "admin" + err := svc.ApproveAgentTags(context.Background(), "agent-1", []string{"finance"}, "admin-user") + require.NoError(t, err) + + agent := storage.agents["agent-1"] + assert.Equal(t, []string{"finance"}, agent.ApprovedTags) + // Skill proposed ["finance", "admin"], only "finance" is in approved set + assert.Equal(t, []string{"finance"}, agent.Skills[0].ApprovedTags) +} + +func TestApproveAgentTags_NonPendingAgentFails(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + + err := svc.ApproveAgentTags(context.Background(), "agent-1", []string{"finance"}, "admin") + assert.Error(t, err) + assert.Contains(t, err.Error(), "not pending approval") +} + +func TestApproveAgentTags_AgentNotFoundFails(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig(), newMockTagApprovalStorage()) + err := svc.ApproveAgentTags(context.Background(), "nonexistent", []string{"finance"}, "admin") + assert.Error(t, err) +} + +// ============================================================================ +// ApproveAgentTagsPerSkill +// ============================================================================ + +func TestApproveAgentTagsPerSkill_HappyPath(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", ProposedTags: []string{"finance", "internal"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"payment"}}, + {ID: "s2", ProposedTags: []string{"billing"}}, + }, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + + err := svc.ApproveAgentTagsPerSkill(context.Background(), "agent-1", + map[string][]string{ + "s1": {"payment"}, + // s2 not approved + }, + map[string][]string{ + "r1": {"finance"}, // internal not approved + }, + "admin-user", + ) + require.NoError(t, err) + + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusStarting, agent.LifecycleStatus) + assert.Equal(t, []string{"finance"}, agent.Reasoners[0].ApprovedTags) + assert.Equal(t, []string{"payment"}, agent.Skills[0].ApprovedTags) + assert.Nil(t, agent.Skills[1].ApprovedTags) // s2 not in approval map + + // Agent-level approved tags = union of all per-skill approved tags + assert.Contains(t, agent.ApprovedTags, "finance") + assert.Contains(t, agent.ApprovedTags, "payment") +} + +func TestApproveAgentTagsPerSkill_NonPendingFails(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusReady, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + err := svc.ApproveAgentTagsPerSkill(context.Background(), "agent-1", nil, nil, "admin") + assert.Error(t, err) + assert.Contains(t, err.Error(), "not pending approval") +} + +// ============================================================================ +// RejectAgentTags +// ============================================================================ + +func TestRejectAgentTags_HappyPath(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusPendingApproval, + ProposedTags: []string{"root"}, + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", ProposedTags: []string{"root"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", ProposedTags: []string{"root"}}, + }, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + + err := svc.RejectAgentTags(context.Background(), "agent-1", "admin", "Forbidden tags") + require.NoError(t, err) + + agent := storage.agents["agent-1"] + assert.Equal(t, types.AgentStatusOffline, agent.LifecycleStatus) + assert.Nil(t, agent.ApprovedTags) + assert.Nil(t, agent.Reasoners[0].ApprovedTags) + assert.Nil(t, agent.Skills[0].ApprovedTags) +} + +func TestRejectAgentTags_NonPendingFails(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["agent-1"] = &types.AgentNode{ + ID: "agent-1", + LifecycleStatus: types.AgentStatusStarting, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + err := svc.RejectAgentTags(context.Background(), "agent-1", "admin", "reason") + assert.Error(t, err) + assert.Contains(t, err.Error(), "not pending approval") +} + +// ============================================================================ +// ListPendingAgents +// ============================================================================ + +func TestListPendingAgents_ReturnsOnlyPending(t *testing.T) { + storage := newMockTagApprovalStorage() + storage.agents["pending-1"] = &types.AgentNode{ + ID: "pending-1", + LifecycleStatus: types.AgentStatusPendingApproval, + } + storage.agents["ready-1"] = &types.AgentNode{ + ID: "ready-1", + LifecycleStatus: types.AgentStatusReady, + } + storage.agents["pending-2"] = &types.AgentNode{ + ID: "pending-2", + LifecycleStatus: types.AgentStatusPendingApproval, + } + + svc := NewTagApprovalService(testApprovalConfig(), storage) + agents, err := svc.ListPendingAgents(context.Background()) + require.NoError(t, err) + + assert.Len(t, agents, 2) + for _, a := range agents { + assert.Equal(t, types.AgentStatusPendingApproval, a.LifecycleStatus) + } +} + +// ============================================================================ +// ProcessRegistrationTags +// ============================================================================ + +func TestProcessRegistrationTags_AllAutoApproved(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"internal", "beta"}, Approval: "auto"}, + ), newMockTagApprovalStorage()) + + agent := &types.AgentNode{ + ID: "agent-1", + Reasoners: []types.ReasonerDefinition{ + {ID: "r1", Tags: []string{"internal"}}, + }, + Skills: []types.SkillDefinition{ + {ID: "s1", Tags: []string{"beta"}}, + }, + } + + result := svc.ProcessRegistrationTags(agent) + assert.True(t, result.AllAutoApproved) + assert.Equal(t, []string{"internal", "beta"}, agent.ProposedTags) + assert.Equal(t, []string{"internal", "beta"}, agent.ApprovedTags) + // Lifecycle status should NOT be set to pending + assert.NotEqual(t, types.AgentStatusPendingApproval, agent.LifecycleStatus) +} + +func TestProcessRegistrationTags_NeedsApproval(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"internal"}, Approval: "auto"}, + config.TagApprovalRule{Tags: []string{"finance"}, Approval: "manual"}, + ), newMockTagApprovalStorage()) + + agent := &types.AgentNode{ + ID: "agent-1", + Skills: []types.SkillDefinition{ + {ID: "s1", Tags: []string{"internal", "finance"}}, + }, + } + + result := svc.ProcessRegistrationTags(agent) + assert.False(t, result.AllAutoApproved) + assert.Equal(t, types.AgentStatusPendingApproval, agent.LifecycleStatus) + // Only auto-approved tags should be set + assert.Equal(t, []string{"internal"}, agent.ApprovedTags) +} + +func TestProcessRegistrationTags_ForbiddenTagBlocksApproval(t *testing.T) { + svc := NewTagApprovalService(testApprovalConfig( + config.TagApprovalRule{Tags: []string{"root"}, Approval: "forbidden"}, + ), newMockTagApprovalStorage()) + + agent := &types.AgentNode{ + ID: "agent-1", + Skills: []types.SkillDefinition{ + {ID: "s1", Tags: []string{"root"}}, + }, + } + + result := svc.ProcessRegistrationTags(agent) + assert.False(t, result.AllAutoApproved) + assert.Equal(t, []string{"root"}, result.Forbidden) + assert.Equal(t, types.AgentStatusPendingApproval, agent.LifecycleStatus) +} diff --git a/control-plane/internal/services/tag_normalization.go b/control-plane/internal/services/tag_normalization.go new file mode 100644 index 00000000..a4affc4d --- /dev/null +++ b/control-plane/internal/services/tag_normalization.go @@ -0,0 +1,69 @@ +package services + +import ( + "strings" + + "github.com/Agent-Field/agentfield/control-plane/pkg/types" +) + +// CanonicalAgentTags returns normalized plain tags for permission matching. +// Canonical tags are lowercased, trimmed, plain values (e.g. "admin"). +func CanonicalAgentTags(agent *types.AgentNode) []string { + if agent == nil { + return nil + } + + seen := make(map[string]struct{}) + tags := make([]string, 0) + + add := func(tag string) { + normalized := normalizeTag(tag) + if normalized == "" { + return + } + if _, exists := seen[normalized]; exists { + return + } + seen[normalized] = struct{}{} + tags = append(tags, normalized) + } + + // NOTE: Deployment metadata tags (agent.Metadata.Deployment.Tags) and + // agent.DeploymentType are excluded from canonical authorization tags because + // they are self-asserted at registration time and NOT subject to the tag + // approval workflow. Including them would allow agents to self-assign + // authorization-relevant tags. + + for _, reasoner := range agent.Reasoners { + // Prefer approved tags over raw tags for canonical matching + sourceTags := reasoner.Tags + if len(reasoner.ApprovedTags) > 0 { + sourceTags = reasoner.ApprovedTags + } + for _, tag := range sourceTags { + add(tag) + } + } + + for _, skill := range agent.Skills { + // Prefer approved tags over raw tags for canonical matching + sourceTags := skill.Tags + if len(skill.ApprovedTags) > 0 { + sourceTags = skill.ApprovedTags + } + for _, tag := range sourceTags { + add(tag) + } + } + + // Include agent-level approved tags + for _, tag := range agent.ApprovedTags { + add(tag) + } + + return tags +} + +func normalizeTag(tag string) string { + return strings.ToLower(strings.TrimSpace(tag)) +} diff --git a/control-plane/internal/services/tag_vc_verifier.go b/control-plane/internal/services/tag_vc_verifier.go new file mode 100644 index 00000000..c786c489 --- /dev/null +++ b/control-plane/internal/services/tag_vc_verifier.go @@ -0,0 +1,77 @@ +package services + +import ( + "context" + "encoding/json" + "fmt" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/logger" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" +) + +// TagVCStorage defines the storage operations needed by the tag VC verifier. +type TagVCStorage interface { + GetAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCRecord, error) +} + +// TagVCVerifier loads and verifies Agent Tag VCs at call time. +type TagVCVerifier struct { + storage TagVCStorage + vcService *VCService +} + +// NewTagVCVerifier creates a new tag VC verifier. +func NewTagVCVerifier(storage TagVCStorage, vcService *VCService) *TagVCVerifier { + return &TagVCVerifier{ + storage: storage, + vcService: vcService, + } +} + +// VerifyAgentTagVC loads an agent's tag VC from storage, verifies the signature, +// checks expiration/revocation, and returns the parsed VC document. +func (v *TagVCVerifier) VerifyAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCDocument, error) { + // Load VC record from storage + record, err := v.storage.GetAgentTagVC(ctx, agentID) + if err != nil { + return nil, fmt.Errorf("no tag VC for agent %s: %w", agentID, err) + } + + // Check revocation + if record.RevokedAt != nil { + return nil, fmt.Errorf("tag VC for agent %s was revoked at %s", agentID, record.RevokedAt.Format(time.RFC3339)) + } + + // Check expiration + if record.ExpiresAt != nil && record.ExpiresAt.Before(time.Now()) { + return nil, fmt.Errorf("tag VC for agent %s expired at %s", agentID, record.ExpiresAt.Format(time.RFC3339)) + } + + // Parse VC document + var vc types.AgentTagVCDocument + if err := json.Unmarshal([]byte(record.VCDocument), &vc); err != nil { + return nil, fmt.Errorf("failed to parse tag VC document for agent %s: %w", agentID, err) + } + + // Verify Ed25519 signature — vcService is required for signature verification + if v.vcService == nil { + return nil, fmt.Errorf("cannot verify tag VC for agent %s: VC service not available", agentID) + } + + valid, err := v.vcService.VerifyAgentTagVCSignature(&vc) + if err != nil { + logger.Logger.Warn().Err(err).Str("agent_id", agentID).Msg("Tag VC signature verification failed") + return nil, fmt.Errorf("tag VC signature verification failed for agent %s: %w", agentID, err) + } + if !valid { + return nil, fmt.Errorf("tag VC signature is invalid for agent %s", agentID) + } + + // Validate issuer-subject binding: the VC's agent ID must match the requested agent + if vc.CredentialSubject.AgentID != "" && vc.CredentialSubject.AgentID != agentID { + return nil, fmt.Errorf("tag VC subject mismatch: VC is for agent %s but verification requested for %s", vc.CredentialSubject.AgentID, agentID) + } + + return &vc, nil +} diff --git a/control-plane/internal/services/tag_vc_verifier_test.go b/control-plane/internal/services/tag_vc_verifier_test.go new file mode 100644 index 00000000..227f6114 --- /dev/null +++ b/control-plane/internal/services/tag_vc_verifier_test.go @@ -0,0 +1,179 @@ +package services + +import ( + "context" + "encoding/json" + "fmt" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/stretchr/testify/assert" +) + +// mockTagVCStorage implements TagVCStorage for testing. +type mockTagVCStorage struct { + records map[string]*types.AgentTagVCRecord +} + +func newMockTagVCStorage() *mockTagVCStorage { + return &mockTagVCStorage{records: make(map[string]*types.AgentTagVCRecord)} +} + +func (m *mockTagVCStorage) GetAgentTagVC(_ context.Context, agentID string) (*types.AgentTagVCRecord, error) { + r, ok := m.records[agentID] + if !ok { + return nil, fmt.Errorf("no tag VC for agent %s", agentID) + } + return r, nil +} + +func validVCDocument(agentID, agentDID string) string { + vc := types.AgentTagVCDocument{ + Context: []string{"https://www.w3.org/2018/credentials/v1"}, + Type: []string{"VerifiableCredential", "AgentTagCredential"}, + ID: "urn:agentfield:test-vc", + Issuer: "did:web:localhost:admin", + IssuanceDate: time.Now().Format(time.RFC3339), + CredentialSubject: types.AgentTagVCCredentialSubject{ + ID: agentDID, + AgentID: agentID, + Permissions: types.AgentTagVCPermissions{ + Tags: []string{"finance"}, + AllowedCallees: []string{"*"}, + }, + }, + } + b, _ := json.Marshal(vc) + return string(b) +} + +func TestVerifyAgentTagVC_StorageError(t *testing.T) { + storage := newMockTagVCStorage() + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "nonexistent") + assert.Error(t, err) + assert.Contains(t, err.Error(), "no tag VC for agent") +} + +func TestVerifyAgentTagVC_RevokedVC(t *testing.T) { + storage := newMockTagVCStorage() + revokedAt := time.Now().Add(-1 * time.Hour) + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: validVCDocument("agent-1", "did:web:test"), + RevokedAt: &revokedAt, + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + assert.Error(t, err) + assert.Contains(t, err.Error(), "revoked") +} + +func TestVerifyAgentTagVC_ExpiredVC(t *testing.T) { + storage := newMockTagVCStorage() + expired := time.Now().Add(-24 * time.Hour) + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: validVCDocument("agent-1", "did:web:test"), + ExpiresAt: &expired, + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + assert.Error(t, err) + assert.Contains(t, err.Error(), "expired") +} + +func TestVerifyAgentTagVC_NotYetExpired(t *testing.T) { + // VC with future expiry should pass the expiration check (but still fail on + // nil vcService — that's expected and tested separately) + storage := newMockTagVCStorage() + future := time.Now().Add(24 * time.Hour) + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: validVCDocument("agent-1", "did:web:test"), + ExpiresAt: &future, + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + // Should NOT fail on expiration — should fail on nil vcService instead + assert.Error(t, err) + assert.NotContains(t, err.Error(), "expired") + assert.Contains(t, err.Error(), "VC service not available") +} + +func TestVerifyAgentTagVC_MalformedJSON(t *testing.T) { + storage := newMockTagVCStorage() + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: "not valid json{{{", + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + assert.Error(t, err) + assert.Contains(t, err.Error(), "failed to parse tag VC document") +} + +func TestVerifyAgentTagVC_NilVCServiceFails(t *testing.T) { + storage := newMockTagVCStorage() + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: validVCDocument("agent-1", "did:web:test"), + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + assert.Error(t, err) + assert.Contains(t, err.Error(), "VC service not available") +} + +func TestVerifyAgentTagVC_SubjectMismatch(t *testing.T) { + // VC issued for agent-1 but verification requested for agent-2 + // This test covers the subject binding check AFTER signature verification. + // Since we can't easily mock VCService (concrete type), we test this path + // indirectly — the check happens after vcService.VerifyAgentTagVCSignature. + // We verify the error message is correct for mismatch detection. + storage := newMockTagVCStorage() + // Store a VC that claims to be for "agent-1" + storage.records["agent-2"] = &types.AgentTagVCRecord{ + AgentID: "agent-2", + VCDocument: validVCDocument("agent-1", "did:web:test"), // VC says agent_id=agent-1 + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-2") + // Will fail at vcService check before reaching subject mismatch, + // but the flow is correct — nil vcService blocks forged VCs + assert.Error(t, err) + assert.Contains(t, err.Error(), "VC service not available") +} + +func TestVerifyAgentTagVC_NoExpirationIsValid(t *testing.T) { + // VC with nil ExpiresAt should pass expiration check + storage := newMockTagVCStorage() + storage.records["agent-1"] = &types.AgentTagVCRecord{ + AgentID: "agent-1", + VCDocument: validVCDocument("agent-1", "did:web:test"), + ExpiresAt: nil, // No expiration + } + + verifier := NewTagVCVerifier(storage, nil) + + _, err := verifier.VerifyAgentTagVC(context.Background(), "agent-1") + // Should pass revocation and expiration, fail only at vcService + assert.Error(t, err) + assert.NotContains(t, err.Error(), "expired") + assert.NotContains(t, err.Error(), "revoked") + assert.Contains(t, err.Error(), "VC service not available") +} diff --git a/control-plane/internal/services/vc_service.go b/control-plane/internal/services/vc_service.go index 84fe0aaa..94242a5b 100644 --- a/control-plane/internal/services/vc_service.go +++ b/control-plane/internal/services/vc_service.go @@ -14,6 +14,7 @@ import ( "github.com/Agent-Field/agentfield/control-plane/internal/logger" "github.com/Agent-Field/agentfield/control-plane/internal/storage" "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/google/uuid" ) // VCService handles verifiable credential generation, verification, and management. @@ -160,8 +161,16 @@ func (s *VCService) GenerateExecutionVC(ctx *types.ExecutionContext, inputData, processedErrorMessage = &msg } - // Resolve caller DID - callerIdentity, err := s.didService.ResolveDID(ctx.CallerDID) + // Resolve caller DID — fall back to agent's own DID for anonymous/external callers + callerDID := ctx.CallerDID + if callerDID == "" { + callerDID = ctx.AgentNodeDID + } + if callerDID == "" { + // No DID available at all — skip VC generation gracefully + return nil, nil + } + callerIdentity, err := s.didService.ResolveDID(callerDID) if err != nil { return nil, fmt.Errorf("failed to resolve caller DID: %w", err) } @@ -193,7 +202,7 @@ func (s *VCService) GenerateExecutionVC(ctx *types.ExecutionContext, inputData, vcDoc.Proof = types.VCProof{ Type: "Ed25519Signature2020", Created: time.Now().UTC().Format(time.RFC3339), - VerificationMethod: fmt.Sprintf("%s#key-1", ctx.CallerDID), + VerificationMethod: fmt.Sprintf("%s#key-1", callerDID), ProofPurpose: "assertionMethod", ProofValue: signature, } @@ -213,9 +222,9 @@ func (s *VCService) GenerateExecutionVC(ctx *types.ExecutionContext, inputData, ExecutionID: ctx.ExecutionID, WorkflowID: ctx.WorkflowID, SessionID: ctx.SessionID, - IssuerDID: ctx.CallerDID, + IssuerDID: callerDID, TargetDID: ctx.TargetDID, - CallerDID: ctx.CallerDID, + CallerDID: callerDID, VCDocument: json.RawMessage(vcDocBytes), Signature: signature, StorageURI: "", @@ -344,13 +353,21 @@ func (s *VCService) CreateWorkflowVC(workflowID, sessionID string, executionVCID return nil, fmt.Errorf("DID system is disabled") } + // Derive start time from the first execution VC if available. + startTime := time.Now() + if len(executionVCIDs) > 0 { + if firstVC, err := s.vcStorage.GetExecutionVC(executionVCIDs[0]); err == nil { + startTime = firstVC.CreatedAt + } + } + workflowVC := &types.WorkflowVC{ WorkflowID: workflowID, SessionID: sessionID, ComponentVCs: executionVCIDs, WorkflowVCID: s.generateVCID(), Status: string(types.ExecutionStatusSucceeded), - StartTime: time.Now(), // TODO: Get actual start time from first execution + StartTime: startTime, EndTime: &[]time.Time{time.Now()}[0], TotalSteps: len(executionVCIDs), CompletedSteps: len(executionVCIDs), @@ -458,6 +475,10 @@ func (s *VCService) signVC(vcDoc *types.VCDocument, callerIdentity *types.DIDIde return "", fmt.Errorf("failed to decode private key seed: %w", err) } + if len(privateKeySeed) != ed25519.SeedSize { + return "", fmt.Errorf("invalid private key seed length: got %d, want %d", len(privateKeySeed), ed25519.SeedSize) + } + privateKey := ed25519.NewKeyFromSeed(privateKeySeed) // Sign the canonical representation @@ -466,6 +487,105 @@ func (s *VCService) signVC(vcDoc *types.VCDocument, callerIdentity *types.DIDIde return base64.RawURLEncoding.EncodeToString(signature), nil } +// SignAgentTagVC signs an AgentTagVCDocument using the control plane's issuer DID. +// Returns the signed proof to be set on the VC document. +func (s *VCService) SignAgentTagVC(vc *types.AgentTagVCDocument) (*types.VCProof, error) { + // Resolve the issuer's identity (control plane DID) + issuerIdentity, err := s.didService.ResolveDID(vc.Issuer) + if err != nil { + return nil, fmt.Errorf("cannot resolve issuer DID %s for agent tag VC signing: %w", vc.Issuer, err) + } + + // Create canonical representation (without proof) for signing + vcCopy := *vc + vcCopy.Proof = nil + canonicalBytes, err := json.Marshal(vcCopy) + if err != nil { + return nil, fmt.Errorf("failed to marshal agent tag VC for signing: %w", err) + } + + // Parse private key from JWK + var jwk map[string]interface{} + if err := json.Unmarshal([]byte(issuerIdentity.PrivateKeyJWK), &jwk); err != nil { + return nil, fmt.Errorf("failed to parse issuer private key JWK: %w", err) + } + + dValue, ok := jwk["d"].(string) + if !ok { + return nil, fmt.Errorf("invalid issuer private key JWK: missing 'd' parameter") + } + + privateKeySeed, err := base64.RawURLEncoding.DecodeString(dValue) + if err != nil { + return nil, fmt.Errorf("failed to decode issuer private key seed: %w", err) + } + + if len(privateKeySeed) != ed25519.SeedSize { + return nil, fmt.Errorf("invalid issuer private key seed length: got %d, want %d", len(privateKeySeed), ed25519.SeedSize) + } + + privateKey := ed25519.NewKeyFromSeed(privateKeySeed) + signature := ed25519.Sign(privateKey, canonicalBytes) + + return &types.VCProof{ + Type: "Ed25519Signature2020", + Created: time.Now().UTC().Format(time.RFC3339), + VerificationMethod: fmt.Sprintf("%s#key-1", vc.Issuer), + ProofPurpose: "assertionMethod", + ProofValue: base64.RawURLEncoding.EncodeToString(signature), + }, nil +} + +// VerifyAgentTagVCSignature verifies the Ed25519 signature on an AgentTagVCDocument. +func (s *VCService) VerifyAgentTagVCSignature(vc *types.AgentTagVCDocument) (bool, error) { + if vc.Proof == nil || vc.Proof.ProofValue == "" || vc.Proof.Type == "UnsignedAuditRecord" { + return false, fmt.Errorf("VC has no valid signature") + } + + // Resolve issuer identity + issuerIdentity, err := s.didService.ResolveDID(vc.Issuer) + if err != nil { + return false, fmt.Errorf("cannot resolve issuer DID %s: %w", vc.Issuer, err) + } + + // Create canonical representation (without proof) + vcCopy := *vc + vcCopy.Proof = nil + canonicalBytes, err := json.Marshal(vcCopy) + if err != nil { + return false, fmt.Errorf("failed to marshal agent tag VC for verification: %w", err) + } + + // Decode signature + signatureBytes, err := base64.RawURLEncoding.DecodeString(vc.Proof.ProofValue) + if err != nil { + return false, fmt.Errorf("failed to decode signature: %w", err) + } + + // Parse public key from JWK + var jwk map[string]interface{} + if err := json.Unmarshal([]byte(issuerIdentity.PublicKeyJWK), &jwk); err != nil { + return false, fmt.Errorf("failed to parse issuer public key JWK: %w", err) + } + + xValue, ok := jwk["x"].(string) + if !ok { + return false, fmt.Errorf("invalid issuer public key JWK: missing 'x' parameter") + } + + publicKeyBytes, err := base64.RawURLEncoding.DecodeString(xValue) + if err != nil { + return false, fmt.Errorf("failed to decode public key: %w", err) + } + + if len(publicKeyBytes) != ed25519.PublicKeySize { + return false, fmt.Errorf("invalid public key length: got %d, want %d", len(publicKeyBytes), ed25519.PublicKeySize) + } + + publicKey := ed25519.PublicKey(publicKeyBytes) + return ed25519.Verify(publicKey, canonicalBytes, signatureBytes), nil +} + // verifyVCSignature verifies the signature of a VC document. func (s *VCService) verifyVCSignature(vcDoc *types.VCDocument, issuerIdentity *types.DIDIdentity) (bool, error) { // Create canonical representation for verification @@ -493,6 +613,10 @@ func (s *VCService) verifyVCSignature(vcDoc *types.VCDocument, issuerIdentity *t return false, fmt.Errorf("failed to decode public key: %w", err) } + if len(publicKeyBytes) != ed25519.PublicKeySize { + return false, fmt.Errorf("invalid public key length: got %d, want %d", len(publicKeyBytes), ed25519.PublicKeySize) + } + publicKey := ed25519.PublicKey(publicKeyBytes) // Decode signature @@ -515,11 +639,9 @@ func (s *VCService) hashData(data []byte) string { return base64.RawURLEncoding.EncodeToString(hash[:]) } -// generateVCID generates a unique VC ID. +// generateVCID generates a unique VC ID using a cryptographically random UUID. func (s *VCService) generateVCID() string { - // Simple UUID-like generation for now - // In production, use proper UUID library - return fmt.Sprintf("vc-%d", time.Now().UnixNano()) + return fmt.Sprintf("vc-%s", uuid.New().String()) } // generateWorkflowVCDocument creates a WorkflowVC document on-demand. @@ -710,6 +832,10 @@ func (s *VCService) signWorkflowVC(vcDoc *types.WorkflowVCDocument, issuerIdenti return "", fmt.Errorf("failed to decode private key seed: %w", err) } + if len(privateKeySeed) != ed25519.SeedSize { + return "", fmt.Errorf("invalid private key seed length: got %d, want %d", len(privateKeySeed), ed25519.SeedSize) + } + privateKey := ed25519.NewKeyFromSeed(privateKeySeed) // Sign the canonical representation @@ -807,6 +933,14 @@ func (s *VCService) ListWorkflowVCs() ([]*types.WorkflowVC, error) { return s.vcStorage.ListWorkflowVCs() } +// ListAgentTagVCs returns all non-revoked agent tag VCs. +func (s *VCService) ListAgentTagVCs() ([]*types.AgentTagVCRecord, error) { + if !s.config.Enabled { + return nil, fmt.Errorf("DID system is disabled") + } + return s.vcStorage.ListAgentTagVCs(context.Background()) +} + // collectDIDResolutionBundle collects all unique DIDs from the VC chain and resolves their public keys. func (s *VCService) collectDIDResolutionBundle(executionVCs []types.ExecutionVC, workflowVC *types.WorkflowVC) (map[string]types.DIDResolutionEntry, error) { bundle := make(map[string]types.DIDResolutionEntry) @@ -1613,6 +1747,10 @@ func (s *VCService) verifyWorkflowVCSignature(vcDoc *types.WorkflowVCDocument, i return false, fmt.Errorf("failed to decode public key: %w", err) } + if len(publicKeyBytes) != ed25519.PublicKeySize { + return false, fmt.Errorf("invalid public key length: got %d, want %d", len(publicKeyBytes), ed25519.PublicKeySize) + } + publicKey := ed25519.PublicKey(publicKeyBytes) // Decode signature diff --git a/control-plane/internal/services/vc_service_test.go b/control-plane/internal/services/vc_service_test.go index 1aa20375..6b270011 100644 --- a/control-plane/internal/services/vc_service_test.go +++ b/control-plane/internal/services/vc_service_test.go @@ -430,12 +430,14 @@ func TestVCService_VerifyVC_Success(t *testing.T) { func TestVCService_VerifyVC_InvalidDocument(t *testing.T) { vcService, _, _, _ := setupVCTestEnvironment(t) + // Valid JSON but missing VC fields - parses into empty VCDocument struct, + // then fails when trying to resolve the empty issuer DID invalidDoc := json.RawMessage(`{"invalid": "json"}`) verifyResp, err := vcService.VerifyVC(invalidDoc) require.NoError(t, err) require.NotNil(t, verifyResp) require.False(t, verifyResp.Valid) - require.Contains(t, verifyResp.Error, "failed to parse VC document") + require.Contains(t, verifyResp.Error, "failed to resolve issuer DID") } func TestVCService_VerifyVC_DisabledSystem(t *testing.T) { @@ -687,8 +689,8 @@ func TestVCService_CreateWorkflowVC_Success(t *testing.T) { require.Equal(t, 2, workflowVC.CompletedSteps) require.NotEmpty(t, workflowVC.WorkflowVCID) - // Verify workflow VC was stored - storedVC, err := provider.GetWorkflowVC(ctx, "workflow-1") + // Verify workflow VC was stored - GetWorkflowVC looks up by workflow_vc_id, not workflow_id + storedVC, err := provider.GetWorkflowVC(ctx, workflowVC.WorkflowVCID) require.NoError(t, err) require.NotNil(t, storedVC) require.Equal(t, workflowVC.WorkflowVCID, storedVC.WorkflowVCID) @@ -991,15 +993,25 @@ func TestVCService_VerifyExecutionVCComprehensive_IssuerMismatch(t *testing.T) { require.NoError(t, err) require.NotNil(t, storedVC) - // Tamper with issuer DID - create a new VC with tampered issuer + // Tamper with the VCDocument JSON to change the issuer field inside it. + // The SQL upsert only updates vc_document (not issuer_did metadata), so we + // must modify the JSON document to create a mismatch between the stored + // metadata issuer_did and the issuer field inside the VC document. + var vcDoc types.VCDocument + require.NoError(t, json.Unmarshal(storedVC.VCDocument, &vcDoc)) + vcDoc.Issuer = "did:key:tampered" + tamperedDocBytes, err := json.Marshal(vcDoc) + require.NoError(t, err) + tamperedVC := *storedVC - tamperedVC.IssuerDID = "did:key:tampered" + tamperedVC.VCDocument = tamperedDocBytes - // Store tampered VC using vcStorage + // Store tampered VC using vcStorage - the upsert updates vc_document but + // preserves the original issuer_did in metadata, creating the mismatch err = vcService.vcStorage.StoreExecutionVC(ctx, &tamperedVC) require.NoError(t, err) - // Verify - should detect issuer mismatch + // Verify - should detect issuer mismatch between metadata and VC document result, err := vcService.VerifyExecutionVCComprehensive("exec-mismatch") require.NoError(t, err) require.NotNil(t, result) @@ -1141,6 +1153,58 @@ func TestVCService_DetermineWorkflowStatus_AllSucceeded(t *testing.T) { require.Len(t, chain.ComponentVCs, 3) } +func TestVCService_GenerateExecutionVC_EmptyCallerDID_FallsBackToAgentDID(t *testing.T) { + vcService, didService, _, _ := setupVCTestEnvironment(t) + + // Register an agent + req := &types.DIDRegistrationRequest{ + AgentNodeID: "agent-empty-caller", + Reasoners: []types.ReasonerDefinition{{ID: "reasoner1"}}, + } + + regResp, err := didService.RegisterAgent(req) + require.NoError(t, err) + require.True(t, regResp.Success) + + agentDID := regResp.IdentityPackage.AgentDID.DID + + // Empty CallerDID — should fall back to AgentNodeDID + execCtx := &types.ExecutionContext{ + ExecutionID: "exec-empty-caller", + WorkflowID: "workflow-1", + SessionID: "session-1", + CallerDID: "", + TargetDID: "", + AgentNodeDID: agentDID, + Timestamp: time.Now(), + } + + vc, err := vcService.GenerateExecutionVC(execCtx, []byte(`{"input": "test"}`), []byte(`{"output": "result"}`), "succeeded", nil, 100) + require.NoError(t, err) + require.NotNil(t, vc, "VC should be generated using agent's own DID as fallback") + require.Equal(t, agentDID, vc.CallerDID) + require.Equal(t, agentDID, vc.IssuerDID) +} + +func TestVCService_GenerateExecutionVC_BothDIDsEmpty_ReturnsNil(t *testing.T) { + vcService, _, _, _ := setupVCTestEnvironment(t) + + // Both CallerDID and AgentNodeDID are empty — should return nil gracefully + execCtx := &types.ExecutionContext{ + ExecutionID: "exec-no-did", + WorkflowID: "workflow-1", + SessionID: "session-1", + CallerDID: "", + TargetDID: "", + AgentNodeDID: "", + Timestamp: time.Now(), + } + + vc, err := vcService.GenerateExecutionVC(execCtx, []byte(`{"input": "test"}`), []byte(`{"output": "result"}`), "succeeded", nil, 100) + require.NoError(t, err) + require.Nil(t, vc, "VC generation should be skipped when no DID is available") +} + // Helper function func stringPtr(s string) *string { return &s diff --git a/control-plane/internal/services/vc_storage.go b/control-plane/internal/services/vc_storage.go index 3d369abb..ad29ac56 100644 --- a/control-plane/internal/services/vc_storage.go +++ b/control-plane/internal/services/vc_storage.go @@ -188,6 +188,14 @@ func (s *VCStorage) ListWorkflowVCs() ([]*types.WorkflowVC, error) { return results, nil } +// ListAgentTagVCs returns all non-revoked agent tag VCs. +func (s *VCStorage) ListAgentTagVCs(ctx context.Context) ([]*types.AgentTagVCRecord, error) { + if s.storageProvider == nil { + return nil, fmt.Errorf("no storage provider configured for VC storage") + } + return s.storageProvider.ListAgentTagVCs(ctx) +} + // DeleteExecutionVC is currently a no-op placeholder. func (s *VCStorage) DeleteExecutionVC(vcID string) error { logger.Logger.Debug().Str("vc_id", vcID).Msg("DeleteExecutionVC is not implemented - skipping") diff --git a/control-plane/internal/services/vc_storage_test.go b/control-plane/internal/services/vc_storage_test.go index b08716b8..71059a4e 100644 --- a/control-plane/internal/services/vc_storage_test.go +++ b/control-plane/internal/services/vc_storage_test.go @@ -328,8 +328,8 @@ func TestVCStorage_StoreWorkflowVC_Success(t *testing.T) { err := vcStorage.StoreWorkflowVC(ctx, workflowVC) require.NoError(t, err) - // Verify workflow VC was stored - storedVC, err := provider.GetWorkflowVC(ctx, "workflow-store") + // Verify workflow VC was stored - GetWorkflowVC looks up by workflow_vc_id + storedVC, err := provider.GetWorkflowVC(ctx, "workflow-vc-store") require.NoError(t, err) require.NotNil(t, storedVC) require.Equal(t, workflowVC.WorkflowVCID, storedVC.WorkflowVCID) @@ -372,8 +372,8 @@ func TestVCStorage_StoreWorkflowVC_AutoSizeCalculation(t *testing.T) { err := vcStorage.StoreWorkflowVC(ctx, workflowVC) require.NoError(t, err) - // Verify size was calculated - storedVC, err := provider.GetWorkflowVC(ctx, "workflow-auto-size") + // Verify size was calculated - GetWorkflowVC looks up by workflow_vc_id + storedVC, err := provider.GetWorkflowVC(ctx, "workflow-vc-auto") require.NoError(t, err) require.Equal(t, int64(len(vcDocBytes)), storedVC.DocumentSize) } @@ -482,10 +482,10 @@ func TestVCStorage_ListWorkflowVCStatusSummaries(t *testing.T) { require.NoError(t, err) require.Empty(t, summaries) - // Test with workflow IDs + // Test with workflow IDs that don't exist in storage - should return empty, no error summaries, err = vcStorage.ListWorkflowVCStatusSummaries(ctx, []string{"workflow-1", "workflow-2"}) require.NoError(t, err) - require.NotNil(t, summaries) + require.Empty(t, summaries) } func TestVCStorage_ListWorkflowVCStatusSummaries_NilProvider(t *testing.T) { diff --git a/control-plane/internal/storage/execution_records_test.go b/control-plane/internal/storage/execution_records_test.go index b1167263..6ce16bb4 100644 --- a/control-plane/internal/storage/execution_records_test.go +++ b/control-plane/internal/storage/execution_records_test.go @@ -55,7 +55,10 @@ func TestQueryRunSummariesParsesTextTimestamps(t *testing.T) { require.False(t, summary.EarliestStarted.IsZero(), "earliest started should be parsed from TEXT timestamps") require.False(t, summary.LatestStarted.IsZero(), "latest started should be parsed from TEXT timestamps") require.Equal(t, summary.EarliestStarted, base.Add(-3*time.Minute)) - require.Equal(t, summary.LatestStarted, base.Add(-1*time.Minute)) + // LatestStarted comes from MAX(COALESCE(updated_at, started_at)). + // CreateExecutionRecord always overwrites updated_at with time.Now(), + // so LatestStarted will be approximately now, not the test's started_at. + require.True(t, summary.LatestStarted.After(base), "latest started should be after the test base time") } func pointerTime(t time.Time) *time.Time { diff --git a/control-plane/internal/storage/execution_webhooks.go b/control-plane/internal/storage/execution_webhooks.go index 1f24183b..7c605113 100644 --- a/control-plane/internal/storage/execution_webhooks.go +++ b/control-plane/internal/storage/execution_webhooks.go @@ -59,7 +59,7 @@ func (ls *LocalStorage) RegisterExecutionWebhook(ctx context.Context, webhook *t last_attempt_at = excluded.last_attempt_at, last_error = excluded.last_error, updated_at = excluded.updated_at - `, webhook.ExecutionID, webhook.URL, secret, headersJSON, types.ExecutionWebhookStatusPending, nextAttempt, now, now) + `, webhook.ExecutionID, webhook.URL, secret, headersJSON, webhook.Status, nextAttempt, now, now) if err != nil { return fmt.Errorf("register execution webhook: %w", err) } diff --git a/control-plane/internal/storage/execution_webhooks_test.go b/control-plane/internal/storage/execution_webhooks_test.go index 386e2bd7..b1fbcd94 100644 --- a/control-plane/internal/storage/execution_webhooks_test.go +++ b/control-plane/internal/storage/execution_webhooks_test.go @@ -286,10 +286,11 @@ func TestListDueExecutionWebhooks_Limit(t *testing.T) { func TestListDueExecutionWebhooks_DefaultLimit(t *testing.T) { provider, ctx := setupTestStorage(t) - // Pass zero limit to test default + // Pass zero limit to test default - should not error even with no webhooks webhooks, err := provider.ListDueExecutionWebhooks(ctx, 0) require.NoError(t, err) - assert.NotNil(t, webhooks) + // No webhooks registered, so result is empty (nil slice from SQL iteration) + assert.Empty(t, webhooks) } func TestTryMarkExecutionWebhookInFlight_Success(t *testing.T) { diff --git a/control-plane/internal/storage/local.go b/control-plane/internal/storage/local.go index e7e2976a..7f841a12 100644 --- a/control-plane/internal/storage/local.go +++ b/control-plane/internal/storage/local.go @@ -875,7 +875,11 @@ func (ls *LocalStorage) createSchema(ctx context.Context) error { } if err := ls.setupWorkflowExecutionFTS(); err != nil { - return err + if strings.Contains(err.Error(), "no such module: fts5") { + log.Printf("FTS5 module not available, full-text search will be degraded") + } else { + return err + } } if err := ls.ensureSQLiteIndexes(); err != nil { @@ -1047,6 +1051,7 @@ func (ls *LocalStorage) ensurePostgresIndexes(ctx context.Context) error { "CREATE INDEX IF NOT EXISTS idx_workflow_executions_parent_workflow_id ON workflow_executions(parent_workflow_id)", "CREATE INDEX IF NOT EXISTS idx_workflow_executions_root_workflow_id ON workflow_executions(root_workflow_id)", "CREATE INDEX IF NOT EXISTS idx_workflow_executions_status ON workflow_executions(status)", + "CREATE INDEX IF NOT EXISTS idx_agent_nodes_group_id ON agent_nodes(group_id)", } for _, stmt := range indexStatements { @@ -1146,6 +1151,7 @@ func (ls *LocalStorage) ensureSQLiteIndexes() error { "CREATE INDEX IF NOT EXISTS idx_agent_nodes_team ON agent_nodes(team_id)", "CREATE INDEX IF NOT EXISTS idx_agent_nodes_health ON agent_nodes(health_status)", "CREATE INDEX IF NOT EXISTS idx_agent_nodes_lifecycle ON agent_nodes(lifecycle_status)", + "CREATE INDEX IF NOT EXISTS idx_agent_nodes_group_id ON agent_nodes(group_id)", "CREATE INDEX IF NOT EXISTS idx_agent_dids_agent_node ON agent_dids(agent_node_id)", "CREATE INDEX IF NOT EXISTS idx_agent_dids_agentfield_server ON agent_dids(agentfield_server_id)", "CREATE INDEX IF NOT EXISTS idx_component_dids_agent_did ON component_dids(agent_did)", @@ -1259,7 +1265,41 @@ func (ls *LocalStorage) runPostgresMigrations(ctx context.Context) error { applied_at TIMESTAMPTZ DEFAULT NOW(), description TEXT );`) - return err + if err != nil { + return fmt.Errorf("failed to create schema_migrations table: %w", err) + } + + migrations := []struct { + version string + description string + sql string + }{ + { + version: "015", + description: "Backfill group_id on agent_nodes with id", + sql: `UPDATE agent_nodes SET group_id = id WHERE group_id = '' OR group_id IS NULL;`, + }, + } + + for _, m := range migrations { + var count int + err := ls.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM schema_migrations WHERE version = $1`, m.version).Scan(&count) + if err != nil { + return fmt.Errorf("failed to check migration %s: %w", m.version, err) + } + if count > 0 { + continue + } + if _, err := ls.db.ExecContext(ctx, m.sql); err != nil { + return fmt.Errorf("failed to apply migration %s: %w", m.version, err) + } + if _, err := ls.db.ExecContext(ctx, `INSERT INTO schema_migrations (version, description) VALUES ($1, $2)`, m.version, m.description); err != nil { + return fmt.Errorf("failed to record migration %s: %w", m.version, err) + } + log.Printf("Applied postgres migration %s: %s", m.version, m.description) + } + + return nil } // buildExecutionVCTableSQL returns the CREATE TABLE statement for execution VC storage. @@ -1604,6 +1644,11 @@ func (ls *LocalStorage) runMigrations() error { description: "Add document size column to workflow_vcs", sql: `ALTER TABLE workflow_vcs ADD COLUMN document_size_bytes INTEGER DEFAULT 0;`, }, + { + version: "015", + description: "Backfill group_id on agent_nodes with id", + sql: `UPDATE agent_nodes SET group_id = id WHERE group_id = '' OR group_id IS NULL;`, + }, } // Apply each migration if not already applied @@ -1630,6 +1675,8 @@ func (ls *LocalStorage) runMigrations() error { // For ALTER TABLE operations, check if column already exists if strings.Contains(err.Error(), "duplicate column name") { log.Printf("Column already exists for migration %s, marking as applied", migration.version) + } else if strings.Contains(err.Error(), "no such module: fts5") { + log.Printf("FTS5 module not available, skipping migration %s (search will be degraded)", migration.version) } else { return fmt.Errorf("failed to apply migration %s: %w", migration.version, err) } @@ -3030,6 +3077,7 @@ func (ls *LocalStorage) populateWorkflowCleanupCounts(ctx context.Context, targe result.DeletedRecords["workflow_executions"] = ls.countWorkflowExecutions(ctx, workflowIDs, runIDs) result.DeletedRecords["workflow_execution_events"] = ls.countWorkflowExecutionEvents(ctx, workflowIDs, runIDs) result.DeletedRecords["workflows"] = ls.countWorkflows(ctx, workflowIDs) + result.DeletedRecords["workflow_runs"] = ls.countWorkflowRuns(ctx, targets.primaryWorkflowID, workflowIDs, runIDs) } func (ls *LocalStorage) performWorkflowCleanup(ctx context.Context, tx DBTX, targets *workflowCleanupTargets) error { @@ -4298,14 +4346,15 @@ func (ls *LocalStorage) RegisterAgent(ctx context.Context, agent *types.AgentNod func (ls *LocalStorage) executeRegisterAgent(ctx context.Context, q DBTX, agent *types.AgentNode) error { query := ` INSERT INTO agent_nodes ( - id, team_id, base_url, version, deployment_type, invocation_url, reasoners, skills, + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, communication_config, health_status, lifecycle_status, last_heartbeat, - registered_at, features, metadata - ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) - ON CONFLICT(id) DO UPDATE SET + registered_at, features, metadata, proposed_tags, approved_tags + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(id, version) DO UPDATE SET + group_id = excluded.group_id, team_id = excluded.team_id, base_url = excluded.base_url, - version = excluded.version, + traffic_weight = excluded.traffic_weight, deployment_type = excluded.deployment_type, invocation_url = excluded.invocation_url, reasoners = excluded.reasoners, @@ -4315,7 +4364,9 @@ func (ls *LocalStorage) executeRegisterAgent(ctx context.Context, q DBTX, agent lifecycle_status = excluded.lifecycle_status, last_heartbeat = excluded.last_heartbeat, features = excluded.features, - metadata = excluded.metadata;` + metadata = excluded.metadata, + proposed_tags = excluded.proposed_tags, + approved_tags = excluded.approved_tags;` reasonersJSON, err := json.Marshal(agent.Reasoners) if err != nil { @@ -4337,11 +4388,24 @@ func (ls *LocalStorage) executeRegisterAgent(ctx context.Context, q DBTX, agent if err != nil { return fmt.Errorf("failed to marshal agent metadata: %w", err) } + proposedTagsJSON, err := json.Marshal(agent.ProposedTags) + if err != nil { + return fmt.Errorf("failed to marshal proposed tags: %w", err) + } + approvedTagsJSON, err := json.Marshal(agent.ApprovedTags) + if err != nil { + return fmt.Errorf("failed to marshal approved tags: %w", err) + } + + trafficWeight := agent.TrafficWeight + if trafficWeight == 0 { + trafficWeight = 100 + } _, err = q.ExecContext(ctx, query, - agent.ID, agent.TeamID, agent.BaseURL, agent.Version, agent.DeploymentType, agent.InvocationURL, + agent.ID, agent.Version, agent.GroupID, agent.TeamID, agent.BaseURL, trafficWeight, agent.DeploymentType, agent.InvocationURL, reasonersJSON, skillsJSON, commConfigJSON, agent.HealthStatus, agent.LifecycleStatus, - agent.LastHeartbeat, agent.RegisteredAt, featuresJSON, metadataJSON, + agent.LastHeartbeat, agent.RegisteredAt, featuresJSON, metadataJSON, proposedTagsJSON, approvedTagsJSON, ) if err != nil { @@ -4351,7 +4415,9 @@ func (ls *LocalStorage) executeRegisterAgent(ctx context.Context, q DBTX, agent return nil } -// GetAgent retrieves an agent node record from SQLite by ID. +// GetAgent retrieves the default (unversioned) agent node record by ID. +// It filters for version = '' to return only the default agent. +// Use GetAgentVersion for a specific version, or ListAgentVersions for all versions. func (ls *LocalStorage) GetAgent(ctx context.Context, id string) (*types.AgentNode, error) { // Check context cancellation early if err := ctx.Err(); err != nil { @@ -4360,22 +4426,27 @@ func (ls *LocalStorage) GetAgent(ctx context.Context, id string) (*types.AgentNo query := ` SELECT - id, team_id, base_url, version, deployment_type, invocation_url, reasoners, skills, + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, communication_config, health_status, lifecycle_status, last_heartbeat, - registered_at, features, metadata - FROM agent_nodes WHERE id = ?` + registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes WHERE id = ? + ORDER BY CASE WHEN version = '' THEN 0 ELSE 1 END, version ASC + LIMIT 1` row := ls.db.QueryRowContext(ctx, query, id) agent := &types.AgentNode{} var reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON []byte + var proposedTagsJSON, approvedTagsJSON []byte var healthStatusStr, lifecycleStatusStr string var invocationURL sql.NullString + var lastHeartbeat, registeredAt sql.NullTime err := row.Scan( - &agent.ID, &agent.TeamID, &agent.BaseURL, &agent.Version, &agent.DeploymentType, &invocationURL, + &agent.ID, &agent.Version, &agent.GroupID, &agent.TeamID, &agent.BaseURL, &agent.TrafficWeight, &agent.DeploymentType, &invocationURL, &reasonersJSON, &skillsJSON, &commConfigJSON, &healthStatusStr, &lifecycleStatusStr, - &agent.LastHeartbeat, &agent.RegisteredAt, &featuresJSON, &metadataJSON, + &lastHeartbeat, ®isteredAt, &featuresJSON, &metadataJSON, + &proposedTagsJSON, &approvedTagsJSON, ) if err != nil { @@ -4385,6 +4456,12 @@ func (ls *LocalStorage) GetAgent(ctx context.Context, id string) (*types.AgentNo return nil, fmt.Errorf("failed to get agent node with ID '%s': %w", id, err) } + if lastHeartbeat.Valid { + agent.LastHeartbeat = lastHeartbeat.Time + } + if registeredAt.Valid { + agent.RegisteredAt = registeredAt.Time + } agent.HealthStatus = types.HealthStatus(healthStatusStr) agent.LifecycleStatus = types.AgentLifecycleStatus(lifecycleStatusStr) if invocationURL.Valid && strings.TrimSpace(invocationURL.String) != "" { @@ -4417,6 +4494,16 @@ func (ls *LocalStorage) GetAgent(ctx context.Context, id string) (*types.AgentNo return nil, fmt.Errorf("failed to unmarshal agent metadata: %w", err) } } + if len(proposedTagsJSON) > 0 { + if err := json.Unmarshal(proposedTagsJSON, &agent.ProposedTags); err != nil { + return nil, fmt.Errorf("failed to unmarshal agent proposed tags: %w", err) + } + } + if len(approvedTagsJSON) > 0 { + if err := json.Unmarshal(approvedTagsJSON, &agent.ApprovedTags); err != nil { + return nil, fmt.Errorf("failed to unmarshal agent approved tags: %w", err) + } + } if strings.TrimSpace(agent.DeploymentType) == "" { if agent.InvocationURL != nil && strings.TrimSpace(*agent.InvocationURL) != "" { agent.DeploymentType = "serverless" @@ -4436,134 +4523,294 @@ func (ls *LocalStorage) GetAgent(ctx context.Context, id string) (*types.AgentNo } } + // Reconstruct agent-level ProposedTags and ApprovedTags from per-component fields. + // These fields are not stored in dedicated columns but are derived from the + // reasoners/skills JSON blobs. + reconstructAgentLevelTags(agent) + return agent, nil } -// ListAgents retrieves agent node records from SQLite based on filters. -func (ls *LocalStorage) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) { - // Check context cancellation early +// GetAgentVersion retrieves a specific (id, version) agent node. +func (ls *LocalStorage) GetAgentVersion(ctx context.Context, id string, version string) (*types.AgentNode, error) { if err := ctx.Err(); err != nil { - return nil, fmt.Errorf("context cancelled during list agents: %w", err) + return nil, fmt.Errorf("context cancelled during get agent version: %w", err) } - // Build query with filters + query := ` SELECT - id, team_id, base_url, version, deployment_type, invocation_url, reasoners, skills, + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, communication_config, health_status, lifecycle_status, last_heartbeat, - registered_at, features, metadata - FROM agent_nodes` + registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes WHERE id = ? AND version = ?` - var conditions []string - var args []interface{} + row := ls.db.QueryRowContext(ctx, query, id, version) + return ls.scanAgentNode(row) +} - // Add health status filter - if filters.HealthStatus != nil { - conditions = append(conditions, "health_status = ?") - args = append(args, string(*filters.HealthStatus)) +// DeleteAgentVersion deletes a specific agent version row from the agent_nodes table. +func (ls *LocalStorage) DeleteAgentVersion(ctx context.Context, id string, version string) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during delete agent version: %w", err) } - // Add team ID filter - if filters.TeamID != nil { - conditions = append(conditions, "team_id = ?") - args = append(args, *filters.TeamID) + _, err := ls.db.ExecContext(ctx, `DELETE FROM agent_nodes WHERE id = ? AND version = ?`, id, version) + if err != nil { + return fmt.Errorf("failed to delete agent version id='%s' version='%s': %w", id, version, err) } + return nil +} - // Add WHERE clause if there are conditions - if len(conditions) > 0 { - query += " WHERE " + conditions[0] - for i := 1; i < len(conditions); i++ { - query += " AND " + conditions[i] - } +// ListAgentVersions returns all versioned agents with the given ID (version != ''). +func (ls *LocalStorage) ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list agent versions: %w", err) } - query += " ORDER BY registered_at DESC" + query := ` + SELECT + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, + communication_config, health_status, lifecycle_status, last_heartbeat, + registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes WHERE id = ? AND version != '' ORDER BY registered_at DESC` - rows, err := ls.db.QueryContext(ctx, query, args...) + rows, err := ls.db.QueryContext(ctx, query, id) if err != nil { - return nil, fmt.Errorf("failed to list agent nodes: %w", err) + return nil, fmt.Errorf("failed to list agent versions for '%s': %w", id, err) } defer rows.Close() + return ls.scanAgentNodes(ctx, rows) +} + +// scanAgentNode scans a single row into an AgentNode, applying post-processing. +func (ls *LocalStorage) scanAgentNode(row *sql.Row) (*types.AgentNode, error) { + agent := &types.AgentNode{} + var reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON []byte + var proposedTagsJSON, approvedTagsJSON []byte + var healthStatusStr, lifecycleStatusStr string + var invocationURL sql.NullString + var lastHeartbeat, registeredAt sql.NullTime + + err := row.Scan( + &agent.ID, &agent.Version, &agent.GroupID, &agent.TeamID, &agent.BaseURL, &agent.TrafficWeight, &agent.DeploymentType, &invocationURL, + &reasonersJSON, &skillsJSON, &commConfigJSON, &healthStatusStr, &lifecycleStatusStr, + &lastHeartbeat, ®isteredAt, &featuresJSON, &metadataJSON, + &proposedTagsJSON, &approvedTagsJSON, + ) + if err != nil { + if err == sql.ErrNoRows { + return nil, fmt.Errorf("agent node with ID '%s' version '%s' not found", agent.ID, agent.Version) + } + return nil, fmt.Errorf("failed to scan agent node: %w", err) + } + + if lastHeartbeat.Valid { + agent.LastHeartbeat = lastHeartbeat.Time + } + if registeredAt.Valid { + agent.RegisteredAt = registeredAt.Time + } + ls.postProcessAgentNode(agent, healthStatusStr, lifecycleStatusStr, invocationURL, + reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON, proposedTagsJSON, approvedTagsJSON) + return agent, nil +} + +// scanAgentNodes scans multiple rows into AgentNode slices, applying post-processing. +func (ls *LocalStorage) scanAgentNodes(ctx context.Context, rows *sql.Rows) ([]*types.AgentNode, error) { agents := []*types.AgentNode{} for rows.Next() { - // Check context cancellation during iteration if err := ctx.Err(); err != nil { return nil, fmt.Errorf("context cancelled during agent list iteration: %w", err) } agent := &types.AgentNode{} var reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON []byte + var proposedTagsJSON, approvedTagsJSON []byte var healthStatusStr, lifecycleStatusStr string var invocationURL sql.NullString + var lastHeartbeat, registeredAt sql.NullTime err := rows.Scan( - &agent.ID, &agent.TeamID, &agent.BaseURL, &agent.Version, &agent.DeploymentType, &invocationURL, + &agent.ID, &agent.Version, &agent.GroupID, &agent.TeamID, &agent.BaseURL, &agent.TrafficWeight, &agent.DeploymentType, &invocationURL, &reasonersJSON, &skillsJSON, &commConfigJSON, &healthStatusStr, &lifecycleStatusStr, - &agent.LastHeartbeat, &agent.RegisteredAt, &featuresJSON, &metadataJSON, + &lastHeartbeat, ®isteredAt, &featuresJSON, &metadataJSON, + &proposedTagsJSON, &approvedTagsJSON, ) if err != nil { return nil, fmt.Errorf("failed to scan agent node row: %w", err) } - agent.HealthStatus = types.HealthStatus(healthStatusStr) - agent.LifecycleStatus = types.AgentLifecycleStatus(lifecycleStatusStr) - if invocationURL.Valid && strings.TrimSpace(invocationURL.String) != "" { - url := strings.TrimSpace(invocationURL.String) - agent.InvocationURL = &url - } - - if len(reasonersJSON) > 0 { - if err := json.Unmarshal(reasonersJSON, &agent.Reasoners); err != nil { - return nil, fmt.Errorf("failed to unmarshal agent reasoners: %w", err) - } - } - if len(skillsJSON) > 0 { - if err := json.Unmarshal(skillsJSON, &agent.Skills); err != nil { - return nil, fmt.Errorf("failed to unmarshal agent skills: %w", err) - } - } - if len(commConfigJSON) > 0 { - if err := json.Unmarshal(commConfigJSON, &agent.CommunicationConfig); err != nil { - return nil, fmt.Errorf("failed to unmarshal agent communication config: %w", err) - } + if lastHeartbeat.Valid { + agent.LastHeartbeat = lastHeartbeat.Time } - if len(featuresJSON) > 0 { - if err := json.Unmarshal(featuresJSON, &agent.Features); err != nil { - return nil, fmt.Errorf("failed to unmarshal agent features: %w", err) - } + if registeredAt.Valid { + agent.RegisteredAt = registeredAt.Time } - if len(metadataJSON) > 0 { - if err := json.Unmarshal(metadataJSON, &agent.Metadata); err != nil { - return nil, fmt.Errorf("failed to unmarshal agent metadata: %w", err) + ls.postProcessAgentNode(agent, healthStatusStr, lifecycleStatusStr, invocationURL, + reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON, proposedTagsJSON, approvedTagsJSON) + agents = append(agents, agent) + } + + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("error after listing agent nodes: %w", err) + } + return agents, nil +} + +// postProcessAgentNode applies common post-processing to a scanned AgentNode. +func (ls *LocalStorage) postProcessAgentNode(agent *types.AgentNode, healthStatusStr, lifecycleStatusStr string, invocationURL sql.NullString, + reasonersJSON, skillsJSON, commConfigJSON, featuresJSON, metadataJSON, proposedTagsJSON, approvedTagsJSON []byte) { + + agent.HealthStatus = types.HealthStatus(healthStatusStr) + agent.LifecycleStatus = types.AgentLifecycleStatus(lifecycleStatusStr) + if invocationURL.Valid && strings.TrimSpace(invocationURL.String) != "" { + url := strings.TrimSpace(invocationURL.String) + agent.InvocationURL = &url + } + + if len(reasonersJSON) > 0 { + _ = json.Unmarshal(reasonersJSON, &agent.Reasoners) + } + if len(skillsJSON) > 0 { + _ = json.Unmarshal(skillsJSON, &agent.Skills) + } + if len(commConfigJSON) > 0 { + _ = json.Unmarshal(commConfigJSON, &agent.CommunicationConfig) + } + if len(featuresJSON) > 0 { + _ = json.Unmarshal(featuresJSON, &agent.Features) + } + if len(metadataJSON) > 0 { + _ = json.Unmarshal(metadataJSON, &agent.Metadata) + } + if len(proposedTagsJSON) > 0 { + _ = json.Unmarshal(proposedTagsJSON, &agent.ProposedTags) + } + if len(approvedTagsJSON) > 0 { + _ = json.Unmarshal(approvedTagsJSON, &agent.ApprovedTags) + } + + if strings.TrimSpace(agent.DeploymentType) == "" { + if agent.InvocationURL != nil && strings.TrimSpace(*agent.InvocationURL) != "" { + agent.DeploymentType = "serverless" + } else if agent.Metadata.Custom != nil { + if v, ok := agent.Metadata.Custom["serverless"]; ok && fmt.Sprint(v) == "true" { + agent.DeploymentType = "serverless" } } if strings.TrimSpace(agent.DeploymentType) == "" { - if agent.InvocationURL != nil && strings.TrimSpace(*agent.InvocationURL) != "" { - agent.DeploymentType = "serverless" - } else if agent.Metadata.Custom != nil { - if v, ok := agent.Metadata.Custom["serverless"]; ok && fmt.Sprint(v) == "true" { - agent.DeploymentType = "serverless" - } - } - if strings.TrimSpace(agent.DeploymentType) == "" { - agent.DeploymentType = "long_running" - } + agent.DeploymentType = "long_running" } - if agent.DeploymentType == "serverless" && (agent.InvocationURL == nil || strings.TrimSpace(*agent.InvocationURL) == "") { - if trimmed := strings.TrimSpace(agent.BaseURL); trimmed != "" { - execURL := strings.TrimSuffix(trimmed, "/") + "/execute" - agent.InvocationURL = &execURL - } + } + if agent.DeploymentType == "serverless" && (agent.InvocationURL == nil || strings.TrimSpace(*agent.InvocationURL) == "") { + if trimmed := strings.TrimSpace(agent.BaseURL); trimmed != "" { + execURL := strings.TrimSuffix(trimmed, "/") + "/execute" + agent.InvocationURL = &execURL } + } - agents = append(agents, agent) + reconstructAgentLevelTags(agent) +} + +// ListAgents retrieves agent node records from SQLite based on filters. +func (ls *LocalStorage) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list agents: %w", err) + } + + query := ` + SELECT + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, + communication_config, health_status, lifecycle_status, last_heartbeat, + registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes` + + var conditions []string + var args []interface{} + + if filters.HealthStatus != nil { + conditions = append(conditions, "health_status = ?") + args = append(args, string(*filters.HealthStatus)) + } + if filters.TeamID != nil { + conditions = append(conditions, "team_id = ?") + args = append(args, *filters.TeamID) + } + if filters.GroupID != nil { + conditions = append(conditions, "group_id = ?") + args = append(args, *filters.GroupID) + } + + if len(conditions) > 0 { + query += " WHERE " + conditions[0] + for i := 1; i < len(conditions); i++ { + query += " AND " + conditions[i] + } + } + + query += " ORDER BY registered_at DESC" + + rows, err := ls.db.QueryContext(ctx, query, args...) + if err != nil { + return nil, fmt.Errorf("failed to list agent nodes: %w", err) + } + defer rows.Close() + + return ls.scanAgentNodes(ctx, rows) +} + +// ListAgentsByGroup returns all agents belonging to a specific group. +func (ls *LocalStorage) ListAgentsByGroup(ctx context.Context, groupID string) ([]*types.AgentNode, error) { + return ls.ListAgents(ctx, types.AgentFilters{GroupID: &groupID}) +} + +// ListAgentGroups returns distinct agent groups with summary info for a team. +func (ls *LocalStorage) ListAgentGroups(ctx context.Context, teamID string) ([]types.AgentGroupSummary, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list agent groups: %w", err) + } + + var query string + if ls.mode == "postgres" { + query = ` + SELECT group_id, team_id, COUNT(*) as node_count, STRING_AGG(DISTINCT version, ',') as versions + FROM agent_nodes + WHERE team_id = $1 + GROUP BY group_id, team_id + ORDER BY group_id` + } else { + query = ` + SELECT group_id, team_id, COUNT(*) as node_count, GROUP_CONCAT(DISTINCT version) as versions + FROM agent_nodes + WHERE team_id = ? + GROUP BY group_id, team_id + ORDER BY group_id` + } + + rows, err := ls.db.QueryContext(ctx, query, teamID) + if err != nil { + return nil, fmt.Errorf("failed to list agent groups: %w", err) } + defer rows.Close() + var groups []types.AgentGroupSummary + for rows.Next() { + var g types.AgentGroupSummary + var versionsStr sql.NullString + if err := rows.Scan(&g.GroupID, &g.TeamID, &g.NodeCount, &versionsStr); err != nil { + return nil, fmt.Errorf("failed to scan agent group row: %w", err) + } + if versionsStr.Valid && versionsStr.String != "" { + g.Versions = strings.Split(versionsStr.String, ",") + } + groups = append(groups, g) + } if err := rows.Err(); err != nil { - return nil, fmt.Errorf("error after listing agent nodes: %w", err) + return nil, fmt.Errorf("error after listing agent groups: %w", err) } - return agents, nil + return groups, nil } // UpdateAgentHealth updates the health status of an agent node in SQLite. @@ -4661,25 +4908,22 @@ func (ls *LocalStorage) UpdateAgentHealthAtomic(ctx context.Context, id string, } // UpdateAgentHeartbeat updates only the heartbeat timestamp of an agent node in SQLite. -func (ls *LocalStorage) UpdateAgentHeartbeat(ctx context.Context, id string, heartbeatTime time.Time) error { - // Check context cancellation early +// If version is empty, it updates the default (unversioned) agent. +func (ls *LocalStorage) UpdateAgentHeartbeat(ctx context.Context, id string, version string, heartbeatTime time.Time) error { if err := ctx.Err(); err != nil { return fmt.Errorf("context cancelled during update agent heartbeat: %w", err) } - // Begin transaction for atomic operation tx, err := ls.db.BeginTx(ctx, nil) if err != nil { return fmt.Errorf("failed to begin transaction for agent heartbeat update: %w", err) } defer rollbackTx(tx, "UpdateAgentHeartbeat:"+id) - // Execute the heartbeat update using the transaction - if err := ls.executeUpdateAgentHeartbeat(ctx, tx, id, heartbeatTime); err != nil { + if err := ls.executeUpdateAgentHeartbeat(ctx, tx, id, version, heartbeatTime); err != nil { return err } - // Commit transaction if err := tx.Commit(); err != nil { return fmt.Errorf("failed to commit agent heartbeat transaction: %w", err) } @@ -4688,16 +4932,15 @@ func (ls *LocalStorage) UpdateAgentHeartbeat(ctx context.Context, id string, hea } // executeUpdateAgentHeartbeat performs the actual heartbeat timestamp update using DBTX interface -func (ls *LocalStorage) executeUpdateAgentHeartbeat(ctx context.Context, q DBTX, id string, heartbeatTime time.Time) error { +func (ls *LocalStorage) executeUpdateAgentHeartbeat(ctx context.Context, q DBTX, id string, version string, heartbeatTime time.Time) error { query := ` UPDATE agent_nodes SET last_heartbeat = ? - WHERE id = ?;` + WHERE id = ? AND version = ?;` - // Store timestamp in UTC format with timezone info - _, err := q.ExecContext(ctx, query, heartbeatTime.UTC().Format(time.RFC3339Nano), id) + _, err := q.ExecContext(ctx, query, heartbeatTime.UTC().Format(time.RFC3339Nano), id, version) if err != nil { - return fmt.Errorf("failed to update agent heartbeat for ID '%s': %w", id, err) + return fmt.Errorf("failed to update agent heartbeat for ID '%s' version '%s': %w", id, version, err) } return nil @@ -4746,6 +4989,49 @@ func (ls *LocalStorage) executeUpdateAgentLifecycleStatus(ctx context.Context, q return nil } +// UpdateAgentVersion updates only the version field for an agent node. +func (ls *LocalStorage) UpdateAgentVersion(ctx context.Context, id string, version string) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during update agent version: %w", err) + } + + tx, err := ls.db.BeginTx(ctx, nil) + if err != nil { + return fmt.Errorf("failed to begin transaction for agent version update: %w", err) + } + defer rollbackTx(tx, "UpdateAgentVersion:"+id) + + query := `UPDATE agent_nodes SET version = ? WHERE id = ?;` + if _, err := tx.ExecContext(ctx, query, version, id); err != nil { + return fmt.Errorf("failed to update agent version for ID '%s': %w", id, err) + } + + if err := tx.Commit(); err != nil { + return fmt.Errorf("failed to commit agent version transaction: %w", err) + } + + return nil +} + +// UpdateAgentTrafficWeight sets the traffic_weight for a specific (id, version) pair. +func (ls *LocalStorage) UpdateAgentTrafficWeight(ctx context.Context, id string, version string, weight int) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during update traffic weight: %w", err) + } + + result, err := ls.db.ExecContext(ctx, + `UPDATE agent_nodes SET traffic_weight = ? WHERE id = ? AND version = ?`, + weight, id, version) + if err != nil { + return fmt.Errorf("failed to update traffic weight: %w", err) + } + rows, _ := result.RowsAffected() + if rows == 0 { + return fmt.Errorf("agent (id=%s, version=%s) not found", id, version) + } + return nil +} + // SetConfig stores a configuration key-value pair in SQLite. func (ls *LocalStorage) SetConfig(ctx context.Context, key string, value interface{}) error { // Fast-fail if context is already cancelled @@ -7331,3 +7617,688 @@ func (ls *LocalStorage) ListExecutionWebhookEventsBatch(ctx context.Context, exe return results, nil } + +// ============================================================================= +// DID Document Operations (did:web Resolution) +// ============================================================================= + +// StoreDIDDocument stores a DID document record. +func (ls *LocalStorage) StoreDIDDocument(ctx context.Context, record *types.DIDDocumentRecord) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during store DID document: %w", err) + } + + query := ` + INSERT INTO did_documents ( + did, agent_id, did_document, public_key_jwk, revoked_at, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(did) DO UPDATE SET + agent_id = excluded.agent_id, + did_document = excluded.did_document, + public_key_jwk = excluded.public_key_jwk, + updated_at = excluded.updated_at` + + _, err := ls.db.ExecContext(ctx, query, + record.DID, record.AgentID, record.DIDDocument, record.PublicKeyJWK, + record.RevokedAt, record.CreatedAt, record.UpdatedAt, + ) + if err != nil { + return fmt.Errorf("failed to store DID document: %w", err) + } + + return nil +} + +// GetDIDDocument retrieves a DID document by its DID. +func (ls *LocalStorage) GetDIDDocument(ctx context.Context, did string) (*types.DIDDocumentRecord, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during get DID document: %w", err) + } + + query := ` + SELECT did, agent_id, did_document, public_key_jwk, revoked_at, created_at, updated_at + FROM did_documents WHERE did = ?` + + row := ls.db.QueryRowContext(ctx, query, did) + + record := &types.DIDDocumentRecord{} + var revokedAt sql.NullTime + + err := row.Scan( + &record.DID, &record.AgentID, &record.DIDDocument, &record.PublicKeyJWK, + &revokedAt, &record.CreatedAt, &record.UpdatedAt, + ) + if err != nil { + if err == sql.ErrNoRows { + return nil, fmt.Errorf("DID document not found: %s", did) + } + return nil, fmt.Errorf("failed to get DID document: %w", err) + } + + if revokedAt.Valid { + record.RevokedAt = &revokedAt.Time + } + + return record, nil +} + +// GetDIDDocumentByAgentID retrieves a DID document by agent ID. +func (ls *LocalStorage) GetDIDDocumentByAgentID(ctx context.Context, agentID string) (*types.DIDDocumentRecord, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during get DID document by agent ID: %w", err) + } + + query := ` + SELECT did, agent_id, did_document, public_key_jwk, revoked_at, created_at, updated_at + FROM did_documents WHERE agent_id = ? AND revoked_at IS NULL + ORDER BY created_at DESC LIMIT 1` + + row := ls.db.QueryRowContext(ctx, query, agentID) + + record := &types.DIDDocumentRecord{} + var revokedAt sql.NullTime + + err := row.Scan( + &record.DID, &record.AgentID, &record.DIDDocument, &record.PublicKeyJWK, + &revokedAt, &record.CreatedAt, &record.UpdatedAt, + ) + if err != nil { + if err == sql.ErrNoRows { + return nil, fmt.Errorf("DID document not found for agent: %s", agentID) + } + return nil, fmt.Errorf("failed to get DID document by agent ID: %w", err) + } + + if revokedAt.Valid { + record.RevokedAt = &revokedAt.Time + } + + return record, nil +} + +// RevokeDIDDocument revokes a DID document by setting its revoked_at timestamp. +func (ls *LocalStorage) RevokeDIDDocument(ctx context.Context, did string) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during revoke DID document: %w", err) + } + + query := `UPDATE did_documents SET revoked_at = ?, updated_at = ? WHERE did = ?` + + now := time.Now() + result, err := ls.db.ExecContext(ctx, query, now, now, did) + if err != nil { + return fmt.Errorf("failed to revoke DID document: %w", err) + } + + rows, err := result.RowsAffected() + if err != nil { + return fmt.Errorf("failed to get rows affected: %w", err) + } + if rows == 0 { + return fmt.Errorf("DID document not found: %s", did) + } + + return nil +} + +// ListDIDDocuments lists all DID documents. +func (ls *LocalStorage) ListDIDDocuments(ctx context.Context) ([]*types.DIDDocumentRecord, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list DID documents: %w", err) + } + + query := ` + SELECT did, agent_id, did_document, public_key_jwk, revoked_at, created_at, updated_at + FROM did_documents ORDER BY created_at DESC` + + rows, err := ls.db.QueryContext(ctx, query) + if err != nil { + return nil, fmt.Errorf("failed to list DID documents: %w", err) + } + defer rows.Close() + + var records []*types.DIDDocumentRecord + for rows.Next() { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during scan: %w", err) + } + + record := &types.DIDDocumentRecord{} + var revokedAt sql.NullTime + + err := rows.Scan( + &record.DID, &record.AgentID, &record.DIDDocument, &record.PublicKeyJWK, + &revokedAt, &record.CreatedAt, &record.UpdatedAt, + ) + if err != nil { + return nil, fmt.Errorf("failed to scan DID document: %w", err) + } + + if revokedAt.Valid { + record.RevokedAt = &revokedAt.Time + } + + records = append(records, record) + } + + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("error iterating DID documents: %w", err) + } + + return records, nil +} + +// ListAgentsByLifecycleStatus lists agents filtered by lifecycle status. +func (ls *LocalStorage) ListAgentsByLifecycleStatus(ctx context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list agents by lifecycle status: %w", err) + } + + query := ` + SELECT + id, version, group_id, team_id, base_url, traffic_weight, deployment_type, invocation_url, reasoners, skills, + communication_config, health_status, lifecycle_status, last_heartbeat, + registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes WHERE lifecycle_status = ? ORDER BY registered_at DESC` + + rows, err := ls.db.QueryContext(ctx, query, string(status)) + if err != nil { + return nil, fmt.Errorf("failed to list agents by lifecycle status: %w", err) + } + defer rows.Close() + + return ls.scanAgentNodes(ctx, rows) +} + +// reconstructAgentLevelTags ensures agent-level ProposedTags and ApprovedTags +// are populated. If the dedicated DB columns were empty (e.g., on older records), +// it reconstructs them from per-reasoner/per-skill fields as a fallback. +func reconstructAgentLevelTags(agent *types.AgentNode) { + // Only reconstruct if DB columns were empty + if len(agent.ApprovedTags) == 0 { + seen := make(map[string]struct{}) + for _, r := range agent.Reasoners { + for _, t := range r.ApprovedTags { + if _, exists := seen[t]; !exists { + seen[t] = struct{}{} + agent.ApprovedTags = append(agent.ApprovedTags, t) + } + } + } + for _, sk := range agent.Skills { + for _, t := range sk.ApprovedTags { + if _, exists := seen[t]; !exists { + seen[t] = struct{}{} + agent.ApprovedTags = append(agent.ApprovedTags, t) + } + } + } + } + + if len(agent.ProposedTags) == 0 { + proposedSeen := make(map[string]struct{}) + for _, r := range agent.Reasoners { + source := r.ProposedTags + if len(source) == 0 { + source = r.Tags + } + for _, t := range source { + if _, exists := proposedSeen[t]; !exists { + proposedSeen[t] = struct{}{} + agent.ProposedTags = append(agent.ProposedTags, t) + } + } + } + for _, sk := range agent.Skills { + source := sk.ProposedTags + if len(source) == 0 { + source = sk.Tags + } + for _, t := range source { + if _, exists := proposedSeen[t]; !exists { + proposedSeen[t] = struct{}{} + agent.ProposedTags = append(agent.ProposedTags, t) + } + } + } + } +} + +// ============================================================================ +// Access Policy Storage +// ============================================================================ + +// GetAccessPolicies retrieves all enabled access policies, sorted by priority descending. +func (ls *LocalStorage) GetAccessPolicies(ctx context.Context) ([]*types.AccessPolicy, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during get access policies: %w", err) + } + + query := ` + SELECT id, name, caller_tags, target_tags, allow_functions, deny_functions, + constraints, action, priority, enabled, description, created_at, updated_at + FROM access_policies WHERE enabled = true ORDER BY priority DESC, created_at DESC` + + rows, err := ls.db.QueryContext(ctx, query) + if err != nil { + return nil, fmt.Errorf("failed to get access policies: %w", err) + } + defer rows.Close() + + var policies []*types.AccessPolicy + for rows.Next() { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during scan: %w", err) + } + + policy, err := scanAccessPolicy(rows) + if err != nil { + return nil, err + } + policies = append(policies, policy) + } + + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("error iterating access policies: %w", err) + } + + return policies, nil +} + +// GetAccessPolicyByID retrieves a single access policy by its ID. +func (ls *LocalStorage) GetAccessPolicyByID(ctx context.Context, id int64) (*types.AccessPolicy, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during get access policy: %w", err) + } + + query := ` + SELECT id, name, caller_tags, target_tags, allow_functions, deny_functions, + constraints, action, priority, enabled, description, created_at, updated_at + FROM access_policies WHERE id = ?` + + row := ls.db.QueryRowContext(ctx, query, id) + + policy := &types.AccessPolicy{} + var callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON string + var description sql.NullString + + err := row.Scan( + &policy.ID, &policy.Name, &callerTagsJSON, &targetTagsJSON, + &allowFuncsJSON, &denyFuncsJSON, &constraintsJSON, + &policy.Action, &policy.Priority, &policy.Enabled, &description, + &policy.CreatedAt, &policy.UpdatedAt, + ) + if err != nil { + return nil, fmt.Errorf("access policy with ID %d not found: %w", id, err) + } + + if description.Valid { + policy.Description = &description.String + } + if err := unmarshalAccessPolicyJSON(policy, callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON); err != nil { + return nil, fmt.Errorf("failed to unmarshal access policy %d: %w", id, err) + } + + return policy, nil +} + +// CreateAccessPolicy creates a new access policy. +func (ls *LocalStorage) CreateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error { + if ls.mode == "postgres" { + return ls.createAccessPolicyPostgres(ctx, policy) + } + + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during create access policy: %w", err) + } + + callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON, err := marshalAccessPolicyJSON(policy) + if err != nil { + return fmt.Errorf("failed to marshal access policy fields: %w", err) + } + + query := ` + INSERT INTO access_policies ( + name, caller_tags, target_tags, allow_functions, deny_functions, + constraints, action, priority, enabled, description, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)` + + result, err := ls.db.ExecContext(ctx, query, + policy.Name, callerTagsJSON, targetTagsJSON, + allowFuncsJSON, denyFuncsJSON, constraintsJSON, + policy.Action, policy.Priority, policy.Enabled, policy.Description, + policy.CreatedAt, policy.UpdatedAt, + ) + if err != nil { + if strings.Contains(err.Error(), "UNIQUE constraint") { + return fmt.Errorf("access policy with name %q already exists", policy.Name) + } + return fmt.Errorf("failed to create access policy: %w", err) + } + + id, err := result.LastInsertId() + if err == nil { + policy.ID = id + } + + return nil +} + +// createAccessPolicyPostgres creates an access policy using PostgreSQL's RETURNING clause. +func (ls *LocalStorage) createAccessPolicyPostgres(ctx context.Context, policy *types.AccessPolicy) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during create access policy: %w", err) + } + + callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON, err := marshalAccessPolicyJSON(policy) + if err != nil { + return fmt.Errorf("failed to marshal access policy fields: %w", err) + } + + query := ` + INSERT INTO access_policies ( + name, caller_tags, target_tags, allow_functions, deny_functions, + constraints, action, priority, enabled, description, created_at, updated_at + ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) + RETURNING id` + + row := ls.db.DB.QueryRowContext(ctx, query, + policy.Name, callerTagsJSON, targetTagsJSON, + allowFuncsJSON, denyFuncsJSON, constraintsJSON, + policy.Action, policy.Priority, policy.Enabled, policy.Description, + policy.CreatedAt, policy.UpdatedAt, + ) + + if err := row.Scan(&policy.ID); err != nil { + if strings.Contains(err.Error(), "duplicate key") { + return fmt.Errorf("access policy with name %q already exists", policy.Name) + } + return fmt.Errorf("failed to create access policy: %w", err) + } + + return nil +} + +// UpdateAccessPolicy updates an existing access policy. +func (ls *LocalStorage) UpdateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during update access policy: %w", err) + } + + callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON, err := marshalAccessPolicyJSON(policy) + if err != nil { + return fmt.Errorf("failed to marshal access policy fields: %w", err) + } + + query := ` + UPDATE access_policies SET + name = ?, caller_tags = ?, target_tags = ?, allow_functions = ?, + deny_functions = ?, constraints = ?, action = ?, priority = ?, + enabled = ?, description = ?, updated_at = ? + WHERE id = ?` + + result, err := ls.db.ExecContext(ctx, query, + policy.Name, callerTagsJSON, targetTagsJSON, + allowFuncsJSON, denyFuncsJSON, constraintsJSON, + policy.Action, policy.Priority, policy.Enabled, policy.Description, + policy.UpdatedAt, policy.ID, + ) + if err != nil { + return fmt.Errorf("failed to update access policy: %w", err) + } + + rowsAffected, err := result.RowsAffected() + if err != nil { + return fmt.Errorf("failed to get rows affected: %w", err) + } + if rowsAffected == 0 { + return fmt.Errorf("access policy with ID %d not found", policy.ID) + } + + return nil +} + +// DeleteAccessPolicy deletes an access policy by ID. +func (ls *LocalStorage) DeleteAccessPolicy(ctx context.Context, id int64) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during delete access policy: %w", err) + } + + query := `DELETE FROM access_policies WHERE id = ?` + + result, err := ls.db.ExecContext(ctx, query, id) + if err != nil { + return fmt.Errorf("failed to delete access policy: %w", err) + } + + rows, err := result.RowsAffected() + if err != nil { + return fmt.Errorf("failed to get rows affected: %w", err) + } + if rows == 0 { + return fmt.Errorf("access policy with ID %d not found", id) + } + + return nil +} + +// scanAccessPolicy scans a row into an AccessPolicy struct. +func scanAccessPolicy(rows *sql.Rows) (*types.AccessPolicy, error) { + policy := &types.AccessPolicy{} + var callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON string + var description sql.NullString + + err := rows.Scan( + &policy.ID, &policy.Name, &callerTagsJSON, &targetTagsJSON, + &allowFuncsJSON, &denyFuncsJSON, &constraintsJSON, + &policy.Action, &policy.Priority, &policy.Enabled, &description, + &policy.CreatedAt, &policy.UpdatedAt, + ) + if err != nil { + return nil, fmt.Errorf("failed to scan access policy: %w", err) + } + + if description.Valid { + policy.Description = &description.String + } + if err := unmarshalAccessPolicyJSON(policy, callerTagsJSON, targetTagsJSON, allowFuncsJSON, denyFuncsJSON, constraintsJSON); err != nil { + return nil, fmt.Errorf("failed to unmarshal access policy %d: %w", policy.ID, err) + } + + return policy, nil +} + +// unmarshalAccessPolicyJSON populates the JSON fields of an AccessPolicy. +// Returns an error if any JSON field cannot be deserialized, preventing +// corrupted data from silently producing empty policy rules. +func unmarshalAccessPolicyJSON(policy *types.AccessPolicy, callerTags, targetTags, allowFuncs, denyFuncs, constraints string) error { + if callerTags != "" { + if err := json.Unmarshal([]byte(callerTags), &policy.CallerTags); err != nil { + return fmt.Errorf("failed to unmarshal caller_tags: %w", err) + } + } + if targetTags != "" { + if err := json.Unmarshal([]byte(targetTags), &policy.TargetTags); err != nil { + return fmt.Errorf("failed to unmarshal target_tags: %w", err) + } + } + if allowFuncs != "" { + if err := json.Unmarshal([]byte(allowFuncs), &policy.AllowFunctions); err != nil { + return fmt.Errorf("failed to unmarshal allow_functions: %w", err) + } + } + if denyFuncs != "" { + if err := json.Unmarshal([]byte(denyFuncs), &policy.DenyFunctions); err != nil { + return fmt.Errorf("failed to unmarshal deny_functions: %w", err) + } + } + if constraints != "" { + if err := json.Unmarshal([]byte(constraints), &policy.Constraints); err != nil { + return fmt.Errorf("failed to unmarshal constraints: %w", err) + } + } + return nil +} + +// marshalAccessPolicyJSON serializes the JSON fields of an AccessPolicy for storage. +func marshalAccessPolicyJSON(policy *types.AccessPolicy) (callerTags, targetTags, allowFuncs, denyFuncs, constraints string, err error) { + ct, err := json.Marshal(policy.CallerTags) + if err != nil { + return "", "", "", "", "", fmt.Errorf("caller_tags: %w", err) + } + tt, err := json.Marshal(policy.TargetTags) + if err != nil { + return "", "", "", "", "", fmt.Errorf("target_tags: %w", err) + } + af, err := json.Marshal(policy.AllowFunctions) + if err != nil { + return "", "", "", "", "", fmt.Errorf("allow_functions: %w", err) + } + df, err := json.Marshal(policy.DenyFunctions) + if err != nil { + return "", "", "", "", "", fmt.Errorf("deny_functions: %w", err) + } + cn, err := json.Marshal(policy.Constraints) + if err != nil { + return "", "", "", "", "", fmt.Errorf("constraints: %w", err) + } + return string(ct), string(tt), string(af), string(df), string(cn), nil +} + +// ========== Agent Tag VC operations ========== + +// StoreAgentTagVC stores or replaces an agent's tag VC. +func (ls *LocalStorage) StoreAgentTagVC(ctx context.Context, agentID, agentDID, vcID, vcDocument, signature string, issuedAt time.Time, expiresAt *time.Time) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during store agent tag VC: %w", err) + } + + query := ` + INSERT INTO agent_tag_vcs (agent_id, agent_did, vc_id, vc_document, signature, issued_at, expires_at, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(agent_id) DO UPDATE SET + agent_did = excluded.agent_did, + vc_id = excluded.vc_id, + vc_document = excluded.vc_document, + signature = excluded.signature, + issued_at = excluded.issued_at, + expires_at = excluded.expires_at, + revoked_at = NULL, + updated_at = excluded.updated_at` + + now := time.Now() + _, err := ls.db.ExecContext(ctx, query, agentID, agentDID, vcID, vcDocument, signature, issuedAt, expiresAt, now, now) + if err != nil { + return fmt.Errorf("failed to store agent tag VC: %w", err) + } + return nil +} + +// GetAgentTagVC retrieves an agent's tag VC record. +func (ls *LocalStorage) GetAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCRecord, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during get agent tag VC: %w", err) + } + + query := ` + SELECT id, agent_id, agent_did, vc_id, vc_document, signature, issued_at, expires_at, revoked_at + FROM agent_tag_vcs WHERE agent_id = ?` + + row := ls.db.QueryRowContext(ctx, query, agentID) + + record := &types.AgentTagVCRecord{} + var expiresAt, revokedAt sql.NullTime + var signature sql.NullString + + err := row.Scan( + &record.ID, &record.AgentID, &record.AgentDID, &record.VCID, + &record.VCDocument, &signature, &record.IssuedAt, &expiresAt, &revokedAt, + ) + if err != nil { + if err == sql.ErrNoRows { + return nil, fmt.Errorf("agent tag VC not found for agent %s", agentID) + } + return nil, fmt.Errorf("failed to get agent tag VC: %w", err) + } + + if signature.Valid { + record.Signature = signature.String + } + if expiresAt.Valid { + record.ExpiresAt = &expiresAt.Time + } + if revokedAt.Valid { + record.RevokedAt = &revokedAt.Time + } + + return record, nil +} + +// ListAgentTagVCs returns all non-revoked agent tag VCs. +func (ls *LocalStorage) ListAgentTagVCs(ctx context.Context) ([]*types.AgentTagVCRecord, error) { + if err := ctx.Err(); err != nil { + return nil, fmt.Errorf("context cancelled during list agent tag VCs: %w", err) + } + + query := ` + SELECT id, agent_id, agent_did, vc_id, vc_document, signature, issued_at, expires_at, revoked_at + FROM agent_tag_vcs WHERE revoked_at IS NULL` + + rows, err := ls.db.QueryContext(ctx, query) + if err != nil { + return nil, fmt.Errorf("failed to list agent tag VCs: %w", err) + } + defer rows.Close() + + var records []*types.AgentTagVCRecord + for rows.Next() { + record := &types.AgentTagVCRecord{} + var expiresAt, revokedAt sql.NullTime + var signature sql.NullString + + if err := rows.Scan( + &record.ID, &record.AgentID, &record.AgentDID, &record.VCID, + &record.VCDocument, &signature, &record.IssuedAt, &expiresAt, &revokedAt, + ); err != nil { + return nil, fmt.Errorf("failed to scan agent tag VC: %w", err) + } + + if signature.Valid { + record.Signature = signature.String + } + if expiresAt.Valid { + record.ExpiresAt = &expiresAt.Time + } + if revokedAt.Valid { + record.RevokedAt = &revokedAt.Time + } + records = append(records, record) + } + + return records, rows.Err() +} + +// RevokeAgentTagVC marks an agent's tag VC as revoked. +func (ls *LocalStorage) RevokeAgentTagVC(ctx context.Context, agentID string) error { + if err := ctx.Err(); err != nil { + return fmt.Errorf("context cancelled during revoke agent tag VC: %w", err) + } + + query := `UPDATE agent_tag_vcs SET revoked_at = ?, updated_at = ? WHERE agent_id = ? AND revoked_at IS NULL` + + now := time.Now() + result, err := ls.db.ExecContext(ctx, query, now, now, agentID) + if err != nil { + return fmt.Errorf("failed to revoke agent tag VC: %w", err) + } + + rows, err := result.RowsAffected() + if err != nil { + return fmt.Errorf("failed to get rows affected: %w", err) + } + if rows == 0 { + return fmt.Errorf("no active agent tag VC found for agent %s", agentID) + } + + return nil +} diff --git a/control-plane/internal/storage/migrations.go b/control-plane/internal/storage/migrations.go index 9e932ec4..a38e0d19 100644 --- a/control-plane/internal/storage/migrations.go +++ b/control-plane/internal/storage/migrations.go @@ -5,7 +5,191 @@ import ( "fmt" ) +// migrateAgentNodesCompositePK recreates the agent_nodes table with a composite +// primary key (id, version) and adds the traffic_weight column. This is needed +// because SQLite does not support ALTER TABLE ... DROP PRIMARY KEY. +func (ls *LocalStorage) migrateAgentNodesCompositePK(ctx context.Context) error { + // Check if migration is needed by looking for the traffic_weight column + var count int + err := ls.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM pragma_table_info('agent_nodes') WHERE name = 'traffic_weight'`).Scan(&count) + if err != nil { + // Table might not exist yet (fresh install); GORM will create it with composite PK + return nil + } + if count > 0 { + // Already migrated + return nil + } + + // Check the table exists at all + var tableCount int + err = ls.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='agent_nodes'`).Scan(&tableCount) + if err != nil || tableCount == 0 { + return nil // Fresh install, GORM will create the table + } + + tx, err := ls.db.BeginTx(ctx, nil) + if err != nil { + return fmt.Errorf("failed to begin migration transaction: %w", err) + } + defer rollbackTx(tx, "migrateAgentNodesCompositePK") + + // Ensure columns from recent features exist before table recreation. + // These may be absent if the DB predates those features being merged. + columnsToEnsure := []struct { + name string + ddl string + }{ + {"version", `ALTER TABLE agent_nodes ADD COLUMN version TEXT NOT NULL DEFAULT ''`}, + {"proposed_tags", `ALTER TABLE agent_nodes ADD COLUMN proposed_tags BLOB`}, + {"approved_tags", `ALTER TABLE agent_nodes ADD COLUMN approved_tags BLOB`}, + } + for _, col := range columnsToEnsure { + var colExists int + if err := tx.QueryRowContext(ctx, `SELECT COUNT(*) FROM pragma_table_info('agent_nodes') WHERE name = ?`, col.name).Scan(&colExists); err != nil { + return fmt.Errorf("failed to check for column %s: %w", col.name, err) + } + if colExists == 0 { + if _, err := tx.ExecContext(ctx, col.ddl); err != nil { + return fmt.Errorf("failed to add column %s: %w", col.name, err) + } + } + } + + migrations := []string{ + `CREATE TABLE agent_nodes_new ( + id TEXT NOT NULL, + version TEXT NOT NULL DEFAULT '', + group_id TEXT NOT NULL DEFAULT '', + team_id TEXT NOT NULL DEFAULT '', + base_url TEXT NOT NULL DEFAULT '', + traffic_weight INTEGER NOT NULL DEFAULT 100, + deployment_type TEXT DEFAULT 'long_running', + invocation_url TEXT, + reasoners BLOB, + skills BLOB, + communication_config BLOB, + health_status TEXT NOT NULL DEFAULT 'unknown', + lifecycle_status TEXT DEFAULT 'starting', + last_heartbeat TIMESTAMP, + registered_at TIMESTAMP, + features BLOB, + metadata BLOB, + proposed_tags BLOB, + approved_tags BLOB, + PRIMARY KEY (id, version) + )`, + `INSERT INTO agent_nodes_new ( + id, version, group_id, team_id, base_url, deployment_type, invocation_url, + reasoners, skills, communication_config, health_status, lifecycle_status, + last_heartbeat, registered_at, features, metadata, proposed_tags, approved_tags + ) SELECT + id, version, id, team_id, base_url, deployment_type, invocation_url, + reasoners, skills, communication_config, health_status, lifecycle_status, + last_heartbeat, registered_at, features, metadata, proposed_tags, approved_tags + FROM agent_nodes`, + `DROP TABLE agent_nodes`, + `ALTER TABLE agent_nodes_new RENAME TO agent_nodes`, + `CREATE INDEX IF NOT EXISTS idx_agent_nodes_team_id ON agent_nodes(team_id)`, + `CREATE INDEX IF NOT EXISTS idx_agent_nodes_group_id ON agent_nodes(group_id)`, + } + + for _, m := range migrations { + if _, err := tx.ExecContext(ctx, m); err != nil { + return fmt.Errorf("composite PK migration failed: %w", err) + } + } + + if err := tx.Commit(); err != nil { + return fmt.Errorf("failed to commit composite PK migration: %w", err) + } + + fmt.Println("[migration] agent_nodes table migrated to composite PK (id, version) with traffic_weight") + return nil +} + +// migrateAgentNodesCompositePKPostgres handles the composite PK migration for PostgreSQL. +func (ls *LocalStorage) migrateAgentNodesCompositePKPostgres(ctx context.Context) error { + // Check if the table exists at all — on a fresh database GORM will create it + // with the composite PK already in place, so we skip this migration entirely. + var tableExists int + if err := ls.db.QueryRowContext(ctx, + `SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public' AND table_name = 'agent_nodes'`, + ).Scan(&tableExists); err != nil || tableExists == 0 { + return nil // Fresh install, GORM will create the table + } + + var count int + err := ls.db.QueryRowContext(ctx, + `SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'agent_nodes' AND column_name = 'traffic_weight'`, + ).Scan(&count) + if err != nil { + return nil // Unexpected error querying schema + } + if count > 0 { + return nil // Already migrated + } + + tx, err := ls.db.BeginTx(ctx, nil) + if err != nil { + return fmt.Errorf("failed to begin postgres migration transaction: %w", err) + } + defer func() { + if err != nil { + _ = tx.Rollback() + } + }() + + // Ensure columns from recent features exist before altering PK. + ensureColumns := []string{ + `ALTER TABLE agent_nodes ADD COLUMN IF NOT EXISTS version TEXT NOT NULL DEFAULT ''`, + `ALTER TABLE agent_nodes ADD COLUMN IF NOT EXISTS group_id TEXT NOT NULL DEFAULT ''`, + `ALTER TABLE agent_nodes ADD COLUMN IF NOT EXISTS proposed_tags BYTEA`, + `ALTER TABLE agent_nodes ADD COLUMN IF NOT EXISTS approved_tags BYTEA`, + } + for _, ddl := range ensureColumns { + if _, err = tx.ExecContext(ctx, ddl); err != nil { + return fmt.Errorf("postgres ensure column failed: %w", err) + } + } + // Backfill group_id with id where empty + if _, err = tx.ExecContext(ctx, `UPDATE agent_nodes SET group_id = id WHERE group_id = '' OR group_id IS NULL`); err != nil { + return fmt.Errorf("postgres backfill group_id failed: %w", err) + } + + migrations := []string{ + `ALTER TABLE agent_nodes DROP CONSTRAINT IF EXISTS agent_nodes_pkey`, + `ALTER TABLE agent_nodes ALTER COLUMN version SET DEFAULT ''`, + `ALTER TABLE agent_nodes ADD PRIMARY KEY (id, version)`, + `ALTER TABLE agent_nodes ADD COLUMN IF NOT EXISTS traffic_weight INTEGER NOT NULL DEFAULT 100`, + } + + for _, m := range migrations { + if _, err = tx.ExecContext(ctx, m); err != nil { + return fmt.Errorf("postgres composite PK migration failed: %w", err) + } + } + + if err = tx.Commit(); err != nil { + return fmt.Errorf("failed to commit postgres composite PK migration: %w", err) + } + + fmt.Println("[migration] agent_nodes table migrated to composite PK (id, version) with traffic_weight [postgres]") + return nil +} + func (ls *LocalStorage) autoMigrateSchema(ctx context.Context) error { + // Run composite PK migration before GORM auto-migrate + if ls.mode == "local" { + if err := ls.migrateAgentNodesCompositePK(ctx); err != nil { + return fmt.Errorf("agent_nodes composite PK migration failed: %w", err) + } + } else { + if err := ls.migrateAgentNodesCompositePKPostgres(ctx); err != nil { + return fmt.Errorf("agent_nodes composite PK migration (postgres) failed: %w", err) + } + } + gormDB, err := ls.gormWithContext(ctx) if err != nil { return fmt.Errorf("failed to initialize gorm for migrations: %w", err) @@ -45,6 +229,10 @@ func (ls *LocalStorage) autoMigrateSchema(ctx context.Context) error { &ExecutionWebhookModel{}, &ObservabilityWebhookModel{}, &ObservabilityDeadLetterQueueModel{}, + // VC Authorization models + &DIDDocumentModel{}, + &AccessPolicyModel{}, + &AgentTagVCModel{}, } if err := gormDB.WithContext(ctx).AutoMigrate(models...); err != nil { diff --git a/control-plane/internal/storage/models.go b/control-plane/internal/storage/models.go index 663e1c81..bd2761ed 100644 --- a/control-plane/internal/storage/models.go +++ b/control-plane/internal/storage/models.go @@ -51,9 +51,11 @@ func (AgentExecutionModel) TableName() string { return "agent_executions" } type AgentNodeModel struct { ID string `gorm:"column:id;primaryKey"` + Version string `gorm:"column:version;primaryKey;not null;default:''"` + GroupID string `gorm:"column:group_id;not null;default:'';index"` TeamID string `gorm:"column:team_id;not null;index"` BaseURL string `gorm:"column:base_url;not null"` - Version string `gorm:"column:version;not null"` + TrafficWeight int `gorm:"column:traffic_weight;not null;default:100"` DeploymentType string `gorm:"column:deployment_type;default:'long_running';index"` InvocationURL *string `gorm:"column:invocation_url"` Reasoners []byte `gorm:"column:reasoners"` @@ -65,6 +67,8 @@ type AgentNodeModel struct { RegisteredAt time.Time `gorm:"column:registered_at;autoCreateTime"` Features []byte `gorm:"column:features"` Metadata []byte `gorm:"column:metadata"` + ProposedTags []byte `gorm:"column:proposed_tags"` + ApprovedTags []byte `gorm:"column:approved_tags"` } func (AgentNodeModel) TableName() string { return "agent_nodes" } @@ -410,3 +414,52 @@ type ObservabilityDeadLetterQueueModel struct { } func (ObservabilityDeadLetterQueueModel) TableName() string { return "observability_dead_letter_queue" } + +// DIDDocumentModel represents a DID document record for did:web resolution. +type DIDDocumentModel struct { + DID string `gorm:"column:did;primaryKey"` + AgentID string `gorm:"column:agent_id;not null;index"` + DIDDocument []byte `gorm:"column:did_document;type:jsonb;not null"` // JSONB in PostgreSQL, TEXT in SQLite + PublicKeyJWK string `gorm:"column:public_key_jwk;not null"` + RevokedAt *time.Time `gorm:"column:revoked_at;index"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime"` +} + +func (DIDDocumentModel) TableName() string { return "did_documents" } + +// AccessPolicyModel represents a tag-based access policy for cross-agent calls. +type AccessPolicyModel struct { + ID int64 `gorm:"column:id;primaryKey;autoIncrement"` + Name string `gorm:"column:name;not null;uniqueIndex"` + CallerTags string `gorm:"column:caller_tags;type:text;not null"` // JSON array + TargetTags string `gorm:"column:target_tags;type:text;not null"` // JSON array + AllowFunctions string `gorm:"column:allow_functions;type:text"` // JSON array + DenyFunctions string `gorm:"column:deny_functions;type:text"` // JSON array + Constraints string `gorm:"column:constraints;type:text"` // JSON object + Action string `gorm:"column:action;not null;default:'allow'"` + Priority int `gorm:"column:priority;not null;default:0;index"` + Enabled bool `gorm:"column:enabled;not null;default:true;index"` + Description *string `gorm:"column:description"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime"` +} + +func (AccessPolicyModel) TableName() string { return "access_policies" } + +// AgentTagVCModel stores signed Agent Tag VCs issued on tag approval. +type AgentTagVCModel struct { + ID int64 `gorm:"column:id;primaryKey;autoIncrement"` + AgentID string `gorm:"column:agent_id;uniqueIndex;not null"` + AgentDID string `gorm:"column:agent_did;not null;index"` + VCID string `gorm:"column:vc_id;uniqueIndex;not null"` + VCDocument string `gorm:"column:vc_document;type:text;not null"` + Signature string `gorm:"column:signature;type:text"` + IssuedAt time.Time `gorm:"column:issued_at;not null"` + ExpiresAt *time.Time `gorm:"column:expires_at"` + RevokedAt *time.Time `gorm:"column:revoked_at"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime"` +} + +func (AgentTagVCModel) TableName() string { return "agent_tag_vcs" } diff --git a/control-plane/internal/storage/postgres_test.go b/control-plane/internal/storage/postgres_test.go index 2b9e5f76..11841ba0 100644 --- a/control-plane/internal/storage/postgres_test.go +++ b/control-plane/internal/storage/postgres_test.go @@ -43,9 +43,10 @@ func TestPostgresStorage_ConnectionPooling(t *testing.T) { defer ls.Close(ctx) // Test that we can create and retrieve records + execID := fmt.Sprintf("exec-pg-pool-%d", time.Now().UnixNano()) exec := &types.Execution{ - ExecutionID: "exec-pg-1", - RunID: "run-pg-1", + ExecutionID: execID, + RunID: fmt.Sprintf("run-pg-pool-%d", time.Now().UnixNano()), AgentNodeID: "agent-1", ReasonerID: "reasoner-1", NodeID: "node-1", @@ -56,7 +57,7 @@ func TestPostgresStorage_ConnectionPooling(t *testing.T) { err = ls.CreateExecutionRecord(ctx, exec) require.NoError(t, err) - retrieved, err := ls.GetExecutionRecord(ctx, "exec-pg-1") + retrieved, err := ls.GetExecutionRecord(ctx, execID) require.NoError(t, err) require.NotNil(t, retrieved) require.Equal(t, exec.ExecutionID, retrieved.ExecutionID) @@ -187,8 +188,8 @@ func TestPostgresStorage_ConnectionSettings(t *testing.T) { // Verify storage is functional exec := &types.Execution{ - ExecutionID: "exec-pg-conn", - RunID: "run-pg-conn", + ExecutionID: fmt.Sprintf("exec-pg-conn-%d", time.Now().UnixNano()), + RunID: fmt.Sprintf("run-pg-conn-%d", time.Now().UnixNano()), AgentNodeID: "agent-1", ReasonerID: "reasoner-1", NodeID: "node-1", @@ -228,12 +229,13 @@ func TestPostgresStorage_ConcurrentOperations(t *testing.T) { // Create multiple executions concurrently const numExecutions = 10 done := make(chan error, numExecutions) + runID := fmt.Sprintf("run-pg-concurrent-%d", time.Now().UnixNano()) for i := 0; i < numExecutions; i++ { go func(id int) { exec := &types.Execution{ - ExecutionID: "exec-pg-concurrent-" + string(rune(id)), - RunID: "run-pg-concurrent", + ExecutionID: fmt.Sprintf("exec-pg-concurrent-%d-%d", time.Now().UnixNano(), id), + RunID: runID, AgentNodeID: "agent-1", ReasonerID: "reasoner-1", NodeID: "node-1", @@ -252,7 +254,7 @@ func TestPostgresStorage_ConcurrentOperations(t *testing.T) { // Verify all executions were created results, err := ls.QueryExecutionRecords(ctx, types.ExecutionFilter{ - RunID: stringPtr("run-pg-concurrent"), + RunID: &runID, }) require.NoError(t, err) require.GreaterOrEqual(t, len(results), numExecutions) diff --git a/control-plane/internal/storage/storage.go b/control-plane/internal/storage/storage.go index 972bb5ed..7f61a6e7 100644 --- a/control-plane/internal/storage/storage.go +++ b/control-plane/internal/storage/storage.go @@ -105,11 +105,18 @@ type StorageProvider interface { // Agent registry RegisterAgent(ctx context.Context, agent *types.AgentNode) error GetAgent(ctx context.Context, id string) (*types.AgentNode, error) + GetAgentVersion(ctx context.Context, id string, version string) (*types.AgentNode, error) + DeleteAgentVersion(ctx context.Context, id string, version string) error + ListAgentVersions(ctx context.Context, id string) ([]*types.AgentNode, error) ListAgents(ctx context.Context, filters types.AgentFilters) ([]*types.AgentNode, error) + ListAgentsByGroup(ctx context.Context, groupID string) ([]*types.AgentNode, error) + ListAgentGroups(ctx context.Context, teamID string) ([]types.AgentGroupSummary, error) UpdateAgentHealth(ctx context.Context, id string, status types.HealthStatus) error UpdateAgentHealthAtomic(ctx context.Context, id string, status types.HealthStatus, expectedLastHeartbeat *time.Time) error - UpdateAgentHeartbeat(ctx context.Context, id string, heartbeatTime time.Time) error + UpdateAgentHeartbeat(ctx context.Context, id string, version string, heartbeatTime time.Time) error UpdateAgentLifecycleStatus(ctx context.Context, id string, status types.AgentLifecycleStatus) error + UpdateAgentVersion(ctx context.Context, id string, version string) error + UpdateAgentTrafficWeight(ctx context.Context, id string, version string, weight int) error // Configuration SetConfig(ctx context.Context, key string, value interface{}) error @@ -188,6 +195,29 @@ type StorageProvider interface { GetDeadLetterQueue(ctx context.Context, limit, offset int) ([]types.ObservabilityDeadLetterEntry, error) DeleteFromDeadLetterQueue(ctx context.Context, ids []int64) error ClearDeadLetterQueue(ctx context.Context) error + + // Access policy operations (tag-based authorization) + GetAccessPolicies(ctx context.Context) ([]*types.AccessPolicy, error) + GetAccessPolicyByID(ctx context.Context, id int64) (*types.AccessPolicy, error) + CreateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error + UpdateAccessPolicy(ctx context.Context, policy *types.AccessPolicy) error + DeleteAccessPolicy(ctx context.Context, id int64) error + + // Agent Tag VC operations (tag-based PermissionVC) + StoreAgentTagVC(ctx context.Context, agentID, agentDID, vcID, vcDocument, signature string, issuedAt time.Time, expiresAt *time.Time) error + GetAgentTagVC(ctx context.Context, agentID string) (*types.AgentTagVCRecord, error) + ListAgentTagVCs(ctx context.Context) ([]*types.AgentTagVCRecord, error) + RevokeAgentTagVC(ctx context.Context, agentID string) error + + // DID Document operations (did:web resolution) + StoreDIDDocument(ctx context.Context, record *types.DIDDocumentRecord) error + GetDIDDocument(ctx context.Context, did string) (*types.DIDDocumentRecord, error) + GetDIDDocumentByAgentID(ctx context.Context, agentID string) (*types.DIDDocumentRecord, error) + RevokeDIDDocument(ctx context.Context, did string) error + ListDIDDocuments(ctx context.Context) ([]*types.DIDDocumentRecord, error) + + // Agent lifecycle queries (tag approval workflow) + ListAgentsByLifecycleStatus(ctx context.Context, status types.AgentLifecycleStatus) ([]*types.AgentNode, error) } // ComponentDIDRequest represents a component DID to be stored diff --git a/control-plane/internal/vc_authorization_integration_test.go b/control-plane/internal/vc_authorization_integration_test.go new file mode 100644 index 00000000..c90298dc --- /dev/null +++ b/control-plane/internal/vc_authorization_integration_test.go @@ -0,0 +1,1295 @@ +// Package internal provides integration tests for the VC-based authorization system. +// +// These tests verify the complete flow from storage through services to HTTP handlers +// with minimal mocking, using real SQLite storage for integration validation. +package internal + +import ( + "bytes" + "context" + "crypto/ed25519" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "fmt" + "net/http/httptest" + "path/filepath" + "strconv" + "strings" + "testing" + "time" + + "github.com/Agent-Field/agentfield/control-plane/internal/server/middleware" + "github.com/Agent-Field/agentfield/control-plane/internal/services" + "github.com/Agent-Field/agentfield/control-plane/internal/storage" + "github.com/Agent-Field/agentfield/control-plane/pkg/types" + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// ============================================================================= +// Test Infrastructure +// ============================================================================= + +// testContext holds all components needed for integration testing +type testContext struct { + t *testing.T + ctx context.Context + storage *storage.LocalStorage + didWebService *mockDIDWebService + accessPolicyService *services.AccessPolicyService + router *gin.Engine + cleanup func() +} + +// mockDIDWebService provides a minimal DID web service for testing +type mockDIDWebService struct { + domain string + storage storage.StorageProvider +} + +func newMockDIDWebService(domain string, s storage.StorageProvider) *mockDIDWebService { + return &mockDIDWebService{ + domain: domain, + storage: s, + } +} + +func (m *mockDIDWebService) GenerateDIDWeb(agentID string) string { + encodedDomain := strings.ReplaceAll(m.domain, ":", "%3A") + return fmt.Sprintf("did:web:%s:agents:%s", encodedDomain, agentID) +} + +func (m *mockDIDWebService) ParseDIDWeb(did string) (string, error) { + if !strings.HasPrefix(did, "did:web:") { + return "", fmt.Errorf("invalid did:web format") + } + parts := strings.Split(did, ":") + for i, part := range parts { + if part == "agents" && i+1 < len(parts) { + return parts[i+1], nil + } + } + return "", fmt.Errorf("invalid did:web format: missing 'agents' segment") +} + +func (m *mockDIDWebService) VerifyDIDOwnership(ctx context.Context, did string, message []byte, signature []byte) (bool, error) { + // Look up the DID document to get the public key + record, err := m.storage.GetDIDDocument(ctx, did) + if err != nil { + return false, fmt.Errorf("DID not found: %w", err) + } + + if record.IsRevoked() { + return false, fmt.Errorf("DID is revoked") + } + + // Parse the public key from JWK + var jwk struct { + X string `json:"x"` + } + if err := json.Unmarshal([]byte(record.PublicKeyJWK), &jwk); err != nil { + return false, fmt.Errorf("invalid public key JWK: %w", err) + } + + publicKeyBytes, err := base64.RawURLEncoding.DecodeString(jwk.X) + if err != nil { + return false, fmt.Errorf("failed to decode public key: %w", err) + } + + publicKey := ed25519.PublicKey(publicKeyBytes) + return ed25519.Verify(publicKey, message, signature), nil +} + +func (m *mockDIDWebService) RevokeDID(ctx context.Context, did string) error { + return m.storage.RevokeDIDDocument(ctx, did) +} + +func (m *mockDIDWebService) GetOrCreateDIDDocument(ctx context.Context, agentID string) (*types.DIDWebDocument, string, error) { + did := m.GenerateDIDWeb(agentID) + + // Try to get existing + record, err := m.storage.GetDIDDocument(ctx, did) + if err == nil && !record.IsRevoked() { + var didDoc types.DIDWebDocument + if err := json.Unmarshal(record.DIDDocument, &didDoc); err != nil { + return nil, "", err + } + return &didDoc, did, nil + } + + // Generate new key pair + publicKey, _, err := ed25519.GenerateKey(nil) + if err != nil { + return nil, "", err + } + + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(publicKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record = &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + if err := m.storage.StoreDIDDocument(ctx, record); err != nil { + return nil, "", err + } + + return didDoc, did, nil +} + +func (m *mockDIDWebService) ResolveDID(ctx context.Context, did string) (*types.DIDResolutionResult, error) { + record, err := m.storage.GetDIDDocument(ctx, did) + if err != nil { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{Error: "notFound"}, + }, nil + } + + if record.IsRevoked() { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{Error: "deactivated"}, + DIDDocumentMetadata: types.DIDDocumentMetadata{Deactivated: true}, + }, nil + } + + var didDoc types.DIDWebDocument + if err := json.Unmarshal(record.DIDDocument, &didDoc); err != nil { + return &types.DIDResolutionResult{ + DIDResolutionMetadata: types.DIDResolutionMetadata{Error: "invalidDidDocument"}, + }, nil + } + + return &types.DIDResolutionResult{ + DIDDocument: &didDoc, + DIDResolutionMetadata: types.DIDResolutionMetadata{ContentType: "application/did+ld+json"}, + }, nil +} + +// setupTestContext creates a fully initialized test environment with real storage +func setupTestContext(t *testing.T) *testContext { + t.Helper() + + ctx := context.Background() + tempDir := t.TempDir() + + // Initialize real SQLite storage + cfg := storage.StorageConfig{ + Mode: "local", + Local: storage.LocalStorageConfig{ + DatabasePath: filepath.Join(tempDir, "test_agentfield.db"), + KVStorePath: filepath.Join(tempDir, "test_agentfield.bolt"), + }, + } + + ls := storage.NewLocalStorage(storage.LocalStorageConfig{}) + if err := ls.Initialize(ctx, cfg); err != nil { + if strings.Contains(err.Error(), "no such module: fts5") { + t.Skip("sqlite3 compiled without FTS5; skipping integration test") + } + t.Fatalf("failed to initialize local storage: %v", err) + } + + // Create mock DID Web service (uses real storage) + didWebService := newMockDIDWebService("localhost:8080", ls) + + // Create access policy service (replaces legacy permission service) + accessPolicyService := services.NewAccessPolicyService(ls) + err := accessPolicyService.Initialize(ctx) + require.NoError(t, err, "failed to initialize access policy service") + + // Set up Gin router for HTTP tests + gin.SetMode(gin.TestMode) + router := gin.New() + + // Add test middleware that simulates DID auth verification. + // In production, the DID auth middleware verifies signatures and sets verified_caller_did. + // For integration tests, we trust the X-Caller-DID header directly. + router.Use(func(c *gin.Context) { + if did := c.GetHeader("X-Caller-DID"); did != "" { + c.Set("verified_caller_did", did) + } + c.Next() + }) + + tc := &testContext{ + t: t, + ctx: ctx, + storage: ls, + didWebService: didWebService, + accessPolicyService: accessPolicyService, + router: router, + cleanup: func() { + _ = ls.Close(ctx) + }, + } + + t.Cleanup(tc.cleanup) + + return tc +} + +// createTestAgent creates a test agent in storage with the given ID and tags. +// Tags are stored as approved tags (key:value format) for authorization matching. +// Deployment metadata tags are excluded from authorization — only ApprovedTags +// are used by CanonicalAgentTags for permission enforcement. +func (tc *testContext) createTestAgent(agentID string, tags map[string]string) *types.AgentNode { + tc.t.Helper() + + // Convert key:value tags to canonical approved tags + var approvedTags []string + for k, v := range tags { + approvedTags = append(approvedTags, k+":"+v) + } + + agent := &types.AgentNode{ + ID: agentID, + DeploymentType: "test", + ApprovedTags: approvedTags, + Metadata: types.AgentMetadata{ + Deployment: &types.DeploymentMetadata{ + Tags: tags, + }, + }, + RegisteredAt: time.Now(), + } + + err := tc.storage.RegisterAgent(tc.ctx, agent) + require.NoError(tc.t, err, "failed to register test agent") + + return agent +} + +// ============================================================================= +// Phase 1: Storage Layer Tests +// ============================================================================= + +func TestVCAuth_Phase1_Storage_DIDDocuments(t *testing.T) { + tc := setupTestContext(t) + + t.Run("store and retrieve DID document", func(t *testing.T) { + // Create a DID document + agentID := "test-agent-did-1" + did := tc.didWebService.GenerateDIDWeb(agentID) + + // Generate a test public key JWK + pubKey, _, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(pubKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, err := json.Marshal(didDoc) + require.NoError(t, err) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + // Store the DID document + err = tc.storage.StoreDIDDocument(tc.ctx, record) + require.NoError(t, err) + + // Retrieve by DID + retrieved, err := tc.storage.GetDIDDocument(tc.ctx, did) + require.NoError(t, err) + require.NotNil(t, retrieved) + assert.Equal(t, did, retrieved.DID) + assert.Equal(t, agentID, retrieved.AgentID) + assert.False(t, retrieved.IsRevoked()) + + // Retrieve by agent ID + retrievedByAgent, err := tc.storage.GetDIDDocumentByAgentID(tc.ctx, agentID) + require.NoError(t, err) + require.NotNil(t, retrievedByAgent) + assert.Equal(t, did, retrievedByAgent.DID) + }) + + t.Run("revoke DID document", func(t *testing.T) { + agentID := "test-agent-did-2" + did := tc.didWebService.GenerateDIDWeb(agentID) + + pubKey, _, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(pubKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + err = tc.storage.StoreDIDDocument(tc.ctx, record) + require.NoError(t, err) + + // Revoke the DID + err = tc.storage.RevokeDIDDocument(tc.ctx, did) + require.NoError(t, err) + + // Verify it's revoked + retrieved, err := tc.storage.GetDIDDocument(tc.ctx, did) + require.NoError(t, err) + assert.True(t, retrieved.IsRevoked()) + }) + + t.Run("list DID documents", func(t *testing.T) { + // Create multiple DID documents + for i := 3; i <= 5; i++ { + agentID := fmt.Sprintf("test-agent-did-%d", i) + did := tc.didWebService.GenerateDIDWeb(agentID) + + pubKey, _, _ := ed25519.GenerateKey(nil) + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(pubKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + + _ = tc.storage.StoreDIDDocument(tc.ctx, record) + } + + // List all DID documents + docs, err := tc.storage.ListDIDDocuments(tc.ctx) + require.NoError(t, err) + assert.GreaterOrEqual(t, len(docs), 3) + }) +} + +func TestVCAuth_Phase1_Storage_AccessPolicies(t *testing.T) { + tc := setupTestContext(t) + + t.Run("create and retrieve access policy", func(t *testing.T) { + now := time.Now() + policy := &types.AccessPolicy{ + Name: "test-policy", + CallerTags: []string{"analytics"}, + TargetTags: []string{"data-service"}, + AllowFunctions: []string{"query_*", "get_*"}, + DenyFunctions: []string{"delete_*"}, + Constraints: map[string]types.AccessConstraint{ + "limit": {Operator: "<=", Value: 1000}, + }, + Action: "allow", + Priority: 100, + Enabled: true, + CreatedAt: now, + UpdatedAt: now, + } + + err := tc.storage.CreateAccessPolicy(tc.ctx, policy) + require.NoError(t, err) + assert.NotZero(t, policy.ID, "policy ID should be set after creation") + + // Retrieve by ID + retrieved, err := tc.storage.GetAccessPolicyByID(tc.ctx, policy.ID) + require.NoError(t, err) + assert.Equal(t, "test-policy", retrieved.Name) + assert.Equal(t, "allow", retrieved.Action) + assert.Equal(t, 100, retrieved.Priority) + assert.True(t, retrieved.Enabled) + }) + + t.Run("list access policies", func(t *testing.T) { + policies, err := tc.storage.GetAccessPolicies(tc.ctx) + require.NoError(t, err) + assert.GreaterOrEqual(t, len(policies), 1) + }) + + t.Run("update access policy", func(t *testing.T) { + now := time.Now() + policy := &types.AccessPolicy{ + Name: "to-update", + CallerTags: []string{"caller"}, + TargetTags: []string{"target"}, + Action: "deny", + Priority: 50, + Enabled: true, + CreatedAt: now, + UpdatedAt: now, + } + + err := tc.storage.CreateAccessPolicy(tc.ctx, policy) + require.NoError(t, err) + + policy.Action = "allow" + policy.Priority = 200 + policy.UpdatedAt = time.Now() + err = tc.storage.UpdateAccessPolicy(tc.ctx, policy) + require.NoError(t, err) + + retrieved, err := tc.storage.GetAccessPolicyByID(tc.ctx, policy.ID) + require.NoError(t, err) + assert.Equal(t, "allow", retrieved.Action) + assert.Equal(t, 200, retrieved.Priority) + }) + + t.Run("delete access policy", func(t *testing.T) { + now := time.Now() + policy := &types.AccessPolicy{ + Name: "to-delete", + CallerTags: []string{"temp"}, + TargetTags: []string{"temp"}, + Action: "allow", + Priority: 10, + Enabled: true, + CreatedAt: now, + UpdatedAt: now, + } + + err := tc.storage.CreateAccessPolicy(tc.ctx, policy) + require.NoError(t, err) + + err = tc.storage.DeleteAccessPolicy(tc.ctx, policy.ID) + require.NoError(t, err) + + _, err = tc.storage.GetAccessPolicyByID(tc.ctx, policy.ID) + assert.Error(t, err, "deleted policy should not be retrievable") + }) +} + +// ============================================================================= +// Phase 2: Service Layer Tests +// ============================================================================= + +func TestVCAuth_Phase2_Service_DIDWebService(t *testing.T) { + tc := setupTestContext(t) + + t.Run("generate DID web identifier", func(t *testing.T) { + did := tc.didWebService.GenerateDIDWeb("my-agent") + assert.Contains(t, did, "did:web:") + assert.Contains(t, did, "agents:my-agent") + }) + + t.Run("parse DID web identifier", func(t *testing.T) { + did := tc.didWebService.GenerateDIDWeb("parsed-agent") + agentID, err := tc.didWebService.ParseDIDWeb(did) + require.NoError(t, err) + assert.Equal(t, "parsed-agent", agentID) + }) + + t.Run("get or create DID document", func(t *testing.T) { + agentID := "new-agent-did" + + // First call creates + didDoc1, did1, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, agentID) + require.NoError(t, err) + require.NotNil(t, didDoc1) + assert.Contains(t, did1, agentID) + + // Second call returns existing + didDoc2, did2, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, agentID) + require.NoError(t, err) + assert.Equal(t, did1, did2) + assert.Equal(t, didDoc1.ID, didDoc2.ID) + }) + + t.Run("resolve DID", func(t *testing.T) { + agentID := "resolvable-agent" + _, did, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, agentID) + require.NoError(t, err) + + // Resolve the DID + result, err := tc.didWebService.ResolveDID(tc.ctx, did) + require.NoError(t, err) + assert.NotNil(t, result.DIDDocument) + assert.Empty(t, result.DIDResolutionMetadata.Error) + }) + + t.Run("resolve non-existent DID returns not found", func(t *testing.T) { + result, err := tc.didWebService.ResolveDID(tc.ctx, "did:web:localhost:agents:nonexistent") + require.NoError(t, err) + assert.Equal(t, "notFound", result.DIDResolutionMetadata.Error) + }) + + t.Run("resolve revoked DID returns deactivated", func(t *testing.T) { + agentID := "to-revoke-agent" + _, did, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, agentID) + require.NoError(t, err) + + // Revoke + err = tc.didWebService.RevokeDID(tc.ctx, did) + require.NoError(t, err) + + // Resolve should show deactivated + result, err := tc.didWebService.ResolveDID(tc.ctx, did) + require.NoError(t, err) + assert.Equal(t, "deactivated", result.DIDResolutionMetadata.Error) + assert.True(t, result.DIDDocumentMetadata.Deactivated) + }) +} + +func TestVCAuth_Phase2_Service_AccessPolicyService(t *testing.T) { + tc := setupTestContext(t) + + t.Run("add and evaluate allow policy", func(t *testing.T) { + req := &types.AccessPolicyRequest{ + Name: "analytics-to-data", + CallerTags: []string{"analytics"}, + TargetTags: []string{"data-service"}, + AllowFunctions: []string{"query_*", "get_*"}, + DenyFunctions: []string{"delete_*"}, + Constraints: map[string]types.AccessConstraint{ + "limit": {Operator: "<=", Value: float64(1000)}, + }, + Action: "allow", + Priority: 100, + } + + policy, err := tc.accessPolicyService.AddPolicy(tc.ctx, req) + require.NoError(t, err) + assert.NotZero(t, policy.ID) + + // Evaluate: analytics caller → data-service target → query_data → allowed + result := tc.accessPolicyService.EvaluateAccess( + []string{"analytics"}, []string{"data-service"}, + "query_data", map[string]any{"limit": float64(500)}, + ) + assert.True(t, result.Matched, "policy should match") + assert.True(t, result.Allowed, "access should be allowed") + assert.Equal(t, "analytics-to-data", result.PolicyName) + }) + + t.Run("deny function takes precedence", func(t *testing.T) { + result := tc.accessPolicyService.EvaluateAccess( + []string{"analytics"}, []string{"data-service"}, + "delete_records", map[string]any{}, + ) + assert.True(t, result.Matched, "policy should match") + assert.False(t, result.Allowed, "delete should be denied") + assert.Contains(t, result.Reason, "denied") + }) + + t.Run("constraint violation denies access", func(t *testing.T) { + result := tc.accessPolicyService.EvaluateAccess( + []string{"analytics"}, []string{"data-service"}, + "query_data", map[string]any{"limit": float64(5000)}, + ) + assert.True(t, result.Matched, "policy should match") + assert.False(t, result.Allowed, "over-limit query should be denied") + assert.Contains(t, result.Reason, "Constraint violation") + }) + + t.Run("non-matching tags yield no match", func(t *testing.T) { + result := tc.accessPolicyService.EvaluateAccess( + []string{"unknown"}, []string{"data-service"}, + "query_data", nil, + ) + assert.False(t, result.Matched, "policy should not match for unknown caller tag") + }) + + t.Run("update policy changes behavior", func(t *testing.T) { + policies, err := tc.accessPolicyService.ListPolicies(tc.ctx) + require.NoError(t, err) + require.NotEmpty(t, policies) + + policyID := policies[0].ID + + updateReq := &types.AccessPolicyRequest{ + Name: "analytics-to-data-updated", + CallerTags: []string{"analytics"}, + TargetTags: []string{"data-service"}, + Action: "deny", // Changed to deny + Priority: 100, + } + + updated, err := tc.accessPolicyService.UpdatePolicy(tc.ctx, policyID, updateReq) + require.NoError(t, err) + assert.Equal(t, "deny", updated.Action) + + result := tc.accessPolicyService.EvaluateAccess( + []string{"analytics"}, []string{"data-service"}, + "query_data", nil, + ) + assert.True(t, result.Matched) + assert.False(t, result.Allowed, "should be denied after policy update") + }) + + t.Run("remove policy removes enforcement", func(t *testing.T) { + policies, err := tc.accessPolicyService.ListPolicies(tc.ctx) + require.NoError(t, err) + require.NotEmpty(t, policies) + + err = tc.accessPolicyService.RemovePolicy(tc.ctx, policies[0].ID) + require.NoError(t, err) + + result := tc.accessPolicyService.EvaluateAccess( + []string{"analytics"}, []string{"data-service"}, + "query_data", nil, + ) + assert.False(t, result.Matched, "no policy should match after deletion") + }) +} + +// ============================================================================= +// Phase 3: Middleware Tests +// ============================================================================= + +func TestVCAuth_Phase3_Middleware_DIDAuth(t *testing.T) { + tc := setupTestContext(t) + + // Generate test key pair + publicKey, privateKey, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + // Create DID and store document + agentID := "middleware-test-agent" + did := tc.didWebService.GenerateDIDWeb(agentID) + + // Store DID document with our test key + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(publicKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + err = tc.storage.StoreDIDDocument(tc.ctx, record) + require.NoError(t, err) + + // Helper to sign requests + signRequest := func(body []byte) (string, string) { + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + return base64.StdEncoding.EncodeToString(signature), timestamp + } + + t.Run("request without DID passes through", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + req := httptest.NewRequest("POST", "/test", strings.NewReader(`{}`)) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 200, w.Code) + }) + + t.Run("request with valid DID signature succeeds", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + verifiedDID := middleware.GetVerifiedCallerDID(c) + c.JSON(200, gin.H{"verified_did": verifiedDID}) + }) + + body := []byte(`{"test":"data"}`) + signature, timestamp := signRequest(body) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", signature) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 200, w.Code) + + var response map[string]string + json.Unmarshal(w.Body.Bytes(), &response) + assert.Equal(t, did, response["verified_did"]) + }) + + t.Run("request with DID but missing signature fails", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + req := httptest.NewRequest("POST", "/test", strings.NewReader(`{}`)) + req.Header.Set("X-Caller-DID", did) + // Missing signature and timestamp + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code) + }) + + t.Run("request with invalid signature fails", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + body := []byte(`{"test":"data"}`) + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString([]byte("invalid"))) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code) + }) + + t.Run("request with expired timestamp fails", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + body := []byte(`{"test":"data"}`) + // Use timestamp 10 minutes ago + oldTimestamp := strconv.FormatInt(time.Now().Add(-10*time.Minute).Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", oldTimestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", oldTimestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code) + }) +} + +// ============================================================================= +// Phase 5: End-to-End Integration Tests +// ============================================================================= + +func TestVCAuth_Phase5_EndToEnd_DIDAuthentication(t *testing.T) { + tc := setupTestContext(t) + + // Generate key pair for the calling agent + publicKey, privateKey, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + agentID := "did-auth-e2e-agent" + did := tc.didWebService.GenerateDIDWeb(agentID) + + // Store DID document with the test public key + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(publicKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + tc.storage.StoreDIDDocument(tc.ctx, record) + + // Helper to create signed requests + signAndSend := func(router *gin.Engine, method, path string, body []byte) *httptest.ResponseRecorder { + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + req := httptest.NewRequest(method, path, bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + return w + } + + t.Run("authenticated request succeeds with valid signature", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + verifiedDID := middleware.GetVerifiedCallerDID(c) + c.JSON(200, gin.H{ + "success": true, + "verified_did": verifiedDID, + }) + }) + + body := []byte(`{"action": "test"}`) + w := signAndSend(router, "POST", "/test", body) + + assert.Equal(t, 200, w.Code) + + var response map[string]interface{} + json.Unmarshal(w.Body.Bytes(), &response) + assert.True(t, response["success"].(bool)) + assert.Equal(t, did, response["verified_did"]) + }) + + t.Run("request with tampered body fails", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"success": true}) + }) + + // Sign with original body + originalBody := []byte(`{"action": "original"}`) + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(originalBody) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + // Send with different body + tamperedBody := []byte(`{"action": "tampered"}`) + req := httptest.NewRequest("POST", "/test", bytes.NewReader(tamperedBody)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code) + }) + + t.Run("replay attack with old timestamp fails", func(t *testing.T) { + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, // 5 minutes + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"success": true}) + }) + + body := []byte(`{"action": "test"}`) + // Use timestamp from 10 minutes ago + oldTimestamp := strconv.FormatInt(time.Now().Add(-10*time.Minute).Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", oldTimestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", oldTimestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code) + }) +} + +// ============================================================================= +// Phase 6: SDK Compatibility Tests +// ============================================================================= + +func TestVCAuth_Phase6_SDK_GoClientDIDAuth(t *testing.T) { + tc := setupTestContext(t) + + t.Run("SDK signing produces valid signature", func(t *testing.T) { + // Generate test key pair + publicKey, privateKey, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + agentID := "sdk-test-agent" + did := tc.didWebService.GenerateDIDWeb(agentID) + + // Store DID document with public key + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(publicKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: agentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + tc.storage.StoreDIDDocument(tc.ctx, record) + + // Create private key JWK for SDK + privateKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","d":"%s","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(privateKey.Seed()), + base64.RawURLEncoding.EncodeToString(publicKey)) + + // Simulate SDK signing (matching did_auth.go implementation) + body := []byte(`{"target": "other-agent.skill", "input": {"data": "test"}}`) + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + signatureB64 := base64.StdEncoding.EncodeToString(signature) + + // Set up router with DID auth middleware + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/execute", func(c *gin.Context) { + verifiedDID := middleware.GetVerifiedCallerDID(c) + c.JSON(200, gin.H{"verified_did": verifiedDID}) + }) + + // Make request with SDK-style headers + req := httptest.NewRequest("POST", "/execute", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", signatureB64) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 200, w.Code) + + var response map[string]string + json.Unmarshal(w.Body.Bytes(), &response) + assert.Equal(t, did, response["verified_did"]) + + t.Logf("SDK signature verification successful for DID: %s", did) + t.Logf("Private key JWK (for SDK testing): %s", privateKeyJWK) + }) +} + +// ============================================================================= +// Regression: DID:web document lifecycle during agent registration +// ============================================================================= + +// TestVCAuth_Regression_DIDWebDocumentCreatedDuringRegistration is a regression test +// for a bug where GetOrCreateDIDDocument was never called during agent registration, +// causing VerifyDIDOwnership (DID auth middleware) to always fail with "notFound" +// because no DID:web document existed in storage. +// +// The fix (in RegisterNodeHandler) calls GetOrCreateDIDDocument after DID:key +// registration. This test ensures that flow works end-to-end and catches any +// regression that would break it. +func TestVCAuth_Regression_DIDWebDocumentCreatedDuringRegistration(t *testing.T) { + tc := setupTestContext(t) + + agentID := "regression-agent-lifecycle" + + t.Run("without DID:web document, auth middleware rejects signed requests", func(t *testing.T) { + // Simulate the OLD broken behavior: agent is registered in storage + // but GetOrCreateDIDDocument is never called. + agent := tc.createTestAgent(agentID+"-broken", nil) + _ = agent + + // The DID:web identifier exists as a string... + did := tc.didWebService.GenerateDIDWeb(agentID + "-broken") + + // ...but no DID document was stored, so ResolveDID returns "notFound" + result, err := tc.didWebService.ResolveDID(tc.ctx, did) + require.NoError(t, err) + assert.Equal(t, "notFound", result.DIDResolutionMetadata.Error, + "BUG REGRESSION: ResolveDID should return notFound when GetOrCreateDIDDocument was never called") + assert.Nil(t, result.DIDDocument) + + // VerifyDIDOwnership should also fail + valid, err := tc.didWebService.VerifyDIDOwnership(tc.ctx, did, []byte("test"), []byte("sig")) + assert.Error(t, err) + assert.False(t, valid) + assert.Contains(t, err.Error(), "not found", + "BUG REGRESSION: VerifyDIDOwnership fails because no DID:web document exists") + }) + + t.Run("with GetOrCreateDIDDocument called during registration, auth middleware accepts signed requests", func(t *testing.T) { + // Simulate the FIXED behavior: agent is registered AND GetOrCreateDIDDocument + // is called, just like RegisterNodeHandler does after the fix. + agent := tc.createTestAgent(agentID, nil) + _ = agent + + // This is the critical call that the fix adds to RegisterNodeHandler. + didDoc, did, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, agentID) + require.NoError(t, err, "GetOrCreateDIDDocument must succeed during registration") + require.NotNil(t, didDoc, "DID document must be created") + assert.Contains(t, did, agentID) + + // Verify the document is now resolvable + result, err := tc.didWebService.ResolveDID(tc.ctx, did) + require.NoError(t, err) + assert.Empty(t, result.DIDResolutionMetadata.Error, + "After GetOrCreateDIDDocument, ResolveDID must succeed") + require.NotNil(t, result.DIDDocument, "DID document must be resolvable") + assert.Equal(t, did, result.DIDDocument.ID) + + // Verify the document has a verification method with a public key + require.NotEmpty(t, result.DIDDocument.VerificationMethod, + "DID document must have at least one verification method") + vm := result.DIDDocument.VerificationMethod[0] + assert.Equal(t, "JsonWebKey2020", vm.Type) + assert.NotEmpty(t, vm.PublicKeyJwk, "Verification method must contain a public key JWK") + + // Extract the public key and generate a matching private key to sign a request, + // then verify through the middleware. We use the stored public key to prove the + // full chain works. + var jwk struct { + X string `json:"x"` + } + err = json.Unmarshal(vm.PublicKeyJwk, &jwk) + require.NoError(t, err, "Public key JWK must be valid JSON") + + publicKeyBytes, err := base64.RawURLEncoding.DecodeString(jwk.X) + require.NoError(t, err) + assert.Len(t, publicKeyBytes, ed25519.PublicKeySize, + "Public key must be a valid Ed25519 key") + }) + + t.Run("idempotent: calling GetOrCreateDIDDocument twice returns same document", func(t *testing.T) { + reregAgentID := agentID + "-rereg" + tc.createTestAgent(reregAgentID, nil) + + // First call (initial registration) + doc1, did1, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, reregAgentID) + require.NoError(t, err) + require.NotNil(t, doc1) + + // Second call (re-registration) + doc2, did2, err := tc.didWebService.GetOrCreateDIDDocument(tc.ctx, reregAgentID) + require.NoError(t, err) + require.NotNil(t, doc2) + + assert.Equal(t, did1, did2, "DID must be stable across re-registrations") + assert.Equal(t, doc1.ID, doc2.ID, "Document ID must be stable across re-registrations") + }) + + t.Run("end-to-end: registered agent can authenticate through DID middleware", func(t *testing.T) { + // This is the full end-to-end flow: + // 1. Agent registered in storage + // 2. GetOrCreateDIDDocument called (our fix) + // 3. Agent signs a request + // 4. DID auth middleware verifies the signature + + e2eAgentID := agentID + "-e2e" + tc.createTestAgent(e2eAgentID, nil) + + // Create a known key pair for signing + publicKey, privateKey, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + // Store a DID document with our known test key (simulating what + // GetOrCreateDIDDocument does, but with a key we control for signing) + did := tc.didWebService.GenerateDIDWeb(e2eAgentID) + pubKeyJWK := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","x":"%s"}`, + base64.RawURLEncoding.EncodeToString(publicKey)) + + didDoc := types.NewDIDWebDocument(did, json.RawMessage(pubKeyJWK)) + docBytes, _ := json.Marshal(didDoc) + + record := &types.DIDDocumentRecord{ + DID: did, + AgentID: e2eAgentID, + DIDDocument: docBytes, + PublicKeyJWK: pubKeyJWK, + CreatedAt: time.Now(), + UpdatedAt: time.Now(), + } + err = tc.storage.StoreDIDDocument(tc.ctx, record) + require.NoError(t, err) + + // Set up router with DID auth middleware + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + verifiedDID := middleware.GetVerifiedCallerDID(c) + c.JSON(200, gin.H{"verified_did": verifiedDID}) + }) + + // Sign a request + body := []byte(`{"action":"test-registration-flow"}`) + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 200, w.Code, + "Registered agent with DID:web document must pass DID auth middleware") + + var response map[string]string + err = json.Unmarshal(w.Body.Bytes(), &response) + require.NoError(t, err) + assert.Equal(t, did, response["verified_did"], + "Middleware must set the verified DID in context") + }) + + t.Run("end-to-end: unregistered DID:web document fails auth middleware", func(t *testing.T) { + // Agent exists in storage but NO DID:web document was created. + // This is the exact bug scenario. The middleware must reject. + noDocAgentID := agentID + "-no-doc" + tc.createTestAgent(noDocAgentID, nil) + + // Generate a key pair (agent has keys, but no doc in storage) + _, privateKey, err := ed25519.GenerateKey(nil) + require.NoError(t, err) + + did := tc.didWebService.GenerateDIDWeb(noDocAgentID) + + // Set up router with DID auth middleware + router := gin.New() + router.Use(middleware.DIDAuthMiddleware(tc.didWebService, middleware.DIDAuthConfig{ + Enabled: true, + TimestampWindowSeconds: 300, + })) + router.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // Sign a request + body := []byte(`{"action":"test-no-doc"}`) + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%x", timestamp, bodyHash) + signature := ed25519.Sign(privateKey, []byte(payload)) + + req := httptest.NewRequest("POST", "/test", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Caller-DID", did) + req.Header.Set("X-DID-Signature", base64.StdEncoding.EncodeToString(signature)) + req.Header.Set("X-DID-Timestamp", timestamp) + + w := httptest.NewRecorder() + router.ServeHTTP(w, req) + + assert.Equal(t, 401, w.Code, + "Agent without DID:web document must be rejected by auth middleware") + + var errResponse map[string]string + err = json.Unmarshal(w.Body.Bytes(), &errResponse) + require.NoError(t, err) + assert.Equal(t, "verification_error", errResponse["error"], + "Error must indicate verification failure due to missing document") + }) +} + +// ============================================================================= +// Phase 8: Re-registration State Preservation (D3) +// ============================================================================= + +func TestVCAuth_ReRegistration_PreservesApprovalState(t *testing.T) { + tc := setupTestContext(t) + + t.Run("ready agent re-registering stays ready", func(t *testing.T) { + agent := &types.AgentNode{ + ID: "reregister-ready", + LifecycleStatus: types.AgentStatusReady, + ApprovedTags: []string{"finance:billing"}, + RegisteredAt: time.Now(), + } + err := tc.storage.RegisterAgent(tc.ctx, agent) + require.NoError(t, err) + + // Verify the agent is ready + stored, err := tc.storage.GetAgent(tc.ctx, "reregister-ready") + require.NoError(t, err) + assert.Equal(t, types.AgentStatusReady, stored.LifecycleStatus) + assert.Equal(t, []string{"finance:billing"}, stored.ApprovedTags) + }) + + t.Run("admin-revoked agent stays pending on re-register", func(t *testing.T) { + // Create an agent that was admin-revoked: pending_approval + empty approved tags + agent := &types.AgentNode{ + ID: "reregister-revoked", + LifecycleStatus: types.AgentStatusPendingApproval, + ApprovedTags: nil, // Admin cleared approved tags + ProposedTags: []string{"sensitive"}, + RegisteredAt: time.Now(), + } + err := tc.storage.RegisterAgent(tc.ctx, agent) + require.NoError(t, err) + + // Verify admin-revoked state is stored + stored, err := tc.storage.GetAgent(tc.ctx, "reregister-revoked") + require.NoError(t, err) + assert.Equal(t, types.AgentStatusPendingApproval, stored.LifecycleStatus) + assert.Empty(t, stored.ApprovedTags) + }) +} diff --git a/control-plane/migrations/018_create_permission_approvals.sql b/control-plane/migrations/018_create_permission_approvals.sql new file mode 100644 index 00000000..eee159ef --- /dev/null +++ b/control-plane/migrations/018_create_permission_approvals.sql @@ -0,0 +1,55 @@ +-- +goose Up +-- +goose StatementBegin + +-- Permission approvals table for tracking caller -> target permission requests +CREATE TABLE IF NOT EXISTS permission_approvals ( + id BIGSERIAL PRIMARY KEY, + caller_did TEXT NOT NULL, + target_did TEXT NOT NULL, + caller_agent_id TEXT NOT NULL, + target_agent_id TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'pending', -- pending, approved, rejected, revoked + approved_by TEXT, + approved_at TIMESTAMP WITH TIME ZONE, + rejected_by TEXT, + rejected_at TIMESTAMP WITH TIME ZONE, + revoked_by TEXT, + revoked_at TIMESTAMP WITH TIME ZONE, + expires_at TIMESTAMP WITH TIME ZONE, + reason TEXT, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + + -- Each caller-target pair can only have one active record + CONSTRAINT unique_caller_target UNIQUE (caller_did, target_did) +); + +-- Index for looking up permissions by caller +CREATE INDEX IF NOT EXISTS idx_perm_approvals_caller ON permission_approvals(caller_did); + +-- Index for looking up permissions by target +CREATE INDEX IF NOT EXISTS idx_perm_approvals_target ON permission_approvals(target_did); + +-- Index for filtering by status (pending requests, active approvals) +CREATE INDEX IF NOT EXISTS idx_perm_approvals_status ON permission_approvals(status); + +-- Index for finding expired approvals +CREATE INDEX IF NOT EXISTS idx_perm_approvals_expires ON permission_approvals(expires_at) + WHERE expires_at IS NOT NULL; + +-- Index for efficient lookup by DID pair +CREATE INDEX IF NOT EXISTS idx_perm_approvals_did_pair ON permission_approvals(caller_did, target_did); + +-- +goose StatementEnd + +-- +goose Down +-- +goose StatementBegin + +DROP INDEX IF EXISTS idx_perm_approvals_did_pair; +DROP INDEX IF EXISTS idx_perm_approvals_expires; +DROP INDEX IF EXISTS idx_perm_approvals_status; +DROP INDEX IF EXISTS idx_perm_approvals_target; +DROP INDEX IF EXISTS idx_perm_approvals_caller; +DROP TABLE IF EXISTS permission_approvals; + +-- +goose StatementEnd diff --git a/control-plane/migrations/019_create_did_documents.sql b/control-plane/migrations/019_create_did_documents.sql new file mode 100644 index 00000000..34df0914 --- /dev/null +++ b/control-plane/migrations/019_create_did_documents.sql @@ -0,0 +1,37 @@ +-- +goose Up +-- +goose StatementBegin + +-- DID documents table for did:web resolution +-- Stores the DID document that is served when resolving a did:web identifier +CREATE TABLE IF NOT EXISTS did_documents ( + did TEXT PRIMARY KEY, + agent_id TEXT NOT NULL, + did_document JSONB NOT NULL, -- Full W3C DID Document + public_key_jwk TEXT NOT NULL, -- Public key in JWK format + revoked_at TIMESTAMP WITH TIME ZONE, -- NULL = active, set = revoked + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); + +-- Index for looking up DID documents by agent ID +CREATE INDEX IF NOT EXISTS idx_did_docs_agent ON did_documents(agent_id); + +-- Index for finding revoked DIDs +CREATE INDEX IF NOT EXISTS idx_did_docs_revoked ON did_documents(revoked_at) + WHERE revoked_at IS NOT NULL; + +-- Index for finding active (non-revoked) DIDs +CREATE INDEX IF NOT EXISTS idx_did_docs_active ON did_documents(did) + WHERE revoked_at IS NULL; + +-- +goose StatementEnd + +-- +goose Down +-- +goose StatementBegin + +DROP INDEX IF EXISTS idx_did_docs_active; +DROP INDEX IF EXISTS idx_did_docs_revoked; +DROP INDEX IF EXISTS idx_did_docs_agent; +DROP TABLE IF EXISTS did_documents; + +-- +goose StatementEnd diff --git a/control-plane/migrations/020_create_protected_agents.sql b/control-plane/migrations/020_create_protected_agents.sql new file mode 100644 index 00000000..6157cef1 --- /dev/null +++ b/control-plane/migrations/020_create_protected_agents.sql @@ -0,0 +1,35 @@ +-- +goose Up +-- +goose StatementBegin + +-- Protected agents configuration table +-- Defines which agents require permission to call based on patterns +CREATE TABLE IF NOT EXISTS protected_agents_config ( + id BIGSERIAL PRIMARY KEY, + pattern_type TEXT NOT NULL, -- 'tag', 'tag_pattern', 'agent_id' + pattern TEXT NOT NULL, -- e.g., 'admin', 'finance*', 'payment-gateway' + description TEXT, -- Human-readable description of the rule + enabled BOOLEAN NOT NULL DEFAULT true, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + + -- Each pattern type + pattern combination must be unique + CONSTRAINT unique_pattern UNIQUE (pattern_type, pattern) +); + +-- Index for efficient lookup by pattern type +CREATE INDEX IF NOT EXISTS idx_protected_agents_type ON protected_agents_config(pattern_type); + +-- Index for finding enabled rules only +CREATE INDEX IF NOT EXISTS idx_protected_agents_enabled ON protected_agents_config(enabled) + WHERE enabled = true; + +-- +goose StatementEnd + +-- +goose Down +-- +goose StatementBegin + +DROP INDEX IF EXISTS idx_protected_agents_enabled; +DROP INDEX IF EXISTS idx_protected_agents_type; +DROP TABLE IF EXISTS protected_agents_config; + +-- +goose StatementEnd diff --git a/control-plane/migrations/021_create_access_policies.sql b/control-plane/migrations/021_create_access_policies.sql new file mode 100644 index 00000000..bd25bbb9 --- /dev/null +++ b/control-plane/migrations/021_create_access_policies.sql @@ -0,0 +1,38 @@ +-- +goose Up +-- +goose StatementBegin + +-- Access policies table +-- Defines tag-based authorization policies for cross-agent calls +CREATE TABLE IF NOT EXISTS access_policies ( + id BIGSERIAL PRIMARY KEY, + name TEXT NOT NULL UNIQUE, + caller_tags JSONB NOT NULL DEFAULT '[]', + target_tags JSONB NOT NULL DEFAULT '[]', + allow_functions JSONB DEFAULT '[]', + deny_functions JSONB DEFAULT '[]', + constraints JSONB DEFAULT '{}', + action TEXT NOT NULL DEFAULT 'allow', -- 'allow' or 'deny' + priority INTEGER NOT NULL DEFAULT 0, -- higher = evaluated first + enabled BOOLEAN NOT NULL DEFAULT true, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); + +-- Index for finding enabled policies only +CREATE INDEX IF NOT EXISTS idx_access_policies_enabled ON access_policies(enabled) + WHERE enabled = true; + +-- Index for priority-ordered evaluation +CREATE INDEX IF NOT EXISTS idx_access_policies_priority ON access_policies(priority DESC); + +-- +goose StatementEnd + +-- +goose Down +-- +goose StatementBegin + +DROP INDEX IF EXISTS idx_access_policies_priority; +DROP INDEX IF EXISTS idx_access_policies_enabled; +DROP TABLE IF EXISTS access_policies; + +-- +goose StatementEnd diff --git a/control-plane/migrations/022_create_agent_tag_vcs.sql b/control-plane/migrations/022_create_agent_tag_vcs.sql new file mode 100644 index 00000000..7ae8ec20 --- /dev/null +++ b/control-plane/migrations/022_create_agent_tag_vcs.sql @@ -0,0 +1,20 @@ +-- +goose Up +CREATE TABLE IF NOT EXISTS agent_tag_vcs ( + id BIGSERIAL PRIMARY KEY, + agent_id TEXT NOT NULL UNIQUE, + agent_did TEXT NOT NULL, + vc_id TEXT NOT NULL UNIQUE, + vc_document TEXT NOT NULL, + signature TEXT, + issued_at TIMESTAMP WITH TIME ZONE NOT NULL, + expires_at TIMESTAMP WITH TIME ZONE, + revoked_at TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); + +CREATE INDEX IF NOT EXISTS idx_agent_tag_vcs_agent_did ON agent_tag_vcs(agent_did); +CREATE INDEX IF NOT EXISTS idx_agent_tag_vcs_vc_id ON agent_tag_vcs(vc_id); + +-- +goose Down +DROP TABLE IF EXISTS agent_tag_vcs; diff --git a/control-plane/migrations/023_drop_dead_tables.sql b/control-plane/migrations/023_drop_dead_tables.sql new file mode 100644 index 00000000..d2b4965d --- /dev/null +++ b/control-plane/migrations/023_drop_dead_tables.sql @@ -0,0 +1,6 @@ +-- Migration: Drop unused tables +-- Description: Remove permission_approvals and protected_agents_config tables +-- that were created but never wired into any service or handler code. + +DROP TABLE IF EXISTS protected_agents_config; +DROP TABLE IF EXISTS permission_approvals; diff --git a/control-plane/pkg/types/did_types.go b/control-plane/pkg/types/did_types.go index 0af63beb..39ca3804 100644 --- a/control-plane/pkg/types/did_types.go +++ b/control-plane/pkg/types/did_types.go @@ -113,7 +113,7 @@ type DIDIdentityPackage struct { // DIDIdentity represents a single DID identity with keys. type DIDIdentity struct { DID string `json:"did"` - PrivateKeyJWK string `json:"private_key_jwk"` + PrivateKeyJWK string `json:"private_key_jwk,omitempty"` PublicKeyJWK string `json:"public_key_jwk"` DerivationPath string `json:"derivation_path"` ComponentType string `json:"component_type"` diff --git a/control-plane/pkg/types/did_web_types.go b/control-plane/pkg/types/did_web_types.go new file mode 100644 index 00000000..9c364cb8 --- /dev/null +++ b/control-plane/pkg/types/did_web_types.go @@ -0,0 +1,131 @@ +package types + +import ( + "encoding/json" + "time" +) + +// DIDMethod represents the DID method type. +type DIDMethod string + +const ( + DIDMethodKey DIDMethod = "did:key" + DIDMethodWeb DIDMethod = "did:web" +) + +// DIDWebDocument represents a W3C DID Document for did:web method. +// See: https://www.w3.org/TR/did-core/ +type DIDWebDocument struct { + Context []string `json:"@context"` + ID string `json:"id"` + Controller string `json:"controller,omitempty"` + VerificationMethod []VerificationMethod `json:"verificationMethod"` + Authentication []string `json:"authentication"` + AssertionMethod []string `json:"assertionMethod,omitempty"` + KeyAgreement []string `json:"keyAgreement,omitempty"` + Service []DIDService `json:"service,omitempty"` +} + +// VerificationMethod represents a verification method in a DID Document. +type VerificationMethod struct { + ID string `json:"id"` + Type string `json:"type"` + Controller string `json:"controller"` + PublicKeyJwk json.RawMessage `json:"publicKeyJwk"` +} + +// DIDService represents a service endpoint in a DID Document. +type DIDService struct { + ID string `json:"id"` + Type string `json:"type"` + ServiceEndpoint string `json:"serviceEndpoint"` +} + +// DIDDocumentRecord represents the database record for a DID document. +type DIDDocumentRecord struct { + DID string `json:"did" db:"did"` + AgentID string `json:"agent_id" db:"agent_id"` + DIDDocument json.RawMessage `json:"did_document" db:"did_document"` + PublicKeyJWK string `json:"public_key_jwk" db:"public_key_jwk"` + RevokedAt *time.Time `json:"revoked_at,omitempty" db:"revoked_at"` + CreatedAt time.Time `json:"created_at" db:"created_at"` + UpdatedAt time.Time `json:"updated_at" db:"updated_at"` +} + +// IsRevoked returns true if the DID has been revoked. +func (d *DIDDocumentRecord) IsRevoked() bool { + return d.RevokedAt != nil +} + +// DIDResolutionResult represents the result of resolving a DID. +type DIDResolutionResult struct { + DIDDocument *DIDWebDocument `json:"didDocument,omitempty"` + DIDResolutionMetadata DIDResolutionMetadata `json:"didResolutionMetadata"` + DIDDocumentMetadata DIDDocumentMetadata `json:"didDocumentMetadata"` +} + +// DIDResolutionMetadata contains metadata about the resolution process. +type DIDResolutionMetadata struct { + ContentType string `json:"contentType,omitempty"` + Error string `json:"error,omitempty"` +} + +// DIDDocumentMetadata contains metadata about the DID document. +type DIDDocumentMetadata struct { + Created string `json:"created,omitempty"` + Updated string `json:"updated,omitempty"` + Deactivated bool `json:"deactivated,omitempty"` +} + +// DIDWebConfig holds configuration for did:web generation. +type DIDWebConfig struct { + Domain string `json:"domain" yaml:"domain" mapstructure:"domain"` + BasePath string `json:"base_path" yaml:"base_path" mapstructure:"base_path"` +} + +// GenerateDIDWeb creates a did:web identifier for an agent. +// Format: did:web:{domain}:agents:{agentID} +func GenerateDIDWeb(domain, agentID string) string { + return "did:web:" + domain + ":agents:" + agentID +} + +// GenerateDIDWebVerificationMethodID creates the verification method ID for a did:web. +// Format: {did}#key-1 +func GenerateDIDWebVerificationMethodID(did string) string { + return did + "#key-1" +} + +// NewDIDWebDocument creates a new DID Document for did:web method. +func NewDIDWebDocument(did string, publicKeyJWK json.RawMessage) *DIDWebDocument { + verificationMethodID := GenerateDIDWebVerificationMethodID(did) + + return &DIDWebDocument{ + Context: []string{ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1", + }, + ID: did, + VerificationMethod: []VerificationMethod{ + { + ID: verificationMethodID, + Type: "JsonWebKey2020", + Controller: did, + PublicKeyJwk: publicKeyJWK, + }, + }, + Authentication: []string{verificationMethodID}, + AssertionMethod: []string{verificationMethodID}, + } +} + +// DIDWebConstants holds constants for did:web implementation. +var DIDWebConstants = struct { + VerificationMethodType string + Context []string +}{ + VerificationMethodType: "JsonWebKey2020", + Context: []string{ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1", + }, +} diff --git a/control-plane/pkg/types/permission_types.go b/control-plane/pkg/types/permission_types.go new file mode 100644 index 00000000..3a1b35fb --- /dev/null +++ b/control-plane/pkg/types/permission_types.go @@ -0,0 +1,119 @@ +package types + +import ( + "time" +) + +// AccessPolicy defines a tag-based authorization policy for cross-agent calls. +type AccessPolicy struct { + ID int64 `json:"id" db:"id"` + Name string `json:"name" db:"name"` + CallerTags []string `json:"caller_tags"` + TargetTags []string `json:"target_tags"` + AllowFunctions []string `json:"allow_functions"` + DenyFunctions []string `json:"deny_functions"` + Constraints map[string]AccessConstraint `json:"constraints,omitempty"` + Action string `json:"action" db:"action"` // "allow" or "deny" + Priority int `json:"priority" db:"priority"` + Enabled bool `json:"enabled" db:"enabled"` + Description *string `json:"description,omitempty" db:"description"` + CreatedAt time.Time `json:"created_at" db:"created_at"` + UpdatedAt time.Time `json:"updated_at" db:"updated_at"` +} + +// AccessConstraint defines a parameter constraint for a policy. +type AccessConstraint struct { + Operator string `json:"operator"` // "<=", ">=", "==", "!=", "<", ">" + Value any `json:"value"` +} + +// AccessPolicyRequest represents a request to create or update an access policy. +type AccessPolicyRequest struct { + Name string `json:"name" binding:"required"` + CallerTags []string `json:"caller_tags" binding:"required"` + TargetTags []string `json:"target_tags" binding:"required"` + AllowFunctions []string `json:"allow_functions,omitempty"` + DenyFunctions []string `json:"deny_functions,omitempty"` + Constraints map[string]AccessConstraint `json:"constraints,omitempty"` + Action string `json:"action" binding:"required"` + Priority int `json:"priority,omitempty"` + Description string `json:"description,omitempty"` +} + +// PolicyEvaluationResult represents the outcome of evaluating access policies. +type PolicyEvaluationResult struct { + Allowed bool `json:"allowed"` + Matched bool `json:"matched"` // true if a policy matched + PolicyName string `json:"policy_name"` // which policy matched + PolicyID int64 `json:"policy_id"` + Reason string `json:"reason"` // why allow/deny +} + +// AccessPolicyListResponse represents the response for listing access policies. +type AccessPolicyListResponse struct { + Policies []*AccessPolicy `json:"policies"` + Total int `json:"total"` +} + +// AgentTagVCDocument is a W3C Verifiable Credential certifying an agent's approved tags. +// Issued when an admin approves an agent's tags. Verified at call time. +type AgentTagVCDocument struct { + Context []string `json:"@context"` + Type []string `json:"type"` + ID string `json:"id"` + Issuer string `json:"issuer"` + IssuanceDate string `json:"issuanceDate"` + ExpirationDate string `json:"expirationDate,omitempty"` + CredentialSubject AgentTagVCCredentialSubject `json:"credentialSubject"` + Proof *VCProof `json:"proof,omitempty"` +} + +// AgentTagVCCredentialSubject is the credentialSubject of an AgentTagVC. +type AgentTagVCCredentialSubject struct { + ID string `json:"id"` // Agent's DID + AgentID string `json:"agent_id"` + Permissions AgentTagVCPermissions `json:"permissions"` + ApprovedBy string `json:"approved_by,omitempty"` + ApprovedAt string `json:"approved_at,omitempty"` +} + +// AgentTagVCPermissions contains the approved tags and callee permissions. +type AgentTagVCPermissions struct { + Tags []string `json:"tags"` // Approved tags + AllowedCallees []string `json:"allowed_callees"` // ["*"] = policy decides +} + +// AgentTagVCRecord is the DB record for a stored Agent Tag VC. +type AgentTagVCRecord struct { + ID int64 `json:"id"` + AgentID string `json:"agent_id"` + AgentDID string `json:"agent_did"` + VCID string `json:"vc_id"` + VCDocument string `json:"vc_document"` + Signature string `json:"signature"` + IssuedAt time.Time `json:"issued_at"` + ExpiresAt *time.Time `json:"expires_at,omitempty"` + RevokedAt *time.Time `json:"revoked_at,omitempty"` +} + +// TagApprovalRequest represents a request to approve an agent's tags. +type TagApprovalRequest struct { + ApprovedTags []string `json:"approved_tags" binding:"required"` + SkillTags map[string][]string `json:"skill_tags,omitempty"` + ReasonerTags map[string][]string `json:"reasoner_tags,omitempty"` + Reason string `json:"reason,omitempty"` +} + +// TagRejectionRequest represents a request to reject an agent's tags. +type TagRejectionRequest struct { + Reason string `json:"reason,omitempty"` +} + +// PendingAgentResponse represents the response for a pending agent's tag info. +type PendingAgentResponse struct { + AgentID string `json:"agent_id"` + ProposedTags []string `json:"proposed_tags"` + ApprovedTags []string `json:"approved_tags,omitempty"` + Status string `json:"status"` + RegisteredAt string `json:"registered_at"` +} diff --git a/control-plane/pkg/types/types.go b/control-plane/pkg/types/types.go index 0663cb42..18d8481d 100644 --- a/control-plane/pkg/types/types.go +++ b/control-plane/pkg/types/types.go @@ -156,10 +156,12 @@ type AccessControlMetadata struct { // AgentNode represents a registered agent service. type AgentNode struct { - ID string `json:"id" db:"id"` - TeamID string `json:"team_id" db:"team_id"` - BaseURL string `json:"base_url" db:"base_url"` - Version string `json:"version" db:"version"` + ID string `json:"id" db:"id"` + GroupID string `json:"group_id" db:"group_id"` + TeamID string `json:"team_id" db:"team_id"` + BaseURL string `json:"base_url" db:"base_url"` + Version string `json:"version" db:"version"` + TrafficWeight int `json:"traffic_weight" db:"traffic_weight"` // Weight for A/B traffic distribution (default 100) // Serverless support DeploymentType string `json:"deployment_type" db:"deployment_type"` // "long_running" or "serverless" @@ -178,6 +180,10 @@ type AgentNode struct { Features AgentFeatures `json:"features" db:"features"` Metadata AgentMetadata `json:"metadata" db:"metadata"` + + // Tag approval fields + ProposedTags []string `json:"proposed_tags,omitempty" db:"proposed_tags"` + ApprovedTags []string `json:"approved_tags,omitempty" db:"approved_tags"` } // CallbackDiscoveryInfo captures how the AgentField server resolved an agent callback URL. @@ -207,13 +213,17 @@ type ReasonerDefinition struct { OutputSchema json.RawMessage `json:"output_schema"` MemoryConfig MemoryConfig `json:"memory_config"` Tags []string `json:"tags,omitempty"` + ProposedTags []string `json:"proposed_tags,omitempty"` + ApprovedTags []string `json:"approved_tags,omitempty"` } // SkillDefinition defines a skill provided by an agent node. type SkillDefinition struct { - ID string `json:"id"` - InputSchema json.RawMessage `json:"input_schema"` - Tags []string `json:"tags"` + ID string `json:"id"` + InputSchema json.RawMessage `json:"input_schema"` + Tags []string `json:"tags"` + ProposedTags []string `json:"proposed_tags,omitempty"` + ApprovedTags []string `json:"approved_tags,omitempty"` } // MemoryConfig defines memory configuration for a reasoner. @@ -244,10 +254,11 @@ const ( type AgentLifecycleStatus string const ( - AgentStatusStarting AgentLifecycleStatus = "starting" // Initializing (covers registering + initializing) - AgentStatusReady AgentLifecycleStatus = "ready" // Fully operational - AgentStatusDegraded AgentLifecycleStatus = "degraded" // Partial functionality - AgentStatusOffline AgentLifecycleStatus = "offline" // Not responding + AgentStatusStarting AgentLifecycleStatus = "starting" // Initializing (covers registering + initializing) + AgentStatusReady AgentLifecycleStatus = "ready" // Fully operational + AgentStatusDegraded AgentLifecycleStatus = "degraded" // Partial functionality + AgentStatusOffline AgentLifecycleStatus = "offline" // Not responding + AgentStatusPendingApproval AgentLifecycleStatus = "pending_approval" // Waiting for admin tag approval ) // AgentStatus represents the unified status model for agent nodes. @@ -321,6 +332,7 @@ type AgentStatusUpdate struct { MCPStatus *MCPStatusInfo `json:"mcp_status,omitempty"` Source StatusSource `json:"source"` Reason string `json:"reason,omitempty"` + Version string `json:"version,omitempty"` } // Helper methods for AgentStatus @@ -565,10 +577,19 @@ type ExecutionFilters struct { // AgentFilters holds filters for querying agent nodes. type AgentFilters struct { TeamID *string `json:"team_id,omitempty"` + GroupID *string `json:"group_id,omitempty"` HealthStatus *HealthStatus `json:"health_status,omitempty"` Features []string `json:"features,omitempty"` } +// AgentGroupSummary provides aggregate info about an agent group. +type AgentGroupSummary struct { + GroupID string `json:"group_id"` + TeamID string `json:"team_id"` + NodeCount int `json:"node_count"` + Versions []string `json:"versions"` +} + // EventFilter holds filters for querying memory events. type EventFilter struct { Scope *string `json:"scope,omitempty"` diff --git a/control-plane/web/client/src/App.tsx b/control-plane/web/client/src/App.tsx index 0f66cb64..32d94449 100644 --- a/control-plane/web/client/src/App.tsx +++ b/control-plane/web/client/src/App.tsx @@ -21,6 +21,7 @@ import { WorkflowDeckGLTestPage } from "./pages/WorkflowDeckGLTestPage"; import { DIDExplorerPage } from "./pages/DIDExplorerPage"; import { CredentialsPage } from "./pages/CredentialsPage"; import { ObservabilityWebhookSettingsPage } from "./pages/ObservabilityWebhookSettingsPage"; +import { AuthorizationPage } from "./pages/AuthorizationPage"; import { AuthProvider } from "./contexts/AuthContext"; import { AuthGuard } from "./components/AuthGuard"; @@ -99,6 +100,7 @@ function AppContent() { } /> } /> } /> + } /> } /> diff --git a/control-plane/web/client/src/components/AdminTokenPrompt.tsx b/control-plane/web/client/src/components/AdminTokenPrompt.tsx new file mode 100644 index 00000000..1558c38b --- /dev/null +++ b/control-plane/web/client/src/components/AdminTokenPrompt.tsx @@ -0,0 +1,79 @@ +import { useState } from "react"; +import type { FormEvent } from "react"; +import { useAuth } from "../contexts/AuthContext"; +import { Alert, AlertDescription } from "@/components/ui/alert"; +import { Button } from "@/components/ui/button"; +import { Input } from "@/components/ui/input"; + +/** + * Inline prompt shown on admin pages for managing the admin token. + * Always visible: shows a form when no token is set, or a compact + * status bar with change/clear actions when a token is active. + */ +export function AdminTokenPrompt({ onTokenSet }: { onTokenSet?: () => void }) { + const { adminToken, setAdminToken } = useAuth(); + const [inputToken, setInputToken] = useState(""); + const [editing, setEditing] = useState(false); + + const handleSubmit = (e: FormEvent) => { + e.preventDefault(); + if (!inputToken.trim()) return; + setAdminToken(inputToken.trim()); + setInputToken(""); + setEditing(false); + onTokenSet?.(); + }; + + const handleClear = () => { + setAdminToken(null); + setInputToken(""); + setEditing(false); + }; + + // Token is set — show compact status with change/clear actions + if (adminToken && !editing) { + return ( +
+ + + Admin token set + + + +
+ ); + } + + // No token or editing — show the input form + return ( + + +
+ Admin Token +
+ setInputToken(e.target.value)} + placeholder="Enter admin token" + className="max-w-xs h-8" + autoFocus={editing} + /> + + {editing && ( + + )} +
+
+ + + ); +} diff --git a/control-plane/web/client/src/components/AuthGuard.tsx b/control-plane/web/client/src/components/AuthGuard.tsx index deb2004e..4c98a4c9 100644 --- a/control-plane/web/client/src/components/AuthGuard.tsx +++ b/control-plane/web/client/src/components/AuthGuard.tsx @@ -4,8 +4,9 @@ import { useAuth } from "../contexts/AuthContext"; import { setGlobalApiKey } from "../services/api"; export function AuthGuard({ children }: { children: React.ReactNode }) { - const { apiKey, setApiKey, isAuthenticated, authRequired } = useAuth(); + const { apiKey, setApiKey, setAdminToken, isAuthenticated, authRequired } = useAuth(); const [inputKey, setInputKey] = useState(""); + const [inputAdminToken, setInputAdminToken] = useState(""); const [error, setError] = useState(""); const [validating, setValidating] = useState(false); @@ -26,6 +27,9 @@ export function AuthGuard({ children }: { children: React.ReactNode }) { if (response.ok) { setApiKey(inputKey); setGlobalApiKey(inputKey); + if (inputAdminToken.trim()) { + setAdminToken(inputAdminToken.trim()); + } } else { setError("Invalid API key"); } @@ -56,6 +60,15 @@ export function AuthGuard({ children }: { children: React.ReactNode }) { autoFocus /> + setInputAdminToken(e.target.value)} + placeholder="Admin Token (optional — for permission management)" + className="w-full p-3 border rounded-md mb-4 bg-background" + disabled={validating} + /> + {error &&

{error}

} + + + ), + }, + ]; + + return ( +
+ {/* Toolbar */} +
+
+ +
+ +
+ +
+
+ + {/* Table */} +
+ + String(item.id)} + emptyState={{ + title: "No access policies", + description: + "Create a policy to enable tag-based authorization for cross-agent calls.", + }} + /> + +
+ + {/* Create/Edit Dialog */} + + + {/* Delete Confirmation Dialog */} + !open && setDeleteId(null)} + > + + + Delete Policy + + Are you sure you want to delete this access policy? This action + cannot be undone. + + + + + + + + +
+ ); +} diff --git a/control-plane/web/client/src/components/authorization/AgentTagsTab.tsx b/control-plane/web/client/src/components/authorization/AgentTagsTab.tsx new file mode 100644 index 00000000..9d4e7d88 --- /dev/null +++ b/control-plane/web/client/src/components/authorization/AgentTagsTab.tsx @@ -0,0 +1,505 @@ +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { CompactTable } from "@/components/ui/CompactTable"; +import { Badge } from "@/components/ui/badge"; +import { FastTableSearch } from "@/components/ui/FastTableSearch"; +import { SegmentedStatusFilter } from "@/components/ui/segmented-status-filter"; +import { + Tooltip, + TooltipContent, + TooltipProvider, + TooltipTrigger, +} from "@/components/ui/tooltip"; +import { + useSuccessNotification, + useErrorNotification, +} from "@/components/ui/notification"; +import * as tagApprovalApi from "../../services/tagApprovalApi"; +import type { AgentTagSummary } from "../../services/tagApprovalApi"; +import type { AccessPolicy } from "../../services/accessPoliciesApi"; +import { TooltipTagList } from "@/components/ui/tooltip-tag-list"; +import { ApproveWithContextDialog } from "./ApproveWithContextDialog"; +import { RevokeDialog } from "./RevokeDialog"; +import { formatRelativeTime } from "../../utils/dateFormat"; + +const GRID_TEMPLATE = + "minmax(140px,2.5fr) minmax(100px,1.5fr) minmax(100px,1.5fr) 90px 110px 100px"; + +const MAX_VISIBLE_TAGS = 2; + +function renderTagCell(tags: string[]) { + if (!tags.length) + return ( + — + ); + const visible = tags.slice(0, MAX_VISIBLE_TAGS); + const overflow = tags.length - MAX_VISIBLE_TAGS; + const content = ( +
+ {visible.map((tag) => ( + + {tag} + + ))} + {overflow > 0 && ( + + +{overflow} + + )} +
+ ); + if (overflow > 0 || tags.some((t) => t.length > 15)) { + return ( + + +
{content}
+ + + + + + ); + } + return content; +} + +type TagStatus = "pending_approval" | "active" | "other"; + +function getTagStatus(agent: AgentTagSummary): TagStatus { + if (agent.lifecycle_status === "pending_approval") return "pending_approval"; + if ( + agent.lifecycle_status === "active" || + agent.lifecycle_status === "online" || + agent.lifecycle_status === "ready" || + agent.lifecycle_status === "offline" || + agent.lifecycle_status === "degraded" || + agent.lifecycle_status === "starting" + ) + return "active"; + return "other"; +} + +interface AgentTagsTabProps { + policies: AccessPolicy[]; + onPendingCountChange: (count: number) => void; +} + +export function AgentTagsTab({ + policies, + onPendingCountChange, +}: AgentTagsTabProps) { + const [agents, setAgents] = useState([]); + const [loading, setLoading] = useState(true); + + const showSuccess = useSuccessNotification(); + const showError = useErrorNotification(); + + // Stable ref for showError to avoid infinite re-render loop in useCallback + const showErrorRef = useRef(showError); + showErrorRef.current = showError; + + // Search & filter + const [searchQuery, setSearchQuery] = useState(""); + const [statusFilter, setStatusFilter] = useState("all"); + + // Sort + const [sortBy, setSortBy] = useState("registered_at"); + const [sortOrder, setSortOrder] = useState<"asc" | "desc">("desc"); + + // Dialogs + const [approveAgent, setApproveAgent] = useState( + null + ); + const [rejectAgent, setRejectAgent] = useState(null); + const [revokeAgent, setRevokeAgent] = useState(null); + const [rejectReason, setRejectReason] = useState(""); + const [rejectLoading, setRejectLoading] = useState(false); + + const fetchAgents = useCallback(async () => { + try { + setLoading(true); + const data = await tagApprovalApi.listAllAgentsWithTags(); + setAgents(data.agents || []); + } catch (err: unknown) { + showErrorRef.current( + "Failed to fetch agents", + err instanceof Error ? err.message : undefined + ); + } finally { + setLoading(false); + } + }, []); + + useEffect(() => { + fetchAgents(); + }, [fetchAgents]); + + // Update pending count + useEffect(() => { + const pending = agents.filter( + (a) => getTagStatus(a) === "pending_approval" + ).length; + onPendingCountChange(pending); + }, [agents, onPendingCountChange]); + + const handleApprove = async (agentId: string, selectedTags: string[]) => { + try { + await tagApprovalApi.approveAgentTags(agentId, { + approved_tags: selectedTags, + }); + showSuccess(`Tags approved for agent ${agentId}`); + fetchAgents(); + } catch (err: unknown) { + showError( + "Failed to approve tags", + err instanceof Error ? err.message : undefined + ); + throw err; + } + }; + + const handleReject = async () => { + if (!rejectAgent) return; + try { + setRejectLoading(true); + await tagApprovalApi.rejectAgentTags(rejectAgent.agent_id, { + reason: rejectReason || undefined, + }); + showSuccess(`Tags rejected for agent ${rejectAgent.agent_id}`); + setRejectAgent(null); + setRejectReason(""); + fetchAgents(); + } catch (err: unknown) { + showError( + "Failed to reject tags", + err instanceof Error ? err.message : undefined + ); + } finally { + setRejectLoading(false); + } + }; + + const handleRevoke = async (agentId: string, reason?: string) => { + try { + await tagApprovalApi.revokeAgentTags(agentId, reason); + showSuccess(`Tags revoked for agent ${agentId}`); + fetchAgents(); + } catch (err: unknown) { + showError( + "Failed to revoke tags", + err instanceof Error ? err.message : undefined + ); + throw err; + } + }; + + const handleSortChange = (field: string) => { + if (sortBy === field) { + setSortOrder(sortOrder === "asc" ? "desc" : "asc"); + } else { + setSortBy(field); + setSortOrder("desc"); + } + }; + + // Status counts + const statusCounts = useMemo(() => { + const pending = agents.filter( + (a) => getTagStatus(a) === "pending_approval" + ).length; + const approved = agents.filter( + (a) => getTagStatus(a) === "active" + ).length; + const other = agents.length - pending - approved; + return { pending, approved, other }; + }, [agents]); + + // Filtered + sorted data + const filteredAgents = useMemo(() => { + let result = agents; + + // Status filter + if (statusFilter !== "all") { + result = result.filter((a) => { + const s = getTagStatus(a); + if (statusFilter === "pending") return s === "pending_approval"; + if (statusFilter === "approved") return s === "active"; + if (statusFilter === "other") return s === "other"; + return true; + }); + } + + // Search + if (searchQuery.trim()) { + const q = searchQuery.toLowerCase(); + result = result.filter( + (a) => + a.agent_id.toLowerCase().includes(q) || + (a.proposed_tags || []).some((t) => t.toLowerCase().includes(q)) || + (a.approved_tags || []).some((t) => t.toLowerCase().includes(q)) + ); + } + + // Sort + const sorted = [...result].sort((a, b) => { + let cmp = 0; + switch (sortBy) { + case "agent_id": + cmp = a.agent_id.localeCompare(b.agent_id); + break; + case "registered_at": + cmp = new Date(a.registered_at).getTime() - new Date(b.registered_at).getTime(); + break; + default: + cmp = 0; + } + return sortOrder === "asc" ? cmp : -cmp; + }); + + return sorted; + }, [agents, statusFilter, searchQuery, sortBy, sortOrder]); + + const statusOptions = useMemo( + () => [ + { value: "all", label: "All", count: agents.length }, + { value: "pending", label: "Pending", count: statusCounts.pending }, + { value: "approved", label: "Approved", count: statusCounts.approved }, + { value: "other", label: "Other", count: statusCounts.other }, + ], + [agents.length, statusCounts] + ); + + const columns = [ + { + key: "agent_id", + header: "Agent ID", + sortable: true, + align: "left" as const, + render: (item: AgentTagSummary) => ( + + {item.agent_id} + + ), + }, + { + key: "proposed_tags", + header: "Requested", + sortable: false, + align: "left" as const, + render: (item: AgentTagSummary) => + renderTagCell(item.proposed_tags || []), + }, + { + key: "approved_tags", + header: "Granted", + sortable: false, + align: "left" as const, + render: (item: AgentTagSummary) => + renderTagCell(item.approved_tags || []), + }, + { + key: "status", + header: "Status", + sortable: false, + align: "center" as const, + render: (item: AgentTagSummary) => { + const status = getTagStatus(item); + switch (status) { + case "pending_approval": + return Pending; + case "active": + return Approved; + default: + return {status}; + } + }, + }, + { + key: "registered_at", + header: "Registered", + sortable: true, + align: "left" as const, + render: (item: AgentTagSummary) => ( + + + + {formatRelativeTime(item.registered_at)} + + + + {new Date(item.registered_at).toLocaleString()} + + + ), + }, + { + key: "actions", + header: "", + sortable: false, + align: "right" as const, + render: (item: AgentTagSummary) => { + const status = getTagStatus(item); + if (status === "pending_approval") { + return ( +
+ + +
+ ); + } + if (status === "active") { + return ( + + ); + } + return null; + }, + }, + ]; + + return ( +
+ {/* Toolbar */} +
+
+ +
+ +
+ + {/* Table */} +
+ + item.agent_id} + emptyState={{ + title: "No agents", + description: + "Agents with tags will appear here once they register with the control plane.", + }} + /> + +
+ + {/* Approve With Context Dialog */} + !open && setApproveAgent(null)} + /> + + {/* Reject Dialog */} + !open && setRejectAgent(null)} + > + + + Reject Tags + + Reject the proposed tags for agent{" "} + + {rejectAgent?.agent_id} + + . The agent will be set to offline status. + + +
+ + setRejectReason(e.target.value)} + className="mt-1.5" + /> +
+ + + + + + + + {/* Revoke Dialog */} + !open && setRevokeAgent(null)} + /> +
+ ); +} diff --git a/control-plane/web/client/src/components/authorization/ApproveWithContextDialog.tsx b/control-plane/web/client/src/components/authorization/ApproveWithContextDialog.tsx new file mode 100644 index 00000000..7ca6e183 --- /dev/null +++ b/control-plane/web/client/src/components/authorization/ApproveWithContextDialog.tsx @@ -0,0 +1,127 @@ +import { useState, useEffect } from "react"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { Label } from "@/components/ui/label"; +import { Badge } from "@/components/ui/badge"; +import { CheckCircle } from "@/components/ui/icon-bridge"; +import { PolicyContextPanel } from "./PolicyContextPanel"; +import type { AccessPolicy } from "../../services/accessPoliciesApi"; +import type { AgentTagSummary } from "../../services/tagApprovalApi"; + +interface ApproveWithContextDialogProps { + agent: AgentTagSummary | null; + policies: AccessPolicy[]; + onApprove: (agentId: string, selectedTags: string[]) => Promise; + onOpenChange: (open: boolean) => void; +} + +export function ApproveWithContextDialog({ + agent, + policies, + onApprove, + onOpenChange, +}: ApproveWithContextDialogProps) { + const [selectedTags, setSelectedTags] = useState([]); + const [loading, setLoading] = useState(false); + + useEffect(() => { + if (agent) { + setSelectedTags([...(agent.proposed_tags || [])]); + } + }, [agent]); + + const toggleTag = (tag: string) => { + setSelectedTags((prev) => + prev.includes(tag) ? prev.filter((t) => t !== tag) : [...prev, tag] + ); + }; + + const handleApprove = async () => { + if (!agent || selectedTags.length === 0) return; + try { + setLoading(true); + await onApprove(agent.agent_id, selectedTags); + onOpenChange(false); + } finally { + setLoading(false); + } + }; + + return ( + + + + Approve Tags + + Approve tags for agent{" "} + {agent?.agent_id} + + +
+
+ +
+ {(agent?.proposed_tags || []).map((tag) => { + const isSelected = selectedTags.includes(tag); + return ( + + ); + })} +
+ {selectedTags.length === 0 && ( +

+ Select at least one tag to approve. +

+ )} +
+ +
+ + +
+
+ + + + + + + ); +} diff --git a/control-plane/web/client/src/components/authorization/PolicyContextPanel.tsx b/control-plane/web/client/src/components/authorization/PolicyContextPanel.tsx new file mode 100644 index 00000000..d510a05e --- /dev/null +++ b/control-plane/web/client/src/components/authorization/PolicyContextPanel.tsx @@ -0,0 +1,109 @@ +import { useMemo } from "react"; +import { Badge } from "@/components/ui/badge"; +import { cn } from "@/lib/utils"; +import { statusTone } from "../../lib/theme"; +import type { AccessPolicy } from "../../services/accessPoliciesApi"; + +interface PolicyContextPanelProps { + tags: string[]; + policies: AccessPolicy[]; +} + +export function PolicyContextPanel({ tags, policies }: PolicyContextPanelProps) { + const { asCaller, asTarget } = useMemo(() => { + if (tags.length === 0) return { asCaller: [], asTarget: [] }; + + const tagSet = new Set(tags); + + const asCaller = policies.filter((p) => + p.caller_tags.some((t) => tagSet.has(t)) + ); + const asTarget = policies.filter((p) => + p.target_tags.some((t) => tagSet.has(t)) + ); + + return { asCaller, asTarget }; + }, [tags, policies]); + + if (tags.length === 0) { + return ( +

+ Select at least one tag to see policy impact. +

+ ); + } + + if (asCaller.length === 0 && asTarget.length === 0) { + return ( +

+ No existing policies reference these tags. +

+ ); + } + + return ( +
+ {asCaller.length > 0 && ( +
+

+ As Caller +

+
+ {asCaller.map((p) => ( + + ))} +
+
+ )} + {asTarget.length > 0 && ( +
+

+ As Target +

+
+ {asTarget.map((p) => ( + + ))} +
+
+ )} +
+ ); +} + +function PolicyRow({ policy }: { policy: AccessPolicy }) { + const functions = [ + ...(policy.allow_functions || []).map((f) => `${f}`), + ...(policy.deny_functions || []).map((f) => `!${f}`), + ]; + + return ( +
+ + {policy.action} + +
+ {policy.name} + + {" "} + {policy.caller_tags.join(", ")} → {policy.target_tags.join(", ")} + + {functions.length > 0 && ( +
+ Functions: {functions.join(", ")} +
+ )} +
+
+ ); +} diff --git a/control-plane/web/client/src/components/authorization/PolicyFormDialog.tsx b/control-plane/web/client/src/components/authorization/PolicyFormDialog.tsx new file mode 100644 index 00000000..b7ea9d16 --- /dev/null +++ b/control-plane/web/client/src/components/authorization/PolicyFormDialog.tsx @@ -0,0 +1,256 @@ +import { useState, useEffect } from "react"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { + SegmentedControl, + type SegmentedControlOption, +} from "@/components/ui/segmented-control"; +import { ChipInput } from "@/components/ui/chip-input"; +import { CheckCircle, XCircle, CaretRight } from "@/components/ui/icon-bridge"; +import { cn } from "@/lib/utils"; +import type { + AccessPolicy, + AccessPolicyRequest, +} from "../../services/accessPoliciesApi"; +import { listKnownTags } from "../../services/accessPoliciesApi"; + +const emptyPolicy: AccessPolicyRequest = { + name: "", + caller_tags: [], + target_tags: [], + allow_functions: [], + deny_functions: [], + action: "allow", + priority: 0, + description: "", +}; + +const actionOptions: ReadonlyArray = [ + { + value: "allow", + label: "Allow", + icon: ({ className }: { className?: string }) => ( + + ), + }, + { + value: "deny", + label: "Deny", + icon: ({ className }: { className?: string }) => ( + + ), + }, +] as const; + +interface PolicyFormDialogProps { + open: boolean; + onOpenChange: (open: boolean) => void; + editPolicy?: AccessPolicy | null; + onSave: (req: AccessPolicyRequest, editId?: number) => Promise; +} + +export function PolicyFormDialog({ + open, + onOpenChange, + editPolicy, + onSave, +}: PolicyFormDialogProps) { + const [form, setForm] = useState({ ...emptyPolicy }); + const [saving, setSaving] = useState(false); + const [suggestions, setSuggestions] = useState([]); + + // Fetch known tags when dialog opens + useEffect(() => { + if (open) { + listKnownTags() + .then((data) => setSuggestions(data.tags)) + .catch(() => {}); + } + }, [open]); + + // Populate form when editing + useEffect(() => { + if (editPolicy) { + setForm({ + name: editPolicy.name, + caller_tags: [...editPolicy.caller_tags], + target_tags: [...editPolicy.target_tags], + allow_functions: [...(editPolicy.allow_functions || [])], + deny_functions: [...(editPolicy.deny_functions || [])], + action: editPolicy.action, + priority: editPolicy.priority, + description: editPolicy.description || "", + }); + } else { + setForm({ ...emptyPolicy }); + } + }, [editPolicy, open]); + + const handleSave = async () => { + try { + setSaving(true); + await onSave(form, editPolicy?.id); + onOpenChange(false); + } finally { + setSaving(false); + } + }; + + const functionsLabel = + form.action === "allow" ? "Allowed Functions" : "Denied Functions"; + const functionsValue = + form.action === "allow" + ? form.allow_functions || [] + : form.deny_functions || []; + const onFunctionsChange = (fns: string[]) => { + if (form.action === "allow") { + setForm({ ...form, allow_functions: fns, deny_functions: [] }); + } else { + setForm({ ...form, deny_functions: fns, allow_functions: [] }); + } + }; + + return ( + + + + + {editPolicy ? "Edit Policy" : "Create Policy"} + + + Define a tag-based access policy for cross-agent calls. + + + +
+ {/* Action segmented control */} +
+ + + setForm({ ...form, action: v as "allow" | "deny" }) + } + options={actionOptions} + className="w-full" + /> +
+ + {/* Name */} +
+ + setForm({ ...form, name: e.target.value })} + placeholder="e.g. analytics-read-financial" + /> +
+ + {/* Description */} +
+ + + setForm({ ...form, description: e.target.value }) + } + placeholder="Optional description" + /> +
+ + {/* Two-column: Tags (left) + Functions/Priority (right) */} +
+ {/* Left column: Caller → Target tags */} +
+
+ + + setForm({ ...form, caller_tags: tags }) + } + suggestions={suggestions} + placeholder="e.g. analytics" + /> +
+ +
+ +
+ +
+ + + setForm({ ...form, target_tags: tags }) + } + suggestions={suggestions} + placeholder="e.g. financial" + /> +
+
+ + {/* Right column: Functions + Priority */} +
+
+ + +

+ Supports wildcards (*). Leave empty for all functions. +

+
+ +
+ + + setForm({ + ...form, + priority: parseInt(e.target.value) || 0, + }) + } + placeholder="0" + /> +

+ Higher priority policies are evaluated first. +

+
+
+
+
+ + + + + + + + ); +} diff --git a/control-plane/web/client/src/components/authorization/RevokeDialog.tsx b/control-plane/web/client/src/components/authorization/RevokeDialog.tsx new file mode 100644 index 00000000..59b96bf2 --- /dev/null +++ b/control-plane/web/client/src/components/authorization/RevokeDialog.tsx @@ -0,0 +1,92 @@ +import { useState } from "react"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { Badge } from "@/components/ui/badge"; +import type { AgentTagSummary } from "../../services/tagApprovalApi"; + +interface RevokeDialogProps { + agent: AgentTagSummary | null; + onRevoke: (agentId: string, reason?: string) => Promise; + onOpenChange: (open: boolean) => void; +} + +export function RevokeDialog({ agent, onRevoke, onOpenChange }: RevokeDialogProps) { + const [reason, setReason] = useState(""); + const [loading, setLoading] = useState(false); + + const handleRevoke = async () => { + if (!agent) return; + try { + setLoading(true); + await onRevoke(agent.agent_id, reason || undefined); + onOpenChange(false); + setReason(""); + } finally { + setLoading(false); + } + }; + + return ( + + + + Revoke Tags + + Revoke approved tags for agent{" "} + {agent?.agent_id}. + This will set the agent's status to pending. + + +
+ {agent && (agent.approved_tags?.length ?? 0) > 0 && ( +
+ +
+ {(agent.approved_tags || []).map((tag) => ( + + {tag} + + ))} +
+
+ )} +
+ + setReason(e.target.value)} + className="mt-1.5" + /> +
+

+ This will revoke the agent's tag VC and set its status to pending. +

+
+ + + + + + + ); +} diff --git a/control-plane/web/client/src/components/ui/CompactTable.tsx b/control-plane/web/client/src/components/ui/CompactTable.tsx index 0d516e32..3ff53d92 100644 --- a/control-plane/web/client/src/components/ui/CompactTable.tsx +++ b/control-plane/web/client/src/components/ui/CompactTable.tsx @@ -20,7 +20,7 @@ import { } from "./empty"; import { Button } from "./button"; -const ROW_HEIGHT = 32; // Using foundation's compact row height +const DEFAULT_ROW_HEIGHT = 32; // Using foundation's compact row height const CHEVRON_COLUMN_WIDTH = "28px"; interface SortableHeaderCellProps { @@ -145,13 +145,14 @@ interface CompactTableProps { }; className?: string; getRowKey: (item: T) => string; + rowHeight?: number; } -function LoadingRow({ gridTemplate }: { gridTemplate: string }) { +function LoadingRow({ gridTemplate, rowHeight }: { gridTemplate: string; rowHeight: number }) { return (
({ }, className, getRowKey, + rowHeight: rowHeightProp, }: CompactTableProps) { + const ROW_HEIGHT = rowHeightProp ?? DEFAULT_ROW_HEIGHT; const [hoveredRow, setHoveredRow] = useState(null); const parentRef = useRef(null); @@ -386,6 +389,7 @@ export function CompactTable({ ); } diff --git a/control-plane/web/client/src/components/ui/badge.tsx b/control-plane/web/client/src/components/ui/badge.tsx index 1f867f47..a77ad6b8 100644 --- a/control-plane/web/client/src/components/ui/badge.tsx +++ b/control-plane/web/client/src/components/ui/badge.tsx @@ -37,6 +37,10 @@ const badgeVariants = cva( pill: "rounded-full bg-muted/30 text-text-primary border border-border/40 px-2.5 py-0.5 text-[11px]", + // Tooltip variant – glass-style chip optimized for dark tooltip backgrounds + tooltip: + "bg-white/15 text-primary-foreground border border-white/20 rounded-md", + // Status variants with standardized colors and icons success: cn(getStatusBadgeClasses("success" satisfies StatusTone), "font-mono tracking-tight"), diff --git a/control-plane/web/client/src/components/ui/chip-input.tsx b/control-plane/web/client/src/components/ui/chip-input.tsx new file mode 100644 index 00000000..c4134f82 --- /dev/null +++ b/control-plane/web/client/src/components/ui/chip-input.tsx @@ -0,0 +1,172 @@ +import { useState, useRef, useEffect, useCallback } from "react"; +import { X } from "@/components/ui/icon-bridge"; +import { Badge } from "./badge"; +import { cn } from "@/lib/utils"; + +interface ChipInputProps { + value: string[]; + onChange: (tags: string[]) => void; + suggestions?: string[]; + placeholder?: string; + className?: string; +} + +export function ChipInput({ + value, + onChange, + suggestions = [], + placeholder = "Type and press Enter...", + className, +}: ChipInputProps) { + const [inputValue, setInputValue] = useState(""); + const [showDropdown, setShowDropdown] = useState(false); + const [highlightIndex, setHighlightIndex] = useState(-1); + const inputRef = useRef(null); + const containerRef = useRef(null); + + // Filter suggestions: exclude already-selected tags and match typed text + const filtered = suggestions.filter( + (s) => + !value.includes(s) && + (inputValue === "" || s.toLowerCase().includes(inputValue.toLowerCase())) + ); + + const addChip = useCallback( + (tag: string) => { + const trimmed = tag.trim(); + if (trimmed && !value.includes(trimmed)) { + onChange([...value, trimmed]); + } + setInputValue(""); + setHighlightIndex(-1); + }, + [value, onChange] + ); + + const removeChip = useCallback( + (tag: string) => { + onChange(value.filter((t) => t !== tag)); + }, + [value, onChange] + ); + + // Close dropdown on outside click + useEffect(() => { + function handleClickOutside(e: MouseEvent) { + if ( + containerRef.current && + !containerRef.current.contains(e.target as Node) + ) { + setShowDropdown(false); + setHighlightIndex(-1); + } + } + document.addEventListener("mousedown", handleClickOutside); + return () => document.removeEventListener("mousedown", handleClickOutside); + }, []); + + const handleKeyDown = (e: React.KeyboardEvent) => { + if (e.key === "Enter" || e.key === ",") { + e.preventDefault(); + if (highlightIndex >= 0 && highlightIndex < filtered.length) { + addChip(filtered[highlightIndex]); + } else if (inputValue.trim()) { + addChip(inputValue); + } + } else if ( + e.key === "Backspace" && + inputValue === "" && + value.length > 0 + ) { + removeChip(value[value.length - 1]); + } else if (e.key === "ArrowDown") { + e.preventDefault(); + setHighlightIndex((prev) => + prev < filtered.length - 1 ? prev + 1 : prev + ); + } else if (e.key === "ArrowUp") { + e.preventDefault(); + setHighlightIndex((prev) => (prev > 0 ? prev - 1 : -1)); + } else if (e.key === "Escape") { + setShowDropdown(false); + setHighlightIndex(-1); + } + }; + + const handleInputChange = (e: React.ChangeEvent) => { + setInputValue(e.target.value); + setHighlightIndex(-1); + if (!showDropdown) { + setShowDropdown(true); + } + }; + + const shouldShowDropdown = showDropdown && filtered.length > 0; + + return ( +
+
inputRef.current?.focus()} + > + {value.map((tag) => ( + + {tag} + + + ))} + setShowDropdown(true)} + placeholder={value.length === 0 ? placeholder : ""} + className="flex-1 min-w-[80px] bg-transparent outline-none text-sm placeholder:text-muted-foreground" + /> +
+ + {shouldShowDropdown && ( +
+ {filtered.map((suggestion, idx) => ( + + ))} +
+ )} +
+ ); +} diff --git a/control-plane/web/client/src/components/ui/icon-bridge.tsx b/control-plane/web/client/src/components/ui/icon-bridge.tsx index 32c573c9..b9089c66 100644 --- a/control-plane/web/client/src/components/ui/icon-bridge.tsx +++ b/control-plane/web/client/src/components/ui/icon-bridge.tsx @@ -5,6 +5,7 @@ import { ArrowCounterClockwiseIcon } from "@phosphor-icons/react/dist/csr/ArrowC import { ArrowLeftIcon } from "@phosphor-icons/react/dist/csr/ArrowLeft"; import { ArrowDownIcon } from "@phosphor-icons/react/dist/csr/ArrowDown"; import { ArrowUpIcon } from "@phosphor-icons/react/dist/csr/ArrowUp"; +import { ArrowRightIcon } from "@phosphor-icons/react/dist/csr/ArrowRight"; import { ArrowUpRightIcon } from "@phosphor-icons/react/dist/csr/ArrowUpRight"; import { ArrowsDownUpIcon } from "@phosphor-icons/react/dist/csr/ArrowsDownUp"; import { ArrowsOutSimpleIcon } from "@phosphor-icons/react/dist/csr/ArrowsOutSimple"; @@ -133,6 +134,7 @@ export const ArrowLeft = ArrowLeftIcon; export const ArrowDown = ArrowDownIcon; export const ArrowUp = ArrowUpIcon; export const ArrowUpDown = ArrowsDownUpIcon; +export const ArrowRight = ArrowRightIcon; export const ArrowUpRight = ArrowUpRightIcon; export const ArrowCounterClockwise = ArrowCounterClockwiseIcon; export const ArrowSquareOut = ArrowSquareOutIcon; diff --git a/control-plane/web/client/src/components/ui/icon.tsx b/control-plane/web/client/src/components/ui/icon.tsx index c8243a47..bcea99dc 100644 --- a/control-plane/web/client/src/components/ui/icon.tsx +++ b/control-plane/web/client/src/components/ui/icon.tsx @@ -14,10 +14,13 @@ import { Moon, Monitor, ShieldCheck, + Shield, Identification, FileText, GithubLogo, Question, + Clock, + RecentlyViewed, } from "@/components/ui/icon-bridge"; import type { IconComponent, IconWeight } from "@/components/ui/icon-bridge"; @@ -36,10 +39,14 @@ const icons = { moon: Moon, monitor: Monitor, "shield-check": ShieldCheck, + shield: Shield, identification: Identification, documentation: FileText, github: GithubLogo, support: Question, + hourglass: Clock, + history: RecentlyViewed, + lock: Shield, } as const; export interface IconProps { diff --git a/control-plane/web/client/src/components/ui/tooltip-tag-list.tsx b/control-plane/web/client/src/components/ui/tooltip-tag-list.tsx new file mode 100644 index 00000000..0ef4f5a7 --- /dev/null +++ b/control-plane/web/client/src/components/ui/tooltip-tag-list.tsx @@ -0,0 +1,51 @@ +import { Badge } from "./badge"; + +/** + * A tag group rendered inside a tooltip. + * - `label` (optional) renders an uppercase section header (e.g. "From", "Granted"). + * - `tags` is the list of tag strings to render as glass-style chips. + * An empty array renders a muted "any" placeholder. + */ +export interface TooltipTagGroup { + label?: string; + tags: string[]; +} + +export interface TooltipTagListProps { + groups: TooltipTagGroup[]; +} + +/** + * Renders one or more groups of tags as styled chips inside a tooltip. + * + * Uses the `tooltip` badge variant (semi-transparent glass on dark bg). + * Place inside `` for consistent styling across the app. + */ +export function TooltipTagList({ groups }: TooltipTagListProps) { + return ( +
+ {groups.map((group, i) => ( +
+ {group.label && ( +
+ {group.label} +
+ )} +
+ {group.tags.length > 0 ? ( + group.tags.map((tag) => ( + + {tag} + + )) + ) : ( + + any + + )} +
+
+ ))} +
+ ); +} diff --git a/control-plane/web/client/src/config/navigation.ts b/control-plane/web/client/src/config/navigation.ts index 2efdb35d..303bef4b 100644 --- a/control-plane/web/client/src/config/navigation.ts +++ b/control-plane/web/client/src/config/navigation.ts @@ -74,6 +74,19 @@ export const navigationSections: NavigationSection[] = [ } ] }, + { + id: 'authorization', + title: 'Authorization', + items: [ + { + id: 'authorization', + label: 'Authorization', + href: '/authorization', + icon: 'shield-check', + description: 'Manage access policies and agent tag approvals' + } + ] + }, { id: 'settings', title: 'Settings', diff --git a/control-plane/web/client/src/contexts/AuthContext.tsx b/control-plane/web/client/src/contexts/AuthContext.tsx index 07a3fc90..b2ae6247 100644 --- a/control-plane/web/client/src/contexts/AuthContext.tsx +++ b/control-plane/web/client/src/contexts/AuthContext.tsx @@ -1,10 +1,12 @@ import { createContext, useContext, useEffect, useState } from "react"; import type { ReactNode } from "react"; -import { setGlobalApiKey } from "../services/api"; +import { setGlobalApiKey, setGlobalAdminToken } from "../services/api"; interface AuthContextType { apiKey: string | null; setApiKey: (key: string | null) => void; + adminToken: string | null; + setAdminToken: (token: string | null) => void; isAuthenticated: boolean; authRequired: boolean; clearAuth: () => void; @@ -12,6 +14,7 @@ interface AuthContextType { const AuthContext = createContext(undefined); const STORAGE_KEY = "af_api_key"; +const ADMIN_TOKEN_STORAGE_KEY = "af_admin_token"; // Simple obfuscation for localStorage; not meant as real security. const encryptKey = (key: string): string => btoa(key.split("").reverse().join("")); @@ -44,6 +47,19 @@ const initStoredKey = (() => { export function AuthProvider({ children }: { children: ReactNode }) { // Initialize with pre-loaded key so it's available immediately const [apiKey, setApiKeyState] = useState(initStoredKey); + const [adminToken, setAdminTokenState] = useState(() => { + try { + const stored = localStorage.getItem(ADMIN_TOKEN_STORAGE_KEY); + if (stored) { + const token = decryptKey(stored); + if (token) { + setGlobalAdminToken(token); + return token; + } + } + } catch { /* localStorage might not be available */ } + return null; + }); const [authRequired, setAuthRequired] = useState(false); const [loading, setLoading] = useState(true); @@ -106,10 +122,23 @@ export function AuthProvider({ children }: { children: ReactNode }) { } }; + const setAdminToken = (token: string | null) => { + setAdminTokenState(token); + setGlobalAdminToken(token); + if (token) { + localStorage.setItem(ADMIN_TOKEN_STORAGE_KEY, encryptKey(token)); + } else { + localStorage.removeItem(ADMIN_TOKEN_STORAGE_KEY); + } + }; + const clearAuth = () => { setApiKeyState(null); setGlobalApiKey(null); localStorage.removeItem(STORAGE_KEY); + setAdminTokenState(null); + setGlobalAdminToken(null); + localStorage.removeItem(ADMIN_TOKEN_STORAGE_KEY); }; if (loading) { @@ -121,6 +150,8 @@ export function AuthProvider({ children }: { children: ReactNode }) { value={{ apiKey, setApiKey, + adminToken, + setAdminToken, isAuthenticated: !authRequired || !!apiKey, authRequired, clearAuth, diff --git a/control-plane/web/client/src/pages/AuthorizationPage.tsx b/control-plane/web/client/src/pages/AuthorizationPage.tsx new file mode 100644 index 00000000..ed51855a --- /dev/null +++ b/control-plane/web/client/src/pages/AuthorizationPage.tsx @@ -0,0 +1,110 @@ +import { useCallback, useEffect, useState } from "react"; +import { Badge } from "@/components/ui/badge"; +import { Renew } from "@/components/ui/icon-bridge"; +import { + AnimatedTabs, + AnimatedTabsContent, + AnimatedTabsList, + AnimatedTabsTrigger, +} from "@/components/ui/animated-tabs"; +import { PageHeader } from "../components/PageHeader"; +import { NotificationProvider } from "@/components/ui/notification"; +import { AdminTokenPrompt } from "../components/AdminTokenPrompt"; +import { AccessRulesTab } from "../components/authorization/AccessRulesTab"; +import { AgentTagsTab } from "../components/authorization/AgentTagsTab"; +import * as policiesApi from "../services/accessPoliciesApi"; +import type { AccessPolicy } from "../services/accessPoliciesApi"; + +function AuthorizationPageContent() { + const [policies, setPolicies] = useState([]); + const [policiesLoading, setPoliciesLoading] = useState(true); + const [pendingCount, setPendingCount] = useState(0); + + const fetchPolicies = useCallback(async () => { + try { + setPoliciesLoading(true); + const data = await policiesApi.listPolicies(); + setPolicies(data.policies || []); + } catch { + // Errors handled per-tab + } finally { + setPoliciesLoading(false); + } + }, []); + + useEffect(() => { + fetchPolicies(); + }, [fetchPolicies]); + + const handleRefreshAll = () => { + fetchPolicies(); + }; + + return ( +
+ {/* Header */} + + ), + }, + ]} + /> + + {/* Admin token prompt — shared above tabs */} + + + {/* Tabs */} + + + + Access Rules + + + Agent Tags + {pendingCount > 0 && ( + + {pendingCount} + + )} + + + + + + + + + + + +
+ ); +} + +export function AuthorizationPage() { + return ( + + + + ); +} diff --git a/control-plane/web/client/src/services/accessPoliciesApi.ts b/control-plane/web/client/src/services/accessPoliciesApi.ts new file mode 100644 index 00000000..f49ea2bb --- /dev/null +++ b/control-plane/web/client/src/services/accessPoliciesApi.ts @@ -0,0 +1,107 @@ +/** + * Access Policies API + * API client for tag-based access policy admin endpoints + */ + +import { getGlobalApiKey, getGlobalAdminToken } from './api'; + +const API_BASE = '/api/v1'; + +export interface AccessConstraint { + operator: string; // "<=", ">=", "==", "!=", "<", ">" + value: string | number; +} + +export interface AccessPolicy { + id: number; + name: string; + caller_tags: string[]; + target_tags: string[]; + allow_functions: string[]; + deny_functions: string[]; + constraints?: Record; + action: 'allow' | 'deny'; + priority: number; + enabled: boolean; + description?: string; + created_at: string; + updated_at: string; +} + +export interface AccessPolicyRequest { + name: string; + caller_tags: string[]; + target_tags: string[]; + allow_functions?: string[]; + deny_functions?: string[]; + constraints?: Record; + action: 'allow' | 'deny'; + priority?: number; + description?: string; +} + +async function fetchWithAuth(url: string, options: RequestInit = {}): Promise { + const apiKey = getGlobalApiKey(); + const headers: HeadersInit = { + 'Content-Type': 'application/json', + ...options.headers, + }; + + if (apiKey) { + (headers as Record)['X-Api-Key'] = apiKey; + } + + const adminToken = getGlobalAdminToken(); + if (adminToken) { + (headers as Record)['X-Admin-Token'] = adminToken; + } + + const response = await fetch(url, { + ...options, + headers, + }); + + if (!response.ok) { + const errorData = await response.json().catch(() => ({})); + throw new Error(errorData.message || `Request failed with status ${response.status}`); + } + + return response; +} + +export async function listPolicies(): Promise<{ policies: AccessPolicy[]; total: number }> { + const response = await fetchWithAuth(`${API_BASE}/admin/policies`); + return response.json(); +} + +export async function getPolicy(id: number): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/policies/${id}`); + return response.json(); +} + +export async function createPolicy(req: AccessPolicyRequest): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/policies`, { + method: 'POST', + body: JSON.stringify(req), + }); + return response.json(); +} + +export async function updatePolicy(id: number, req: AccessPolicyRequest): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/policies/${id}`, { + method: 'PUT', + body: JSON.stringify(req), + }); + return response.json(); +} + +export async function deletePolicy(id: number): Promise { + await fetchWithAuth(`${API_BASE}/admin/policies/${id}`, { + method: 'DELETE', + }); +} + +export async function listKnownTags(): Promise<{ tags: string[]; total: number }> { + const response = await fetchWithAuth(`${API_BASE}/admin/tags`); + return response.json(); +} diff --git a/control-plane/web/client/src/services/api.ts b/control-plane/web/client/src/services/api.ts index 99660d27..ff118e47 100644 --- a/control-plane/web/client/src/services/api.ts +++ b/control-plane/web/client/src/services/api.ts @@ -56,6 +56,31 @@ export function getGlobalApiKey(): string | null { return globalApiKey; } +// Admin token for accessing admin-only permission management routes. +// Stored separately from the API key since it provides elevated privileges. +const ADMIN_TOKEN_STORAGE_KEY = "af_admin_token"; + +let globalAdminToken: string | null = (() => { + try { + const stored = localStorage.getItem(ADMIN_TOKEN_STORAGE_KEY); + if (stored) { + const key = decryptKey(stored); + if (key) return key; + } + } catch { + // localStorage might not be available + } + return null; +})(); + +export function setGlobalAdminToken(token: string | null) { + globalAdminToken = token; +} + +export function getGlobalAdminToken(): string | null { + return globalAdminToken; +} + /** * Enhanced fetch wrapper with MCP-specific error handling, retry logic, and timeout support */ diff --git a/control-plane/web/client/src/services/tagApprovalApi.ts b/control-plane/web/client/src/services/tagApprovalApi.ts new file mode 100644 index 00000000..893562f2 --- /dev/null +++ b/control-plane/web/client/src/services/tagApprovalApi.ts @@ -0,0 +1,101 @@ +/** + * Tag Approval API + * API client for tag approval admin endpoints + */ + +import { getGlobalApiKey, getGlobalAdminToken } from './api'; + +const API_BASE = '/api/v1'; + +export interface PendingAgentResponse { + agent_id: string; + proposed_tags: string[]; + approved_tags?: string[]; + status: string; + registered_at: string; +} + +export interface TagApprovalRequest { + approved_tags: string[]; + skill_tags?: Record; + reasoner_tags?: Record; + reason?: string; +} + +export interface TagRejectionRequest { + reason?: string; +} + +async function fetchWithAuth(url: string, options: RequestInit = {}): Promise { + const apiKey = getGlobalApiKey(); + const headers: HeadersInit = { + 'Content-Type': 'application/json', + ...options.headers, + }; + + if (apiKey) { + (headers as Record)['X-Api-Key'] = apiKey; + } + + const adminToken = getGlobalAdminToken(); + if (adminToken) { + (headers as Record)['X-Admin-Token'] = adminToken; + } + + const response = await fetch(url, { + ...options, + headers, + }); + + if (!response.ok) { + const errorData = await response.json().catch(() => ({})); + throw new Error(errorData.message || `Request failed with status ${response.status}`); + } + + return response; +} + +export async function listPendingAgents(): Promise<{ agents: PendingAgentResponse[]; total: number }> { + const response = await fetchWithAuth(`${API_BASE}/admin/agents/pending`); + return response.json(); +} + +export async function approveAgentTags(agentId: string, req: TagApprovalRequest): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/agents/${encodeURIComponent(agentId)}/approve-tags`, { + method: 'POST', + body: JSON.stringify(req), + }); + return response.json(); +} + +export async function rejectAgentTags(agentId: string, req: TagRejectionRequest): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/agents/${encodeURIComponent(agentId)}/reject-tags`, { + method: 'POST', + body: JSON.stringify(req), + }); + return response.json(); +} + +// Agent tag summary from the UI-optimized endpoint +export interface AgentTagSummary { + agent_id: string; + proposed_tags: string[]; + approved_tags: string[]; + lifecycle_status: string; + registered_at: string; +} + +// List ALL agents with tag data (uses UI-optimized endpoint) +export async function listAllAgentsWithTags(): Promise<{ agents: AgentTagSummary[]; total: number }> { + const response = await fetchWithAuth('/api/ui/v1/authorization/agents'); + return response.json(); +} + +// Revoke agent tags +export async function revokeAgentTags(agentId: string, reason?: string): Promise { + const response = await fetchWithAuth(`${API_BASE}/admin/agents/${encodeURIComponent(agentId)}/revoke-tags`, { + method: 'POST', + body: JSON.stringify({ reason }), + }); + return response.json(); +} diff --git a/control-plane/web/client/src/types/did.ts b/control-plane/web/client/src/types/did.ts index 0881538c..b7e2c062 100644 --- a/control-plane/web/client/src/types/did.ts +++ b/control-plane/web/client/src/types/did.ts @@ -81,7 +81,7 @@ export interface DIDIdentityPackage { export interface DIDIdentity { did: string; - private_key_jwk: string; + private_key_jwk?: string; public_key_jwk: string; derivation_path: string; component_type: string; diff --git a/control-plane/web/client/tsconfig.app.json b/control-plane/web/client/tsconfig.app.json index 8c07f135..f2649e88 100644 --- a/control-plane/web/client/tsconfig.app.json +++ b/control-plane/web/client/tsconfig.app.json @@ -22,7 +22,6 @@ "erasableSyntaxOnly": true, "noFallthroughCasesInSwitch": true, "noUncheckedSideEffectImports": true, - "baseUrl": ".", "paths": { "@/*": [ "./src/*" diff --git a/control-plane/web/client/tsconfig.json b/control-plane/web/client/tsconfig.json index fec8c8e5..c36d52af 100644 --- a/control-plane/web/client/tsconfig.json +++ b/control-plane/web/client/tsconfig.json @@ -5,7 +5,6 @@ { "path": "./tsconfig.node.json" } ], "compilerOptions": { - "baseUrl": ".", "paths": { "@/*": ["./src/*"] } diff --git a/docs/VC_AUTHORIZATION_ARCHITECTURE.md b/docs/VC_AUTHORIZATION_ARCHITECTURE.md new file mode 100644 index 00000000..09595564 --- /dev/null +++ b/docs/VC_AUTHORIZATION_ARCHITECTURE.md @@ -0,0 +1,1126 @@ +# VC-Based Authorization Architecture + +**Version:** 2.0 +**Status:** Implemented +**Date:** February 2026 + +--- + +## Executive Summary + +This document describes the Verifiable Credential (VC) based authorization system for AgentField. The system implements a two-step authorization model: **tag approval** (admin decides which tags agents get) and **policy evaluation** (policies decide which tagged agents can call which other tagged agents). + +**Key Principles:** +- Agents propose tags at registration (agent-level and per-skill/per-reasoner) +- Control plane evaluates proposed tags against configurable approval rules (`auto`/`manual`/`forbidden`) +- Default mode is `auto` (all tags auto-approved) for zero-disruption backward compatibility +- Tags requiring `manual` approval put agents into `pending_approval` state until admin reviews +- `forbidden` tags reject registration outright (HTTP 403) +- Tag-based access policies control which agents can call which functions with parameter constraints +- Upon tag approval, control plane issues a signed `AgentTagVC` (W3C Verifiable Credential) per agent +- Permission middleware evaluates tag-based access policies; no policy match allows the request (backward compatible) +- `did:web` enables real-time revocation via control plane-hosted DID documents +- SDKs support decentralized verification: agents cache policies, revocation lists, and admin public keys locally +- Control plane is source of truth; agents can verify locally without hitting control plane on every call + +--- + +## System Overview + +### Flow 1: Registration with Tag Approval + +When an agent registers, it proposes tags at both the agent level and per-skill/per-reasoner level. The control plane evaluates each proposed tag against configured approval rules. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ REGISTRATION WITH TAG APPROVAL │ +└─────────────────────────────────────────────────────────────────────────────┘ + + AGENT CONTROL PLANE ADMIN + │ │ │ + │ 1. Register │ │ + │ ─────────────────────────► │ │ + │ { │ │ + │ id: "finance-bot", │ │ + │ skills: [{ │ │ + │ id: "charge", │ │ + │ proposed_tags: │ │ + │ ["finance","payment"] │ │ + │ }], │ │ + │ reasoners: [{ │ │ + │ id: "analyze", │ │ + │ proposed_tags: ["nlp"] │ │ + │ }] │ │ + │ } │ │ + │ │ │ + │ │ 2. Evaluate tag approval rules: │ + │ │ "finance" → manual ⏸ │ + │ │ "payment" → manual ⏸ │ + │ │ "nlp" → auto ✓ │ + │ │ │ + │ │ 3. Set status: pending_approval │ + │ │ Auto-approve "nlp" │ + │ │ │ + │ 4. Response │ │ + │ ◄───────────────────────── │ │ + │ { │ │ + │ status: pending_approval, │ │ + │ pending_tags: [finance, │ │ + │ payment], │ │ + │ auto_approved: [nlp] │ │ + │ } │ │ + │ │ │ + │ │ 5. Show in Admin UI │ + │ │ ─────────────────────────────► │ + │ │ │ + │ │ 6. Approve/Modify/Reject│ + │ │ ◄───────────────────────────── │ + │ │ │ + │ │ 7. Issue AgentTagVC │ + │ │ Set status: starting │ + │ │ │ + │ 8. Agent activates │ │ + │ ◄───────────────────────── │ │ +``` + +### Flow 2: Runtime Permission Check (Policy Engine) + +When an agent calls another agent, the permission middleware evaluates tag-based access policies to decide whether to allow or deny the request. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ RUNTIME PERMISSION CHECK (POLICY ENGINE) │ +└─────────────────────────────────────────────────────────────────────────────┘ + + AGENT A CONTROL PLANE AGENT B + (caller) (permission middleware) (target) + │ │ │ + │ 1. POST /execute/B.func │ │ + │ Headers: │ │ + │ X-Caller-DID │ │ + │ X-DID-Signature │ │ + │ X-DID-Timestamp │ │ + │ ─────────────────────────► │ │ + │ │ │ + │ │ 2. DID Auth Middleware: │ + │ │ Verify Ed25519 signature │ + │ │ Check replay protection │ + │ │ Check timestamp window │ + │ │ │ + │ │ 3. Is B in pending_approval? │ + │ │ YES → 503 Unavailable │ + │ │ │ + │ │ 4. Tag Policy Evaluation: │ + │ │ Load caller's AgentTagVC │ + │ │ Verify VC signature │ + │ │ Get caller tags from VC │ + │ │ Get target tags │ + │ │ Evaluate access policies: │ + │ │ caller_tags match? │ + │ │ target_tags match? │ + │ │ function allowed? │ + │ │ constraints satisfied? │ + │ │ │ + │ │ 5. If policy matched → decide │ + │ │ If no policy → allow │ + │ │ (backward compat) │ + │ │ │ + │ │ 6. ALLOW → forward to B │ + │ │ ───────────────────────────────►│ + │ │ │ + │ 7. Result │ │ + │ ◄───────────────────────── │ ◄──────────────────────────────│ +``` + +### Flow 3: Revocation + +Admin can revoke an agent's tags at any time. The agent returns to `pending_approval` and subsequent calls fail. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ REVOCATION │ +└─────────────────────────────────────────────────────────────────────────────┘ + + AGENT A CONTROL PLANE ADMIN + │ │ │ + │ │ 1. Revoke Agent B's tags │ + │ │ ◄───────────────────────────── │ + │ │ │ + │ │ 2. Clear approved_tags │ + │ │ Revoke AgentTagVC │ + │ │ Set status: pending_approval │ + │ │ │ + │ 3. Call Agent B │ │ + │ ─────────────────────────► │ │ + │ │ │ + │ │ 4. B is pending_approval → 503 │ + │ │ │ + │ 5. Error: Agent │ │ + │ unavailable │ │ + │ ◄───────────────────────── │ │ +``` + +### Flow 4: Decentralized Verification + +Agents cache policies, revocation lists, and admin public keys locally. Verification happens without hitting the control plane on every call. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DECENTRALIZED VERIFICATION │ +└─────────────────────────────────────────────────────────────────────────────┘ + + AGENT B CONTROL PLANE + (target, verifying locally) + │ │ + │ 1. On startup / every 5min │ + │ GET /api/v1/policies │ + │ ─────────────────────────► │ + │ ◄───────────────────────── │ (cache policies) + │ │ + │ GET /api/v1/revocations │ + │ ─────────────────────────► │ + │ ◄───────────────────────── │ (cache revoked DIDs) + │ │ + │ GET /api/v1/admin/public-key│ + │ ─────────────────────────► │ + │ ◄───────────────────────── │ (cache issuer public key) + │ │ + │ │ + AGENT A ──► AGENT B (direct call) + │ 2. Incoming request │ + │ from Agent A │ + │ │ + │ 3. Local verification: │ + │ - Check caller DID │ + │ not in revocation list │ + │ - Verify Ed25519 sig │ + │ using cached pub key │ + │ - Evaluate policies │ + │ using cached rules │ + │ - Check constraints │ + │ │ + │ 4. ALLOW/DENY locally │ + │ (no control plane call) │ +``` + +--- + +## Core Concepts + +### 1. Agent Identity (Tags) + +Agents propose tags at registration at both the agent level and per-skill/per-reasoner level. The control plane evaluates proposed tags against configurable approval rules. + +```python +# Python SDK — per-skill tags +app = Agent(node_id="finance-bot") + +@app.reasoner(tags=["pci-compliant", "finance"]) +async def process_payment(input_data): + ... + +@app.skill(tags=["finance", "reporting"]) +async def get_balance(customer_id: str): + ... +``` + +```go +// Go SDK — per-reasoner tags +agent.RegisterReasoner("payment", handler, + agent.WithReasonerTags("pci-compliant", "finance"), +) +``` + +```typescript +// TypeScript SDK — per-skill tags +agent.registerReasoner("payment", handler, { + tags: ["pci-compliant", "finance"], +}); +``` + +**Tag Data Model:** + +Each `ReasonerDefinition` and `SkillDefinition` has three tag fields: + +| Field | Purpose | +|-------|---------| +| `tags` | Original tags declared by developer (backward compatibility) | +| `proposed_tags` | Tags proposed for approval (copied from `tags` if not set) | +| `approved_tags` | Tags granted by admin or auto-approval | + +Agent-level `proposed_tags` is the union of all per-skill/per-reasoner proposed tags (computed by `CollectAllProposedTags()`). Agent-level `approved_tags` is the union of all per-skill/per-reasoner approved tags. + +**Tag Lifecycle:** + +| Stage | Field | Description | +|-------|-------|-------------| +| Registration | `proposed_tags` | Tags the developer wants (per skill/reasoner and agent level) | +| Evaluation | Tag approval rules | Control plane checks each tag against rules | +| Approved | `approved_tags` | Tags the admin (or auto-approval) grants | +| Runtime | `CanonicalAgentTags()` | Prefers `approved_tags`, falls back to `tags`; normalized, deduplicated | + +**Tag Normalization:** +- All tags lowercased and trimmed +- Empty strings filtered out +- Duplicates removed +- Case-insensitive comparison for rule matching +- Deployment metadata tags excluded from canonical tags + +**Tag Approval Modes:** + +| Mode | Behavior | +|------|----------| +| `auto` (default) | Tags auto-approved, agent proceeds immediately | +| `manual` | Agent enters `pending_approval` state, waits for admin review | +| `forbidden` | Registration rejected outright (HTTP 403) | + +Tags serve as: +- **Identity declaration** - "I am a finance agent" +- **Capability advertisement** - "I handle PCI-compliant operations" +- **Authorization scope** - Determines which access policies apply +- **Discovery metadata** - Other agents can find me by tags +- **Admin context** - Helps admin decide whether to approve + +### 2. Agent Lifecycle States + +```go +type AgentLifecycleStatus string + +const ( + AgentStatusStarting = "starting" // Initializing + AgentStatusReady = "ready" // Fully operational + AgentStatusDegraded = "degraded" // Partial functionality + AgentStatusOffline = "offline" // Not responding + AgentStatusPendingApproval = "pending_approval" // Awaiting tag approval +) +``` + +**State Transitions:** + +| Current Status | Event | New Status | +|----------------|-------|------------| +| (new) | Registration, all tags auto-approved | `starting` | +| (new) | Registration, some tags need manual review | `pending_approval` | +| (new) | Registration, any forbidden tag | Registration rejected (403) | +| `pending_approval` | Admin approves tags | `starting` | +| `pending_approval` | Admin rejects tags | `offline` | +| `starting` | Health check passes | `ready` | +| `ready` | Health check fails | `offline` | + +Agents in `pending_approval` state cannot be called — the permission middleware returns HTTP 503 Unavailable. + +### 3. Access Policies (Policy Engine) + +Access policies define tag-based authorization rules for cross-agent calls. They support function-level allow/deny lists and parameter constraints. + +```yaml +# agentfield.yaml +features: + did: + authorization: + access_policies: + - name: finance_to_billing + caller_tags: ["finance"] + target_tags: ["billing"] + allow_functions: ["charge_*", "refund_*", "get_*"] + deny_functions: ["delete_*", "admin_*"] + constraints: + amount: + operator: "<=" + value: 10000 + action: allow + priority: 10 + + - name: support_readonly + caller_tags: ["support"] + target_tags: ["customer-data"] + allow_functions: ["get_*", "query_*"] + action: allow + priority: 5 +``` + +**Policy Fields:** + +| Field | Description | +|-------|-------------| +| `name` | Unique policy name | +| `caller_tags` | Tags the calling agent must have (empty = any) | +| `target_tags` | Tags the target agent must have (empty = any) | +| `allow_functions` | Whitelist of callable functions (supports wildcards) | +| `deny_functions` | Blacklist of functions (checked first, overrides allow) | +| `constraints` | Parameter-level constraints (e.g., `amount <= 10000`) | +| `action` | `"allow"` or `"deny"` — the decision when all conditions match | +| `priority` | Higher priority policies evaluated first | +| `enabled` | Toggle without deletion | + +**Evaluation Algorithm (first-match-wins):** + +1. Policies sorted by `priority DESC, id ASC` (deterministic ordering) +2. For each enabled policy: + - Check caller tags match (empty policy tags = wildcard) + - Check target tags match + - Check deny functions — if matched, **immediately deny** + - Check allow functions — if list exists but function not in it, skip policy + - Evaluate constraints — missing parameters or violations cause deny (fail-closed) + - All checks pass → return `Allowed = (action == "allow")` +3. No matching policy → return `Matched: false` (request allowed for backward compatibility) + +**Constraint Operators:** `<=`, `>=`, `<`, `>`, `==`, `!=` +- Numeric comparison for numeric values +- String comparison (`==`/`!=`) as fallback +- Missing parameters in input → deny (fail-closed) + +**Policy Evaluation Result:** + +```go +type PolicyEvaluationResult struct { + Allowed bool // Whether access is granted + Matched bool // Whether any policy matched + PolicyName string // Which policy matched + PolicyID int64 + Reason string // Human-readable explanation +} +``` + +### 4. Verifiable Credentials (VCs) + +#### AgentTagVC (Per-Agent) + +Issued when admin approves an agent's tags. Certifies which tags an agent is authorized to hold. Signed with Ed25519 by the control plane issuer DID. + +```json +{ + "@context": ["https://www.w3.org/2018/credentials/v1"], + "type": ["VerifiableCredential", "AgentTagCredential"], + "id": "urn:agentfield:agent-tag-vc:550e8400-e29b-41d4-a716-446655440000", + "issuer": "did:web:localhost%3A8080:agents:control-plane", + "issuanceDate": "2026-02-08T10:30:00Z", + "credentialSubject": { + "id": "did:web:localhost%3A8080:agents:finance-bot", + "agent_id": "finance-bot", + "permissions": { + "tags": ["finance", "payment"], + "allowed_callees": ["*"] + }, + "approved_by": "admin", + "approved_at": "2026-02-08T10:30:00Z" + }, + "proof": { + "type": "Ed25519Signature2020", + "created": "2026-02-08T10:30:00Z", + "verificationMethod": "did:web:localhost%3A8080:agents:control-plane#key-1", + "proofPurpose": "assertionMethod", + "proofValue": "s6mNf...XkMg==" + } +} +``` + +**Key fields:** +- `credentialSubject.id` — Agent's DID (cryptographic identity) +- `credentialSubject.permissions.tags` — Approved tags (what the agent is authorized to claim) +- `credentialSubject.permissions.allowed_callees` — `["*"]` means policy engine decides +- `proof` — Ed25519 signature from control plane issuer; falls back to `UnsignedAuditRecord` if issuer DID unavailable + +**Verification at call time (`TagVCVerifier`):** +1. Load VC record from storage +2. Check revocation (`revoked_at` timestamp) +3. Check expiration (`expires_at` timestamp) +4. Parse VC document from JSON +5. Verify Ed25519 signature against issuer public key +6. Validate subject binding (VC agent ID matches requested agent) + +If VC verification succeeds, the permission middleware uses **VC-verified tags** (cryptographic proof). If VC exists but verification fails (revoked/expired/invalid), the middleware uses **empty tags** (fail-closed security — no fallback to unverified tags). + +> **Note:** The legacy `PermissionVC` (per caller-target pair) has been superseded by `AgentTagVC`. The tag-based model scales as O(n) agents + policy rules rather than O(n²) pair-wise approvals. + +### 5. DID Methods + +#### did:web (Primary) +- DID resolves to URL: `did:web:agentfield.example.com:agents:agent-a` +- Control plane hosts DID document at that URL +- **Real-time revocation** — return 404 or revoked status +- Verifiers fetch fresh public key on each verification +- Domain configurable via `features.did.authorization.domain` + +#### did:key (Supported) +- DID derived from public key: `did:key:z6MkpTHR8VNs...` +- Self-contained, no external resolution +- **Cannot be revoked** — only time-based expiry + +### 6. Decentralized Verification + +Agents can verify authorization locally without hitting the control plane on every call. All three SDKs (Python, Go, TypeScript) implement a `LocalVerifier` that caches: + +- **Access policies** — fetched from `GET /api/v1/policies` +- **Revocation list** — fetched from `GET /api/v1/revocations` +- **Admin public key** — fetched from `GET /api/v1/admin/public-key` + +**Cache refresh:** Every 5 minutes (configurable via `refresh_interval`). + +**Local verification steps:** +1. Check caller DID not in revocation list +2. Validate timestamp within window (default 300 seconds) +3. Verify Ed25519 signature using cached admin public key +4. Evaluate policies locally using cached rules +5. Check parameter constraints + +**Opt-out per function:** Functions marked with `require_realtime_validation=True` bypass local verification and forward to the control plane. + +```python +# Python SDK +@app.reasoner(require_realtime_validation=True) +async def high_security_operation(input_data): + ... +``` + +```typescript +// TypeScript SDK +agent.registerReasoner("sensitive_op", handler, { + requireRealtimeValidation: true, +}); +``` + +**Fail-closed behavior:** +- No policies cached → deny access +- Tag VC signature verification fails → use empty tags (deny unless explicit allow-all policy) +- Control plane unreachable → use stale cache (controlled degradation) + +--- + +## Trust Model + +### What We Trust + +| Entity | Trust Level | Rationale | +|--------|-------------|-----------| +| Control Plane | Full | Central authority, hosts DIDs, issues VCs, enforces policies | +| Admin | Full | Approves/rejects tags, defines access policies, manages revocations | +| Agent's Private Key | Cryptographic | Proves DID ownership via Ed25519 signatures | + +### What We Don't Trust + +| Entity | Protection Mechanism | +|--------|---------------------| +| Developers proposing tags | Tags are *proposed*, not active until admin approves | +| Agents spoofing DIDs | DID ownership proven via Ed25519 cryptographic signature | +| Forged AgentTagVCs | VC signature verified against control plane issuer's public key | +| Modified VCs | Any modification breaks Ed25519 signature → rejected | +| Expired approvals | Expiration checked on each call (both VC and approval) | +| Replay attacks | Timestamp window + in-memory signature cache with TTL | + +### Two-Step Authorization + +**Step 1: Tag Assignment (Admin Approval)** +- **Question:** Does this agent deserve these tags? +- **Who decides:** Admin (or auto-approval rules) +- **When:** At registration time +- **Result:** AgentTagVC with approved tags, signed by control plane + +**Step 2: Function Call (Policy Evaluation)** +- **Question:** Can caller's tags call target's function with these parameters? +- **Who decides:** Policy engine (automated, based on admin-defined policies) +- **When:** Every function call +- **Result:** Allow or deny based on tag-matching policies + parameter constraints + +Both steps must pass for access to work. + +### Security Boundaries + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SECURITY BOUNDARY: Control Plane │ +│ │ +│ - Issues DIDs (did:web) │ +│ - Hosts DID documents (enables revocation) │ +│ - Evaluates tag approval rules │ +│ - Issues signed AgentTagVCs (Ed25519) │ +│ - Evaluates access policies at call time │ +│ - Stores approval records (source of truth) │ +│ - Publishes policies, revocations, public keys for caching │ +└─────────────────────────────────────────────────────────────────┘ + │ + │ Admin controls + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ TRUST BOUNDARY: Admin │ +│ │ +│ - Configures tag approval rules (auto/manual/forbidden) │ +│ - Reviews and approves/rejects proposed tags │ +│ - Defines access policies (caller_tags → target_tags) │ +│ - Can revoke tags and VCs at any time │ +└─────────────────────────────────────────────────────────────────┘ + │ + │ Credentials issued + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ AGENT BOUNDARY: Proposed Identity │ +│ │ +│ - Agents propose tags (not active until approved) │ +│ - Tags can be per-skill/per-reasoner │ +│ - Agents cannot grant themselves access │ +│ - Must request and wait for admin approval │ +│ - Can cache policies for local verification │ +│ - Can opt functions into realtime validation │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## API Contracts + +### Agent Registration + +```http +POST /api/v1/nodes/register +Content-Type: application/json + +{ + "id": "finance-bot", + "team_id": "default", + "base_url": "http://localhost:9001", + "reasoners": [ + { + "id": "process_payment", + "tags": ["finance", "pci-compliant"], + "proposed_tags": ["finance", "pci-compliant"], + "input_schema": {} + } + ], + "skills": [ + { + "id": "get_balance", + "tags": ["finance"], + "proposed_tags": ["finance"], + "input_schema": {} + } + ] +} +``` + +**Response (all tags auto-approved):** +```json +{ + "success": true, + "message": "Node registered", + "node_id": "finance-bot" +} +``` + +**Response (some tags need manual review):** +```json +{ + "success": true, + "message": "Node registered but awaiting tag approval", + "node_id": "finance-bot", + "status": "pending_approval", + "proposed_tags": ["finance", "pci-compliant"], + "pending_tags": ["finance"], + "auto_approved_tags": ["pci-compliant"] +} +``` + +**Response (forbidden tag):** +```json +HTTP 403 +{ + "error": "forbidden_tags", + "message": "Registration rejected: tags [root] are forbidden", + "forbidden_tags": ["root"] +} +``` + +**Registration flow:** +1. Parse registration, normalize tags (`proposed_tags` ↔ `tags` bidirectional sync) +2. Evaluate tag approval rules if service enabled +3. If any forbidden tags → reject with HTTP 403 +4. If any manual tags → set lifecycle status to `pending_approval` +5. If all auto → set lifecycle status to `starting`, set approved_tags immediately +6. Create did:web document for the agent +7. Store agent in database + +### Admin Endpoints — Tag Approval + +#### List Pending Agents +```http +GET /api/v1/admin/agents/pending + +Response 200: +{ + "agents": [ + { + "agent_id": "finance-bot", + "proposed_tags": ["finance", "reporting", "admin"], + "approved_tags": [], + "status": "pending_approval", + "registered_at": "2026-02-08T12:00:00Z" + } + ], + "total": 1 +} +``` + +#### Approve Agent Tags (Agent-Level) +```http +POST /api/v1/admin/agents/:agent_id/approve-tags +Content-Type: application/json + +{ + "approved_tags": ["finance", "reporting"], + "reason": "Approved standard finance tags" +} + +Response 200: +{ + "success": true, + "message": "Agent tags approved", + "agent_id": "finance-bot", + "approved_tags": ["finance", "reporting"] +} +``` + +#### Approve Tags Per Skill/Reasoner +```http +POST /api/v1/admin/agents/:agent_id/approve-tags +Content-Type: application/json + +{ + "approved_tags": ["finance"], + "skill_tags": { + "get_balance": ["finance"], + "charge_customer": ["finance", "pci-compliant"] + }, + "reasoner_tags": { + "process_payment": ["finance", "pci-compliant"] + }, + "reason": "Per-skill approval with different tag scopes" +} +``` + +When `skill_tags` or `reasoner_tags` are provided, approval is per-skill/per-reasoner. Each skill/reasoner gets only its specified tags. The agent-level `approved_tags` becomes the union of all per-skill/per-reasoner approved tags. + +#### Reject Agent Tags +```http +POST /api/v1/admin/agents/:agent_id/reject-tags +Content-Type: application/json + +{ + "reason": "Tags not appropriate for this deployment" +} + +Response 200: +{ + "success": true, + "message": "Agent tags rejected", + "agent_id": "finance-bot" +} +``` + +Rejection moves the agent to `offline` status. + +### Admin Endpoints — Access Policies + +#### List Policies +```http +GET /api/v1/admin/policies + +Response 200: +{ + "policies": [ + { + "id": 1, + "name": "finance_to_billing", + "caller_tags": ["finance"], + "target_tags": ["billing"], + "allow_functions": ["charge_*", "refund_*"], + "deny_functions": ["delete_*"], + "constraints": { + "amount": {"operator": "<=", "value": 10000} + }, + "action": "allow", + "priority": 10, + "enabled": true, + "description": "Finance agents can call billing functions" + } + ], + "total": 1 +} +``` + +#### Create Policy +```http +POST /api/v1/admin/policies +Content-Type: application/json + +{ + "name": "finance_to_billing", + "caller_tags": ["finance"], + "target_tags": ["billing"], + "allow_functions": ["charge_*", "refund_*"], + "deny_functions": ["delete_*"], + "constraints": { + "amount": {"operator": "<=", "value": 10000} + }, + "action": "allow", + "priority": 10, + "description": "Finance agents can call billing functions" +} + +Response 201: (created AccessPolicy object) +``` + +#### Get / Update / Delete Policy +```http +GET /api/v1/admin/policies/:id +PUT /api/v1/admin/policies/:id +DELETE /api/v1/admin/policies/:id +``` + +### Agent-Facing Endpoints (Decentralized Verification) + +#### Fetch Policies (for local caching) +```http +GET /api/v1/policies + +Response 200: +{ + "policies": [...], + "total": 5, + "fetched_at": "2026-02-08T12:00:00Z" +} +``` + +#### Fetch Revocation List (for local caching) +```http +GET /api/v1/revocations + +Response 200: +{ + "revoked_dids": [ + "did:web:example.com:agents:compromised-agent" + ], + "total": 1, + "fetched_at": "2026-02-08T12:00:00Z" +} +``` + +#### Fetch Admin Public Key (for local VC verification) +```http +GET /api/v1/admin/public-key + +Response 200: +{ + "issuer_did": "did:web:localhost%3A8080:agents:control-plane", + "public_key_jwk": { + "kty": "OKP", + "crv": "Ed25519", + "x": "base64url_encoded_32_byte_key" + }, + "fetched_at": "2026-02-08T12:00:00Z" +} +``` + +### DID Resolution (did:web) + +```http +GET /agents/:agent_id/did.json + +Response 200 (active): +{ + "@context": ["https://www.w3.org/ns/did/v1"], + "id": "did:web:example.com:agents:agent-a", + "verificationMethod": [{ + "id": "did:web:example.com:agents:agent-a#key-1", + "type": "JsonWebKey2020", + "controller": "did:web:example.com:agents:agent-a", + "publicKeyJwk": { + "kty": "OKP", + "crv": "Ed25519", + "x": "..." + } + }], + "authentication": ["did:web:example.com:agents:agent-a#key-1"] +} + +Response 404 (revoked): +{ + "error": "did_revoked", + "message": "This DID has been revoked" +} +``` + +--- + +## Configuration + +### What Goes Where + +| Data | Source | Purpose | +|------|--------|---------| +| **Tag approval rules** | Config file | Controls which tags need manual approval | +| **Access policies** | Config file + Database (Admin API) | Tag-based authorization rules | +| **Agent Tag VCs** | Database | Stores signed VCs certifying agent tags | +| **DID documents** | Database | Stores did:web documents for resolution | +| **Agent proposed_tags** | Agent registration | Tags the developer proposes (per skill/reasoner) | +| **Agent approved_tags** | Admin approval / auto | Tags granted after evaluation | + +### Full Configuration Example + +```yaml +# agentfield.yaml +features: + did: + authorization: + # Enable/disable the authorization system + enabled: true + + # Enable DID-based authentication on API routes + did_auth_enabled: true + + # Domain for did:web identifiers + domain: "agentfield.example.com" + + # Allowed time drift for DID signature timestamps (seconds) + timestamp_window_seconds: 300 + + # Default duration for permission approvals (hours) + default_approval_duration_hours: 720 # 30 days + + # Separate token for admin operations (tag approval, policy management) + admin_token: "admin-secret-token" + + # Token sent to agents during request forwarding + # (agents with RequireOriginAuth validate this) + internal_token: "internal-secret-token" + + # Tag approval rules + tag_approval_rules: + default_mode: auto # "auto" | "manual" | "forbidden" + rules: + - tags: ["admin", "superuser"] + approval: manual + reason: "Admin-level tags require review" + - tags: ["dangerous", "root"] + approval: forbidden + reason: "These tags are not allowed" + - tags: ["internal", "beta"] + approval: auto + reason: "Safe tags, no special privileges" + + # Access policies (seeded at startup, also manageable via Admin API) + access_policies: + - name: finance_to_billing + caller_tags: ["finance"] + target_tags: ["billing"] + allow_functions: ["charge_*", "refund_*", "get_*"] + deny_functions: ["delete_*", "admin_*"] + constraints: + amount: + operator: "<=" + value: 10000 + action: allow + priority: 10 + - name: support_readonly + caller_tags: ["support"] + target_tags: ["customer-data"] + allow_functions: ["get_*", "query_*"] + action: allow + priority: 5 +``` + +### Environment Variables + +```bash +# Enable authorization +AGENTFIELD_AUTHORIZATION_ENABLED=true + +# Enable DID-based authentication on API routes +AGENTFIELD_AUTHORIZATION_DID_AUTH_ENABLED=true + +# Domain for did:web identifiers +AGENTFIELD_AUTHORIZATION_DOMAIN=agentfield.example.com + +# Separate token for admin operations +AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN=admin-secret-token + +# Token sent to agents during request forwarding +AGENTFIELD_AUTHORIZATION_INTERNAL_TOKEN=internal-secret-token +``` + +Environment variables take precedence over YAML config values. + +--- + +## Database Schema + +### did_documents +Stores DID documents for did:web resolution. + +```sql +CREATE TABLE did_documents ( + did TEXT PRIMARY KEY, + agent_id TEXT NOT NULL, + did_document JSONB NOT NULL, + public_key_jwk TEXT NOT NULL, + revoked_at TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); +``` + +### access_policies +Stores tag-based authorization policies. + +```sql +CREATE TABLE access_policies ( + id BIGSERIAL PRIMARY KEY, + name TEXT NOT NULL UNIQUE, + caller_tags TEXT NOT NULL, -- JSON array + target_tags TEXT NOT NULL, -- JSON array + allow_functions TEXT, -- JSON array + deny_functions TEXT, -- JSON array + constraints TEXT, -- JSON object {param: {operator, value}} + action TEXT NOT NULL DEFAULT 'allow', + priority INTEGER NOT NULL DEFAULT 0, + enabled BOOLEAN NOT NULL DEFAULT TRUE, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); +``` + +### agent_tag_vcs +Stores signed Agent Tag VCs issued upon tag approval. + +```sql +CREATE TABLE agent_tag_vcs ( + id BIGSERIAL PRIMARY KEY, + agent_id TEXT NOT NULL UNIQUE, + agent_did TEXT NOT NULL, + vc_id TEXT NOT NULL UNIQUE, + vc_document TEXT NOT NULL, -- Full W3C VC JSON + signature TEXT, -- Ed25519 signature + issued_at TIMESTAMP WITH TIME ZONE NOT NULL, + expires_at TIMESTAMP WITH TIME ZONE, + revoked_at TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW() +); +``` + +--- + +## Middleware Architecture + +### Request Processing Pipeline + +``` +Incoming Request + │ + ▼ +┌──────────────────────────┐ +│ DID Auth Middleware │ +│ - Extract X-Caller-DID │ +│ - Verify Ed25519 sig │ +│ - Check timestamp window │ +│ - Replay protection │ +│ - Store verified DID │ +│ in request context │ +└──────────────────────────┘ + │ + ▼ +┌──────────────────────────┐ +│ Permission Middleware │ +│ │ +│ 1. Target in pending_ │ +│ approval? → 503 │ +│ │ +│ 2. LAYER 1: Tag Policy │ +│ - Load caller's │ +│ AgentTagVC │ +│ - Verify VC signature │ +│ - Get tags from VC │ +│ - EvaluateAccess() │ +│ - Policy matched? │ +│ YES → allow/deny │ +│ │ +│ 3. No policy matched: │ +│ Allow (backward compat)│ +└──────────────────────────┘ + │ + ▼ +┌──────────────────────────┐ +│ Execute Handler │ +│ - Forward to target agent │ +│ - Include X-Caller-DID │ +│ and X-Target-DID headers│ +└──────────────────────────┘ +``` + +### DID Auth Headers + +| Header | Description | +|--------|-------------| +| `X-Caller-DID` | Agent's DID (e.g., `did:web:example.com:agents:agent-a`) | +| `X-DID-Signature` | Base64-encoded Ed25519 signature | +| `X-DID-Timestamp` | ISO 8601 timestamp of signing | + +**Signature payload:** `{timestamp}:{SHA256(request_body)}` + +**Replay protection:** In-memory signature cache with TTL matching the timestamp window. SHA256 hash of decoded signature is tracked. + +--- + +## Backward Compatibility + +### Default Mode is Zero-Disruption + +- `tag_approval_rules.default_mode: auto` — all tags auto-approved when no rules configured +- If no access policies are defined, the policy engine returns `Matched: false` and the request is allowed +- If authorization is disabled (`enabled: false`), all middleware is skipped +- `proposed_tags` ↔ `tags` bidirectional sync ensures old SDKs work seamlessly + +### Policy Evaluation Behavior + +The permission middleware evaluates tag-based access policies: +1. If a policy matches, it decides (allow or deny) +2. If no policy matches, the request is allowed (backward compatible for untagged agents) + +### Migration Path + +1. **Phase 1:** Deploy with `authorization.enabled: false` (default) +2. **Phase 2:** Enable authorization, configure tag approval rules +3. **Phase 3:** Define access policies for tag-based authorization +4. **Phase 4:** Monitor policy evaluation results, tune policies +5. **Phase 5:** Enable decentralized verification in SDKs for performance + +### Authorization Rules + +| Scenario | Behavior | +|----------|----------| +| Agent in pending_approval | 503 Unavailable | +| Policy match → allow | Access granted | +| Policy match → deny | 403 Forbidden | +| No policy match | Allowed (backward compatible) | +| Authorization disabled | All middleware skipped | + +--- + +## Appendix: Glossary + +| Term | Definition | +|------|------------| +| **DID** | Decentralized Identifier — globally unique identifier for agents | +| **did:key** | DID method where identifier is derived from public key | +| **did:web** | DID method where identifier resolves to a web URL | +| **VC** | Verifiable Credential — signed, tamper-evident credential | +| **AgentTagVC** | VC certifying an agent's approved tags (per-agent, issued on tag approval) | +| **Access Policy** | Tag-based rule controlling which agents can call which functions | +| **Tag Approval Rule** | Configuration controlling which tags require admin review | +| **Approval** | Admin decision granting tags to an agent | +| **Revocation** | Invalidating a DID, VC, or permission before expiration | +| **CanonicalAgentTags** | Normalized tag set: prefers approved_tags, excludes metadata | +| **LocalVerifier** | SDK component that caches policies/revocations for offline verification | + +--- + +*End of Architecture Document* diff --git a/examples/go_agent_nodes/cmd/multi_version/main.go b/examples/go_agent_nodes/cmd/multi_version/main.go new file mode 100644 index 00000000..6cd50774 --- /dev/null +++ b/examples/go_agent_nodes/cmd/multi_version/main.go @@ -0,0 +1,248 @@ +// Multi-Version Agent Example (Go) +// +// Demonstrates multi-version agent support using the composite primary key +// (id, version). All agents share the same NodeID but register with different +// versions, creating separate rows in the control plane. +// +// The execute endpoint transparently routes across versioned agents using +// weighted round-robin when no default (unversioned) agent exists. +// +// Usage: +// +// # Start control plane first, then: +// cd examples/go_agent_nodes +// go run ./cmd/multi_version +package main + +import ( + "context" + "encoding/json" + "fmt" + "io" + "log" + "net/http" + "os" + "os/signal" + "strings" + "sync" + "syscall" + "time" + + "github.com/Agent-Field/agentfield/sdk/go/agent" +) + +const ( + agentID = "mv-demo-go" + basePort = 9300 +) + +type versionSpec struct { + version string + port int +} + +func cpURL() string { + if v := strings.TrimSpace(os.Getenv("AGENTFIELD_URL")); v != "" { + return v + } + return "http://localhost:8080" +} + +func createAgent(spec versionSpec) (*agent.Agent, error) { + listenAddr := fmt.Sprintf(":%d", spec.port) + publicURL := fmt.Sprintf("http://localhost:%d", spec.port) + + cfg := agent.Config{ + NodeID: agentID, + Version: spec.version, + AgentFieldURL: cpURL(), + Token: os.Getenv("AGENTFIELD_TOKEN"), + ListenAddress: listenAddr, + PublicURL: publicURL, + } + + a, err := agent.New(cfg) + if err != nil { + return nil, fmt.Errorf("failed to create agent v%s: %w", spec.version, err) + } + + // Echo reasoner present on every version + ver := spec.version // capture for closure + a.RegisterReasoner("echo", func(ctx context.Context, input map[string]any) (any, error) { + msg := "" + if v, ok := input["message"]; ok { + msg = fmt.Sprintf("%v", v) + } + return map[string]any{ + "agent": agentID, + "version": ver, + "echoed": msg, + }, nil + }, agent.WithDescription("Echo back the input with version info")) + + // v2 has an extra capability + if spec.version == "2.0.0" { + a.RegisterReasoner("v2_feature", func(ctx context.Context, input map[string]any) (any, error) { + return map[string]any{ + "agent": agentID, + "version": ver, + "feature": "Only available in v2", + "input": input, + }, nil + }, agent.WithDescription("Feature only available in v2")) + } + + return a, nil +} + +func validateRegistration() { + fmt.Println("\n--- Validating multi-version registration ---") + cp := cpURL() + client := &http.Client{Timeout: 30 * time.Second} + + // List all nodes and check that both versions are registered + resp, err := client.Get(cp + "/api/v1/nodes?show_all=true") + if err != nil { + fmt.Printf("Failed to list nodes: %v\n", err) + return + } + defer resp.Body.Close() + + body, _ := io.ReadAll(resp.Body) + var nodesResp struct { + Nodes []struct { + ID string `json:"id"` + NodeID string `json:"node_id"` + Version string `json:"version"` + BaseURL string `json:"base_url"` + } `json:"nodes"` + Agents []struct { + ID string `json:"id"` + NodeID string `json:"node_id"` + Version string `json:"version"` + BaseURL string `json:"base_url"` + } `json:"agents"` + } + if err := json.Unmarshal(body, &nodesResp); err != nil { + fmt.Printf("Failed to parse nodes response: %v\n", err) + return + } + + allNodes := nodesResp.Nodes + if len(allNodes) == 0 { + allNodes = nodesResp.Agents + } + + var agentNodes []struct { + ID string + Version string + BaseURL string + } + for _, n := range allNodes { + nid := n.ID + if nid == "" { + nid = n.NodeID + } + if nid == agentID { + agentNodes = append(agentNodes, struct { + ID string + Version string + BaseURL string + }{nid, n.Version, n.BaseURL}) + } + } + + fmt.Printf("\n[Nodes] Found %d versions of %q:\n", len(agentNodes), agentID) + for _, n := range agentNodes { + fmt.Printf(" - id=%s, version=%s, base_url=%s\n", n.ID, n.Version, n.BaseURL) + } + + // Execute against the shared ID - the CP will route via round-robin + fmt.Printf("\n[Execute] Sending requests to %s.echo:\n", agentID) + for i := 0; i < 4; i++ { + payload := fmt.Sprintf(`{"input":{"message":"request-%d"}}`, i) + req, _ := http.NewRequest("POST", + fmt.Sprintf("%s/api/v1/execute/%s.echo", cp, agentID), + strings.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + + resp, err := client.Do(req) + if err != nil { + fmt.Printf(" Request %d: failed - %v\n", i, err) + continue + } + + var result map[string]any + json.NewDecoder(resp.Body).Decode(&result) + resp.Body.Close() + routedVersion := resp.Header.Get("X-Routed-Version") + if routedVersion == "" { + if payload, ok := result["result"].(map[string]any); ok { + if payloadVersion, ok := payload["version"].(string); ok && payloadVersion != "" { + routedVersion = payloadVersion + } + } + } + if routedVersion == "" { + routedVersion = "(unknown)" + } + + fmt.Printf(" Request %d: routed to version=%s, result=%v\n", i, routedVersion, result["result"]) + } + + fmt.Println("\n--- Validation complete ---") +} + +func main() { + versions := []versionSpec{ + {version: "1.0.0", port: basePort}, + {version: "2.0.0", port: basePort + 1}, + } + + fmt.Println("Multi-version agent example (Go)") + fmt.Printf(" Control plane: %s\n", cpURL()) + fmt.Printf(" Agent ID: %s\n", agentID) + parts := make([]string, len(versions)) + for i, v := range versions { + parts[i] = fmt.Sprintf("%s@:%d", v.version, v.port) + } + fmt.Printf(" Versions: %s\n\n", strings.Join(parts, ", ")) + + // Create and start all agents + var wg sync.WaitGroup + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + for _, spec := range versions { + a, err := createAgent(spec) + if err != nil { + log.Fatalf("Failed to create agent v%s: %v", spec.version, err) + } + + wg.Add(1) + go func(a *agent.Agent, spec versionSpec) { + defer wg.Done() + fmt.Printf(" Started %s v%s on port %d\n", agentID, spec.version, spec.port) + if err := a.Run(ctx); err != nil && ctx.Err() == nil { + log.Printf("Agent v%s exited with error: %v", spec.version, err) + } + }(a, spec) + } + + // Give the CP a moment to process registrations (DID creation takes ~5s) + fmt.Println("\n Waiting for registrations to propagate...") + time.Sleep(8 * time.Second) + + // Validate + validateRegistration() + + // Keep running so heartbeats continue + fmt.Println("\nAll agents running. Press Ctrl+C to stop.\n") + sigCh := make(chan os.Signal, 1) + signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM) + <-sigCh + + fmt.Println("Shutting down.") + cancel() + wg.Wait() +} diff --git a/examples/go_agent_nodes/cmd/permission_agent_a/main.go b/examples/go_agent_nodes/cmd/permission_agent_a/main.go new file mode 100644 index 00000000..ad5af822 --- /dev/null +++ b/examples/go_agent_nodes/cmd/permission_agent_a/main.go @@ -0,0 +1,165 @@ +// Permission Agent A (Caller) — Go SDK +// +// An agent with tag "analytics" that demonstrates the policy engine: +// - call_data_service -> calls go-perm-target.query_data (ALLOWED by policy) +// - call_large_query -> calls go-perm-target.query_data with limit=5000 (DENIED: constraint) +// - call_delete_records -> calls go-perm-target.delete_records (DENIED: deny_functions) +// +// The "analytics" tag auto-approves (tag_approval_rules), so this agent starts +// immediately in "active" state. +// +// Test flow: +// 1. Start control plane with authorization enabled +// 2. Start go-perm-target -> enters pending_approval +// 3. Admin approves go-perm-target's tags +// 4. Start go-perm-caller (this agent) -> auto-approved +// 5. POST /api/v1/execute/go-perm-caller.call_data_service -> 200 OK +// 6. POST /api/v1/execute/go-perm-caller.call_large_query -> 403 constraint +// 7. POST /api/v1/execute/go-perm-caller.call_delete_records -> 403 denied function +package main + +import ( + "context" + "fmt" + "log" + "os" + "strings" + + "github.com/Agent-Field/agentfield/sdk/go/agent" +) + +func main() { + agentFieldURL := strings.TrimSpace(os.Getenv("AGENTFIELD_URL")) + if agentFieldURL == "" { + agentFieldURL = "http://localhost:8080" + } + + listenAddr := strings.TrimSpace(os.Getenv("AGENT_LISTEN_ADDR")) + if listenAddr == "" { + listenAddr = ":8003" + } + + publicURL := strings.TrimSpace(os.Getenv("AGENT_PUBLIC_URL")) + if publicURL == "" { + publicURL = "http://localhost" + listenAddr + } + + cfg := agent.Config{ + NodeID: "go-perm-caller", + Version: "1.0.0", + AgentFieldURL: agentFieldURL, + Token: os.Getenv("AGENTFIELD_TOKEN"), + InternalToken: os.Getenv("AGENTFIELD_INTERNAL_TOKEN"), + ListenAddress: listenAddr, + PublicURL: publicURL, + EnableDID: true, // Auto-register DID during Initialize() + VCEnabled: true, // Generate VCs for audit trail + Tags: []string{"analytics"}, + LocalVerification: true, // Verify DID signatures locally + RequireOriginAuth: true, + } + + a, err := agent.New(cfg) + if err != nil { + log.Fatal(err) + } + + // Simple health check — no cross-agent call, should always work. + a.RegisterReasoner("ping", func(ctx context.Context, input map[string]any) (any, error) { + return map[string]any{ + "status": "ok", + "agent": "go-perm-caller", + }, nil + }, + agent.WithDescription("Simple health check"), + agent.WithVCEnabled(false), // No VC needed for health checks + ) + + // Calls go-perm-target.query_data with a small limit. + // Should succeed: analytics -> data-service, query_* is in allow_functions, + // limit=100 satisfies the <= 1000 constraint. + a.RegisterReasoner("call_data_service", func(ctx context.Context, input map[string]any) (any, error) { + query := fmt.Sprintf("%v", input["query"]) + if query == "" || query == "" { + query = "SELECT * FROM data" + } + + result, err := a.Call(ctx, "go-perm-target.query_data", map[string]any{ + "query": query, + "limit": 100, + }) + if err != nil { + return nil, fmt.Errorf("failed to call go-perm-target.query_data: %w", err) + } + + return map[string]any{ + "source": "go-perm-caller", + "test": "allowed_query", + "delegation_result": result, + }, nil + }, + agent.WithDescription("Calls go-perm-target.query_data (allowed)"), + agent.WithReasonerTags("analytics"), + ) + + // Calls go-perm-target.query_data with limit=5000. + // Should fail: limit=5000 violates the <= 1000 constraint. + a.RegisterReasoner("call_large_query", func(ctx context.Context, input map[string]any) (any, error) { + query := fmt.Sprintf("%v", input["query"]) + if query == "" || query == "" { + query = "SELECT * FROM big_table" + } + + result, err := a.Call(ctx, "go-perm-target.query_data", map[string]any{ + "query": query, + "limit": 5000, + }) + if err != nil { + return nil, fmt.Errorf("failed to call go-perm-target.query_data: %w", err) + } + + return map[string]any{ + "source": "go-perm-caller", + "test": "constraint_violation", + "delegation_result": result, + }, nil + }, + agent.WithDescription("Calls go-perm-target.query_data with large limit (constraint violation)"), + agent.WithReasonerTags("analytics"), + ) + + // Calls go-perm-target.delete_records. + // Should fail: delete_* is in deny_functions for analytics->data-service. + a.RegisterReasoner("call_delete_records", func(ctx context.Context, input map[string]any) (any, error) { + table := fmt.Sprintf("%v", input["table"]) + if table == "" || table == "" { + table = "sensitive_records" + } + + result, err := a.Call(ctx, "go-perm-target.delete_records", map[string]any{ + "table": table, + }) + if err != nil { + return nil, fmt.Errorf("failed to call go-perm-target.delete_records: %w", err) + } + + return map[string]any{ + "source": "go-perm-caller", + "test": "deny_function", + "delegation_result": result, + }, nil + }, + agent.WithDescription("Calls go-perm-target.delete_records (denied by policy)"), + agent.WithReasonerTags("analytics"), + ) + + fmt.Println("Permission Agent A (Caller) — Go SDK") + fmt.Println("Node: go-perm-caller") + fmt.Printf("Server: %s\n", agentFieldURL) + fmt.Println("Tags: analytics") + fmt.Println("Test reasoners: call_data_service (allow), call_large_query (constraint), call_delete_records (deny)") + + if err := a.Run(context.Background()); err != nil { + log.Fatal(err) + } +} diff --git a/examples/go_agent_nodes/cmd/permission_agent_b/main.go b/examples/go_agent_nodes/cmd/permission_agent_b/main.go new file mode 100644 index 00000000..7f32aaa0 --- /dev/null +++ b/examples/go_agent_nodes/cmd/permission_agent_b/main.go @@ -0,0 +1,139 @@ +// Permission Agent B (Protected Target) — Go SDK +// +// A protected agent with tags ["sensitive", "data-service"]. The "sensitive" +// tag triggers manual approval (tag_approval_rules in config), so this agent +// starts in "pending_approval" state until an admin approves its tags. +// +// Once approved, access policies control which callers can invoke which reasoners: +// - analytics callers can call query_data and get_schema (allowed by policy) +// - analytics callers are denied delete_records (deny_functions in policy) +// - constraint violations (e.g. limit > 1000) are rejected +// +// Reasoners: +// - query_data(query, limit) — simulates a data query (allowed for analytics) +// - delete_records(table) — simulates record deletion (denied for analytics) +// - get_schema — returns the data schema +package main + +import ( + "context" + "fmt" + "log" + "os" + "strings" + + "github.com/Agent-Field/agentfield/sdk/go/agent" +) + +func main() { + agentFieldURL := strings.TrimSpace(os.Getenv("AGENTFIELD_URL")) + if agentFieldURL == "" { + agentFieldURL = "http://localhost:8080" + } + + listenAddr := strings.TrimSpace(os.Getenv("AGENT_LISTEN_ADDR")) + if listenAddr == "" { + listenAddr = ":8004" + } + + publicURL := strings.TrimSpace(os.Getenv("AGENT_PUBLIC_URL")) + if publicURL == "" { + publicURL = "http://localhost" + listenAddr + } + + cfg := agent.Config{ + NodeID: "go-perm-target", + Version: "1.0.0", + AgentFieldURL: agentFieldURL, + Token: os.Getenv("AGENTFIELD_TOKEN"), + InternalToken: os.Getenv("AGENTFIELD_INTERNAL_TOKEN"), + ListenAddress: listenAddr, + PublicURL: publicURL, + EnableDID: true, // Auto-register DID during Initialize() + VCEnabled: true, // Generate VCs for audit trail + Tags: []string{"sensitive", "data-service"}, + RequireOriginAuth: true, // Only the control plane can invoke reasoners + } + + b, err := agent.New(cfg) + if err != nil { + log.Fatal(err) + } + + // Reasoner 1: query_data — simulates a data query. + // Allowed for analytics callers by the access policy (query_* in allow_functions). + // The "limit" parameter is constrained to <= 1000 by the policy. + b.RegisterReasoner("query_data", func(ctx context.Context, input map[string]any) (any, error) { + query := fmt.Sprintf("%v", input["query"]) + if query == "" || query == "" { + query = "SELECT *" + } + + limit := 100 + if l, ok := input["limit"]; ok { + if lf, ok := l.(float64); ok { + limit = int(lf) + } + } + + return map[string]any{ + "status": "success", + "agent": "go-perm-target", + "query": query, + "limit": limit, + "results": []map[string]any{{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}}, + "message": fmt.Sprintf("Query executed: %s (limit=%d)", query, limit), + }, nil + }, + agent.WithDescription("Execute a data query. Protected by access policy."), + agent.WithReasonerTags("sensitive", "data-service"), + ) + + // Reasoner 2: delete_records — simulates record deletion. + // Denied for analytics callers by the access policy (delete_* in deny_functions). + b.RegisterReasoner("delete_records", func(ctx context.Context, input map[string]any) (any, error) { + table := fmt.Sprintf("%v", input["table"]) + if table == "" || table == "" { + table = "records" + } + + return map[string]any{ + "status": "deleted", + "agent": "go-perm-target", + "table": table, + "message": fmt.Sprintf("Records deleted from %s", table), + }, nil + }, + agent.WithDescription("Delete records. Denied for analytics callers by policy."), + agent.WithReasonerTags("data-service"), + ) + + // Reasoner 3: get_schema — returns the data schema. + b.RegisterReasoner("get_schema", func(ctx context.Context, input map[string]any) (any, error) { + return map[string]any{ + "status": "success", + "agent": "go-perm-target", + "schema": map[string]any{ + "table": "records", + "columns": []map[string]any{ + {"name": "id", "type": "integer", "primary_key": true}, + {"name": "name", "type": "text"}, + {"name": "created_at", "type": "timestamp"}, + }, + }, + }, nil + }, + agent.WithDescription("Get the data schema."), + agent.WithReasonerTags("data-service"), + ) + + fmt.Println("Permission Agent B (Protected) — Go SDK") + fmt.Println("Node: go-perm-target") + fmt.Printf("Server: %s\n", agentFieldURL) + fmt.Println("Tags: sensitive, data-service") + fmt.Println("Reasoners: query_data, delete_records, get_schema") + + if err := b.Run(context.Background()); err != nil { + log.Fatal(err) + } +} diff --git a/examples/go_agent_nodes/go_agent_nodes b/examples/go_agent_nodes/multi_version similarity index 54% rename from examples/go_agent_nodes/go_agent_nodes rename to examples/go_agent_nodes/multi_version index 729b4b27..9092ea43 100755 Binary files a/examples/go_agent_nodes/go_agent_nodes and b/examples/go_agent_nodes/multi_version differ diff --git a/examples/python_agent_nodes/multi_version/main.py b/examples/python_agent_nodes/multi_version/main.py new file mode 100644 index 00000000..da426d8f --- /dev/null +++ b/examples/python_agent_nodes/multi_version/main.py @@ -0,0 +1,175 @@ +""" +Multi-Version Agent Example (Python) + +Demonstrates multi-version agent support using the composite primary key +(id, version). All agents share the same node_id but register with different +versions, creating separate rows in the control plane. + +The execute endpoint transparently routes across versioned agents using +weighted round-robin when no default (unversioned) agent exists. + +Usage: + # Start control plane first, then: + cd examples/python_agent_nodes/multi_version + python main.py +""" + +import asyncio +import os +import signal +import sys +import time +from typing import List + +import httpx +from agentfield import Agent + + +CP_URL = os.getenv("AGENTFIELD_URL", "http://localhost:8080") +AGENT_ID = "mv-demo-py" +BASE_PORT = 9200 + + +def create_agent(version: str, port: int) -> Agent: + """Create an agent instance for a specific version.""" + app = Agent( + node_id=AGENT_ID, + agentfield_server=CP_URL, + version=version, + dev_mode=False, + callback_url=f"http://localhost:{port}", + ) + + @app.reasoner() + async def echo(message: str = "") -> dict: + """Echo reasoner present on every version.""" + return { + "agent": AGENT_ID, + "version": version, + "echoed": message, + } + + if version == "2.0.0": + + @app.reasoner() + async def v2_feature(data: str = "") -> dict: + """Extra capability only available in v2.""" + return { + "agent": AGENT_ID, + "version": version, + "feature": "Only available in v2", + "input": data, + } + + return app + + +async def validate_registration(): + """Validate that both versions registered and routing works.""" + print("\n--- Validating multi-version registration ---\n") + + async with httpx.AsyncClient(timeout=30.0) as client: + # List all nodes and check that both versions are registered + try: + res = await client.get(f"{CP_URL}/api/v1/nodes?show_all=true") + res.raise_for_status() + data = res.json() + nodes = data.get("nodes") or data.get("agents") or [] + agent_nodes = [ + n for n in nodes if (n.get("id") or n.get("node_id")) == AGENT_ID + ] + print(f'[Nodes] Found {len(agent_nodes)} versions of "{AGENT_ID}":') + for n in agent_nodes: + nid = n.get("id") or n.get("node_id") + print( + f" - id={nid}, version={n.get('version')}, base_url={n.get('base_url')}" + ) + except Exception as e: + print(f"Failed to list nodes: {e}") + return + + # Execute against the shared ID - the CP will route via round-robin + print(f"\n[Execute] Sending requests to {AGENT_ID}.echo:") + for i in range(4): + try: + res = await client.post( + f"{CP_URL}/api/v1/execute/{AGENT_ID}.echo", + json={"input": {"message": f"request-{i}"}}, + headers={"Content-Type": "application/json"}, + ) + body = res.json() + result = body.get("result") or {} + payload_version = ( + result.get("version") if isinstance(result, dict) else None + ) + routed_version = ( + res.headers.get("X-Routed-Version") + or payload_version + or "(unknown)" + ) + print( + f" Request {i}: routed to version={routed_version}, result={result}" + ) + except Exception as e: + print(f" Request {i}: failed - {e}") + + print("\n--- Validation complete ---\n") + + +def run_agent_in_thread(app: Agent, port: int): + """Run an agent's serve() in a background thread.""" + import threading + + def target(): + app.serve(port=port, host="0.0.0.0") + + t = threading.Thread(target=target, daemon=True) + t.start() + return t + + +def main(): + versions = [ + {"version": "1.0.0", "port": BASE_PORT}, + {"version": "2.0.0", "port": BASE_PORT + 1}, + ] + + print("Multi-version agent example (Python)") + print(f" Control plane: {CP_URL}") + print(f" Agent ID: {AGENT_ID}") + print( + " Versions: " + ", ".join(f"{v['version']}@:{v['port']}" for v in versions) + "\n" + ) + + # Create and start all agents in background threads + agents: List[Agent] = [] + for spec in versions: + app = create_agent(spec["version"], spec["port"]) + agents.append(app) + run_agent_in_thread(app, spec["port"]) + print(f" Started {AGENT_ID} v{spec['version']} on port {spec['port']}") + + # Give the CP a moment to process registrations + print("\n Waiting for registrations to propagate...") + time.sleep(3) + + # Validate + asyncio.run(validate_registration()) + + # Keep running so heartbeats continue + print("All agents running. Press Ctrl+C to stop.\n") + try: + signal.pause() + except (KeyboardInterrupt, AttributeError): + # AttributeError: signal.pause() not available on Windows + try: + while True: + time.sleep(1) + except KeyboardInterrupt: + pass + + print("Shutting down.") + + +if __name__ == "__main__": + main() diff --git a/examples/python_agent_nodes/permission_agent_a/README.md b/examples/python_agent_nodes/permission_agent_a/README.md new file mode 100644 index 00000000..ddad2db7 --- /dev/null +++ b/examples/python_agent_nodes/permission_agent_a/README.md @@ -0,0 +1,45 @@ +# Permission Agent A (Caller) + +Normal agent that attempts to call a protected agent (`permission-agent-b`) through the control plane. + +## What it does + +- `ping` — simple health check, no cross-agent call +- `call_payment_gateway` — calls `permission-agent-b.process_payment` via the control plane, triggering the VC authorization middleware + +## Setup + +Requires the control plane running with `authorization.enabled: true` in config. + +```bash +# Terminal 1: Control plane +cd control-plane && go run ./cmd/af dev + +# Terminal 2: Start the protected agent first +cd examples/python_agent_nodes/permission_agent_b && python main.py + +# Terminal 3: Start this agent +cd examples/python_agent_nodes/permission_agent_a && python main.py +``` + +## Testing the permission flow + +```bash +# Trigger Agent A to call Agent B (will be denied until approved) +curl -X POST http://localhost:8080/api/v1/execute/permission-agent-a.call_payment_gateway \ + -H "Content-Type: application/json" \ + -d '{"input": {"amount": 99.99, "currency": "USD"}}' + +# Check pending permissions +curl http://localhost:8080/api/v1/admin/permissions/pending + +# Approve (replace 1 with actual ID) +curl -X POST http://localhost:8080/api/v1/admin/permissions/1/approve \ + -H "Content-Type: application/json" \ + -d '{"duration_hours": 24}' + +# Retry the call (should succeed now) +curl -X POST http://localhost:8080/api/v1/execute/permission-agent-a.call_payment_gateway \ + -H "Content-Type: application/json" \ + -d '{"input": {"amount": 99.99, "currency": "USD"}}' +``` diff --git a/examples/python_agent_nodes/permission_agent_a/main.py b/examples/python_agent_nodes/permission_agent_a/main.py new file mode 100644 index 00000000..cf62d925 --- /dev/null +++ b/examples/python_agent_nodes/permission_agent_a/main.py @@ -0,0 +1,99 @@ +""" +Permission Agent A (Caller) + +An agent with tag "analytics" that demonstrates the policy engine: + - call_query_data -> calls permission-agent-b.query_data (ALLOWED by policy) + - call_query_large -> calls permission-agent-b.query_data with limit=5000 (DENIED: constraint violation) + - call_delete -> calls permission-agent-b.delete_records (DENIED: deny_functions) + +The "analytics" tag auto-approves (tag_approval_rules), so this agent starts +immediately in "active" state. + +Test flow: + 1. Start control plane with authorization enabled + 2. Start permission-agent-b -> enters pending_approval + 3. Admin approves permission-agent-b's tags + 4. Start permission-agent-a (this agent) -> auto-approved + 5. POST /api/v1/execute/permission-agent-a.call_query_data -> 200 OK + 6. POST /api/v1/execute/permission-agent-a.call_query_large -> 403 constraint + 7. POST /api/v1/execute/permission-agent-a.call_delete -> 403 denied function +""" + +from agentfield import Agent +import os + +app = Agent( + node_id="permission-agent-a", + agentfield_server=os.getenv("AGENTFIELD_URL", "http://localhost:8080"), + tags=["analytics"], + enable_did=True, + vc_enabled=True, +) + + +@app.skill() +def ping() -> dict: + """Simple health check - no cross-agent call, should always work.""" + return {"status": "ok", "agent": "permission-agent-a"} + + +@app.reasoner() +async def call_query_data(query: str = "SELECT * FROM data") -> dict: + """ + Calls permission-agent-b.query_data with a small limit. + Should succeed: analytics -> data-service, query_* is in allow_functions, + limit=100 satisfies the <= 1000 constraint. + """ + result = await app.call( + "permission-agent-b.query_data", + query=query, + limit=100, + ) + return { + "source": "permission-agent-a", + "test": "allowed_query", + "delegation_result": result, + } + + +@app.reasoner() +async def call_query_large(query: str = "SELECT * FROM big_table") -> dict: + """ + Calls permission-agent-b.query_data with limit=5000. + Should fail: limit=5000 violates the <= 1000 constraint. + """ + result = await app.call( + "permission-agent-b.query_data", + query=query, + limit=5000, + ) + return { + "source": "permission-agent-a", + "test": "constraint_violation", + "delegation_result": result, + } + + +@app.reasoner() +async def call_delete(table: str = "sensitive_records") -> dict: + """ + Calls permission-agent-b.delete_records. + Should fail: delete_* is in deny_functions for the analytics->data-service policy. + """ + result = await app.call( + "permission-agent-b.delete_records", + table=table, + ) + return { + "source": "permission-agent-a", + "test": "deny_function", + "delegation_result": result, + } + + +if __name__ == "__main__": + print("Permission Agent A (Caller)") + print("Node: permission-agent-a") + print("Tags: analytics") + print("Test reasoners: call_query_data (allow), call_query_large (constraint), call_delete (deny)") + app.run(auto_port=True) diff --git a/examples/python_agent_nodes/permission_agent_b/README.md b/examples/python_agent_nodes/permission_agent_b/README.md new file mode 100644 index 00000000..d96cc721 --- /dev/null +++ b/examples/python_agent_nodes/permission_agent_b/README.md @@ -0,0 +1,29 @@ +# Permission Agent B (Protected Target) + +Protected agent that requires VC authorization before other agents can call it. + +## Why it's protected + +Matched by **two** protection rules in `control-plane/config/agentfield.yaml`: + +1. `agent_id: permission-agent-b` — exact agent ID match +2. `tag: sensitive` — this agent is tagged `sensitive` + +## What it does + +- `process_payment` — processes a payment (amount + currency) +- `get_balance` — returns account balance + +Both skills are protected because the entire agent is protected. + +## Setup + +```bash +# Terminal 1: Control plane with authorization enabled +cd control-plane && go run ./cmd/af dev + +# Terminal 2: Start this agent +cd examples/python_agent_nodes/permission_agent_b && python main.py +``` + +Direct calls to this agent's skills through the control plane will be denied (403) unless the caller has an approved permission. diff --git a/examples/python_agent_nodes/permission_agent_b/main.py b/examples/python_agent_nodes/permission_agent_b/main.py new file mode 100644 index 00000000..1549e7d5 --- /dev/null +++ b/examples/python_agent_nodes/permission_agent_b/main.py @@ -0,0 +1,74 @@ +""" +Permission Agent B (Protected Target) + +A protected agent that demonstrates tag-based authorization with access policies. +Tags: ["sensitive", "data-service", "payments"] + +The "sensitive" tag triggers manual approval (tag_approval_rules in config), +so this agent starts in "pending_approval" state until an admin approves its tags. + +Once approved, access policies control which callers can invoke which reasoners: + - analytics callers can call query_data and get_schema (allowed by policy) + - analytics callers are denied delete_records (deny_functions in policy) + - constraint violations (e.g. limit > 1000) are rejected + +Reasoners: + - query_data(query, limit) — simulates a data query (allowed for analytics) + - delete_records(table) — simulates record deletion (denied for analytics) + - process_payment(amount, currency) — simulates payment processing +""" + +from agentfield import Agent +import os + +app = Agent( + node_id="permission-agent-b", + agentfield_server=os.getenv("AGENTFIELD_URL", "http://localhost:8080"), + tags=["sensitive", "data-service", "payments"], + enable_did=True, + vc_enabled=True, +) + + +@app.skill(tags=["data-service", "sensitive"]) +def query_data(query: str = "SELECT *", limit: int = 100) -> dict: + """Execute a data query. Protected by access policy — analytics callers allowed.""" + return { + "status": "success", + "agent": "permission-agent-b", + "query": query, + "limit": limit, + "results": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}], + "message": f"Query executed: {query} (limit={limit})", + } + + +@app.skill(tags=["data-service"]) +def delete_records(table: str = "records") -> dict: + """Delete records from a table. Denied for analytics callers by policy.""" + return { + "status": "deleted", + "agent": "permission-agent-b", + "table": table, + "message": f"Records deleted from {table}", + } + + +@app.skill(tags=["payments", "financial"]) +def process_payment(amount: float, currency: str = "USD") -> dict: + """Process a payment. Protected operation.""" + return { + "status": "processed", + "amount": amount, + "currency": currency, + "agent": "permission-agent-b", + "message": f"Payment of {amount} {currency} processed successfully", + } + + +if __name__ == "__main__": + print("Permission Agent B (Protected Target)") + print("Node: permission-agent-b") + print("Tags: sensitive, data-service, payments") + print("Reasoners: query_data, delete_records, process_payment") + app.run(auto_port=True) diff --git a/examples/ts-node-examples/multi-version/main.ts b/examples/ts-node-examples/multi-version/main.ts new file mode 100644 index 00000000..6f553d3f --- /dev/null +++ b/examples/ts-node-examples/multi-version/main.ts @@ -0,0 +1,126 @@ +/** + * Multi-Version Agent Example + * + * Demonstrates multi-version agent support using the composite primary key + * (id, version). All agents share the same nodeId but register with different + * versions, creating separate rows in the control plane. + * + * The execute endpoint transparently routes across versioned agents using + * weighted round-robin when no default (unversioned) agent exists. + * + * Usage: + * # Start control plane first, then: + * cd examples/ts-node-examples && npm run dev:multi-version + */ +import 'dotenv/config'; +import { Agent } from '@agentfield/sdk'; + +const CP_URL = process.env.AGENTFIELD_URL ?? 'http://localhost:8080'; +const AGENT_ID = 'mv-demo'; +const BASE_PORT = 9100; + +interface VersionSpec { + version: string; + port: number; +} + +const versions: VersionSpec[] = [ + { version: '1.0.0', port: BASE_PORT }, + { version: '2.0.0', port: BASE_PORT + 1 }, +]; + +function createAgent(spec: VersionSpec): Agent { + const agent = new Agent({ + nodeId: AGENT_ID, + version: spec.version, + agentFieldUrl: CP_URL, + port: spec.port, + devMode: true, + }); + + // Echo reasoner present on every version + agent.reasoner('echo', async (ctx) => ({ + agent: AGENT_ID, + version: spec.version, + echoed: ctx.input.message ?? '', + })); + + // v2 has an extra capability + if (spec.version === '2.0.0') { + agent.reasoner('v2_feature', async (ctx) => ({ + agent: AGENT_ID, + version: spec.version, + feature: 'Only available in v2', + input: ctx.input, + })); + } + + return agent; +} + +async function validateRegistration() { + console.log('\n--- Validating multi-version registration ---\n'); + + // List all nodes and check that both versions are registered + const nodesRes = await fetch(`${CP_URL}/api/v1/nodes?show_all=true`); + if (!nodesRes.ok) { + console.error(`Failed to list nodes: ${nodesRes.status} ${nodesRes.statusText}`); + return; + } + const nodesData = await nodesRes.json(); + const agentNodes = (nodesData.nodes ?? nodesData.agents ?? []).filter( + (n: any) => (n.id ?? n.node_id) === AGENT_ID + ); + console.log(`[Nodes] Found ${agentNodes.length} versions of "${AGENT_ID}":`); + for (const n of agentNodes) { + console.log(` - id=${n.id ?? n.node_id}, version=${n.version}, base_url=${n.base_url}`); + } + + // Execute against the shared ID — the CP will route via round-robin + console.log('\n[Execute] Sending requests to mv-demo.echo:'); + for (let i = 0; i < 4; i++) { + try { + const res = await fetch(`${CP_URL}/api/v1/execute/${AGENT_ID}.echo`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ input: { message: `request-${i}` } }), + }); + const routedVersion = res.headers.get('X-Routed-Version') ?? '(default)'; + const data = await res.json(); + console.log(` Request ${i}: routed to version=${routedVersion}, result=`, data.result); + } catch (err) { + console.error(` Request ${i}: failed`, err); + } + } + + console.log('\n--- Validation complete ---\n'); +} + +async function main() { + console.log(`Multi-version agent example`); + console.log(` Control plane: ${CP_URL}`); + console.log(` Agent ID: ${AGENT_ID}`); + console.log(` Versions: ${versions.map((v) => `${v.version}@:${v.port}`).join(', ')}\n`); + + // Create and start all agents + const agents = versions.map(createAgent); + + for (const agent of agents) { + await agent.serve(); + console.log(` Started ${agent.config.nodeId} v${(agent.config as any).version} on port ${agent.config.port}`); + } + + // Give the CP a moment to process registrations + await new Promise((resolve) => setTimeout(resolve, 1500)); + + // Validate + await validateRegistration(); + + // Keep running so heartbeats continue + console.log('All agents running. Press Ctrl+C to stop.\n'); +} + +main().catch((err) => { + console.error('Fatal:', err); + process.exit(1); +}); diff --git a/examples/ts-node-examples/package-lock.json b/examples/ts-node-examples/package-lock.json index bd05b010..37a2e1d0 100644 --- a/examples/ts-node-examples/package-lock.json +++ b/examples/ts-node-examples/package-lock.json @@ -22,8 +22,8 @@ }, "../../sdk/typescript": { "name": "@agentfield/sdk", - "version": "0.1.24", - "license": "MIT", + "version": "0.1.41-rc.3", + "license": "Apache-2.0", "dependencies": { "@ai-sdk/anthropic": "^2.0.53", "@ai-sdk/cohere": "^2.0.20", @@ -37,8 +37,10 @@ "axios": "^1.6.2", "dotenv": "^16.4.5", "express": "^4.18.2", + "express-rate-limit": "^8.2.1", "ws": "^8.16.0", - "zod": "^3.22.4" + "zod": "^3.22.4", + "zod-to-json-schema": "^3.25.0" }, "devDependencies": { "@types/express": "^4.17.21", diff --git a/examples/ts-node-examples/package.json b/examples/ts-node-examples/package.json index 213893cb..0d794f3b 100644 --- a/examples/ts-node-examples/package.json +++ b/examples/ts-node-examples/package.json @@ -10,7 +10,10 @@ "dev:simulation": "tsx simulation/main.ts", "dev:init-example": "tsx init-example/main.ts", "dev:serverless": "tsx serverless-hello/main.ts", - "dev:vc": "tsx verifiable-credentials/main.ts" + "dev:vc": "tsx verifiable-credentials/main.ts", + "dev:perm-a": "tsx permission-agent-a/main.ts", + "dev:perm-b": "tsx permission-agent-b/main.ts", + "dev:multi-version": "tsx multi-version/main.ts" }, "dependencies": { "@agentfield/sdk": "file:../../sdk/typescript", diff --git a/examples/ts-node-examples/permission-agent-a/main.ts b/examples/ts-node-examples/permission-agent-a/main.ts new file mode 100644 index 00000000..17fed535 --- /dev/null +++ b/examples/ts-node-examples/permission-agent-a/main.ts @@ -0,0 +1,120 @@ +/** + * Permission Agent A (Caller) — TypeScript SDK + * + * An agent with tag "analytics" that demonstrates the policy engine: + * - call_analytics -> calls ts-perm-target.analyze_data (ALLOWED by policy) + * - call_large_query -> calls ts-perm-target.analyze_data with limit=5000 (DENIED: constraint) + * - call_delete -> calls ts-perm-target.delete_records (DENIED: deny_functions) + * + * The "analytics" tag auto-approves (tag_approval_rules), so this agent starts + * immediately in "active" state. + * + * Test flow: + * 1. Start control plane with authorization enabled + * 2. Start ts-perm-target -> enters pending_approval + * 3. Admin approves ts-perm-target's tags + * 4. Start ts-perm-caller (this agent) -> auto-approved + * 5. POST /api/v1/execute/ts-perm-caller.call_analytics -> 200 OK + * 6. POST /api/v1/execute/ts-perm-caller.call_large_query -> 403 constraint + * 7. POST /api/v1/execute/ts-perm-caller.call_delete -> 403 denied function + */ + +import { Agent } from '@agentfield/sdk'; + +async function main() { + const agent = new Agent({ + nodeId: 'ts-perm-caller', + agentFieldUrl: process.env.AGENTFIELD_URL ?? 'http://localhost:8080', + port: Number(process.env.PORT ?? 8005), + version: '1.0.0', + devMode: true, + didEnabled: true, + tags: ['analytics'], + }); + + // Simple health check — no cross-agent call, should always work. + agent.reasoner('ping', async (ctx) => { + return { + status: 'ok', + agent: 'ts-perm-caller', + }; + }, { + description: 'Simple health check', + }); + + // Calls ts-perm-target.analyze_data with a small limit. + // Should succeed: analytics -> data-service, analyze_* is in allow_functions, + // limit=100 satisfies the <= 1000 constraint. + agent.reasoner('call_analytics', async (ctx) => { + const query = ctx.input.query ?? 'default analytics query'; + + const result = await agent.call('ts-perm-target.analyze_data', { + query, + limit: 100, + }); + + return { + source: 'ts-perm-caller', + test: 'allowed_query', + delegation_result: result, + }; + }, { + description: 'Calls ts-perm-target.analyze_data (allowed)', + tags: ['analytics'], + }); + + // Calls ts-perm-target.analyze_data with limit=5000. + // Should fail: limit=5000 violates the <= 1000 constraint. + agent.reasoner('call_large_query', async (ctx) => { + const query = ctx.input.query ?? 'SELECT * FROM big_table'; + + const result = await agent.call('ts-perm-target.analyze_data', { + query, + limit: 5000, + }); + + return { + source: 'ts-perm-caller', + test: 'constraint_violation', + delegation_result: result, + }; + }, { + description: 'Calls ts-perm-target.analyze_data with large limit (constraint violation)', + tags: ['analytics'], + }); + + // Calls ts-perm-target.delete_records. + // Should fail: delete_* is in deny_functions for analytics->data-service. + agent.reasoner('call_delete', async (ctx) => { + const table = ctx.input.table ?? 'sensitive_records'; + + const result = await agent.call('ts-perm-target.delete_records', { + table, + }); + + return { + source: 'ts-perm-caller', + test: 'deny_function', + delegation_result: result, + }; + }, { + description: 'Calls ts-perm-target.delete_records (denied by policy)', + tags: ['analytics'], + }); + + await agent.serve(); + + console.log(` +Permission Agent A (Caller) — TypeScript SDK +Node: ts-perm-caller +Port: ${agent.config.port} +Server: ${agent.config.agentFieldUrl} +Tags: analytics +Test reasoners: call_analytics (allow), call_large_query (constraint), call_delete (deny) + `); +} + +main().catch((err) => { + console.error('Failed to start agent:', err); + process.exit(1); +}); diff --git a/examples/ts-node-examples/permission-agent-b/main.ts b/examples/ts-node-examples/permission-agent-b/main.ts new file mode 100644 index 00000000..7402fcda --- /dev/null +++ b/examples/ts-node-examples/permission-agent-b/main.ts @@ -0,0 +1,124 @@ +/** + * Permission Agent B (Protected Target) — TypeScript SDK + * + * A protected agent with tags ["sensitive", "data-service"]. The "sensitive" + * tag triggers manual approval (tag_approval_rules in config), so this agent + * starts in "pending_approval" state until an admin approves its tags. + * + * Once approved, access policies control which callers can invoke which reasoners: + * - analytics callers can call analyze_data and get_schema (allowed by policy) + * - analytics callers are denied delete_records (deny_functions in policy) + * - constraint violations (e.g. limit > 1000) are rejected + * + * Reasoners: + * - analyze_data — simulates data analysis, generates a VC on success + * - delete_records — simulates record deletion (denied for analytics callers) + * - get_schema — returns the data schema + */ + +import { Agent } from '@agentfield/sdk'; + +async function main() { + const agent = new Agent({ + nodeId: 'ts-perm-target', + agentFieldUrl: process.env.AGENTFIELD_URL ?? 'http://localhost:8080', + port: Number(process.env.PORT ?? 8006), + version: '1.0.0', + devMode: true, + didEnabled: true, + tags: ['sensitive', 'data-service'], + }); + + // Reasoner 1: analyze_data — simulates data analysis with VC generation. + agent.reasoner('analyze_data', async (ctx) => { + const startTime = Date.now(); + const query = ctx.input.query ?? 'no query provided'; + const limit = ctx.input.limit ?? 100; + + const result = { + status: 'analyzed', + agent: 'ts-perm-target', + query, + limit, + insights: [ + { metric: 'total_records', value: 1542 }, + { metric: 'avg_processing_time_ms', value: 23.7 }, + { metric: 'error_rate', value: 0.003 }, + ], + message: `Analysis complete for query: ${query} (limit=${limit})`, + vcGenerated: false as boolean, + vcId: undefined as string | undefined, + }; + + // Generate a Verifiable Credential for this execution + try { + const credential = await ctx.did.generateCredential({ + inputData: ctx.input, + outputData: { insights: result.insights }, + status: 'succeeded', + durationMs: Date.now() - startTime, + }); + + result.vcGenerated = true; + result.vcId = credential.vcId; + console.log(`[VC] Generated credential for analyze_data: ${credential.vcId}`); + } catch (error) { + console.error('[VC] Failed to generate credential:', error); + } + + return result; + }, { + description: 'Analyze data. Protected by access policy — analytics callers allowed.', + tags: ['sensitive', 'data-service'], + }); + + // Reasoner 2: delete_records — denied for analytics callers by policy. + agent.reasoner('delete_records', async (ctx) => { + const table = ctx.input.table ?? 'records'; + + return { + status: 'deleted', + agent: 'ts-perm-target', + table, + message: `Records deleted from ${table}`, + }; + }, { + description: 'Delete records. Denied for analytics callers by policy.', + tags: ['data-service'], + }); + + // Reasoner 3: get_schema — returns the data schema. + agent.reasoner('get_schema', async (ctx) => { + return { + status: 'success', + agent: 'ts-perm-target', + schema: { + table: 'records', + columns: [ + { name: 'id', type: 'integer', primary_key: true }, + { name: 'name', type: 'text' }, + { name: 'created_at', type: 'timestamp' }, + ], + }, + }; + }, { + description: 'Get the data schema.', + tags: ['data-service'], + }); + + await agent.serve(); + + console.log(` +Permission Agent B (Protected) — TypeScript SDK +Node: ts-perm-target +Port: ${agent.config.port} +Server: ${agent.config.agentFieldUrl} +Tags: sensitive, data-service +Reasoners: analyze_data, delete_records, get_schema + `); +} + +main().catch((err) => { + console.error('Failed to start agent:', err); + process.exit(1); +}); diff --git a/sdk/go/agent/agent.go b/sdk/go/agent/agent.go index 4fd32e23..838914fc 100644 --- a/sdk/go/agent/agent.go +++ b/sdk/go/agent/agent.go @@ -15,11 +15,13 @@ import ( "os/signal" "strings" "sync" + "syscall" "time" "github.com/Agent-Field/agentfield/sdk/go/ai" "github.com/Agent-Field/agentfield/sdk/go/client" + "github.com/Agent-Field/agentfield/sdk/go/did" "github.com/Agent-Field/agentfield/sdk/go/types" ) @@ -39,6 +41,11 @@ type ExecutionContext struct { AgentNodeID string ReasonerName string StartedAt time.Time + + // DID fields — populated when DID authentication is enabled. + CallerDID string + TargetDID string + AgentNodeDID string } func init() { @@ -104,11 +111,55 @@ type Reasoner struct { Handler HandlerFunc InputSchema json.RawMessage OutputSchema json.RawMessage + Tags []string CLIEnabled bool DefaultCLI bool CLIFormatter func(context.Context, any, error) Description string + + // VCEnabled overrides the agent-level VCEnabled setting for this reasoner. + // nil = inherit agent setting, true/false = override. + VCEnabled *bool + + // RequireRealtimeValidation forces control-plane verification for this + // reasoner, skipping local verification even when enabled. + RequireRealtimeValidation bool +} + +// WithVCEnabled overrides VC generation for this specific reasoner. +func WithVCEnabled(enabled bool) ReasonerOption { + return func(r *Reasoner) { + r.VCEnabled = &enabled + } +} + +// WithReasonerTags sets tags for this reasoner (used for tag-based authorization). +func WithReasonerTags(tags ...string) ReasonerOption { + return func(r *Reasoner) { + r.Tags = tags + } +} + +// WithRequireRealtimeValidation forces control-plane verification for this +// reasoner instead of local verification, even when LocalVerification is enabled. +func WithRequireRealtimeValidation() ReasonerOption { + return func(r *Reasoner) { + r.RequireRealtimeValidation = true + } +} + +// ExecuteError is a structured error from agent-to-agent calls via the control +// plane. It preserves the HTTP status code and any structured error details +// (e.g., permission_denied response fields) so callers can inspect them. +type ExecuteError struct { + StatusCode int + Message string + ErrorDetails interface{} +} + +func (e *ExecuteError) Error() string { + return e.Message } // Config drives Agent behaviour. @@ -179,6 +230,62 @@ type Config struct { // MemoryBackend allows plugging in a custom memory storage backend. // Optional. If nil, an in-memory backend is used (data lost on restart). MemoryBackend MemoryBackend + + // DID is the agent's decentralized identifier for DID authentication. + // Optional. If set along with PrivateKeyJWK, enables DID auth on + // all control plane requests without auto-registration. + DID string + + // PrivateKeyJWK is the JWK-formatted Ed25519 private key for signing + // DID-authenticated requests. Optional. Must be set together with DID. + PrivateKeyJWK string + + // EnableDID enables automatic DID registration during Initialize(). + // The agent registers with the control plane's DID service to obtain + // a cryptographic identity (Ed25519 keys and DID). DID authentication + // is then applied to all subsequent control plane requests. + // If DID and PrivateKeyJWK are already set, registration is skipped. + // Optional. Default: false. + EnableDID bool + + // VCEnabled enables Verifiable Credential generation after each execution. + // Requires DID authentication (either EnableDID or DID/PrivateKeyJWK). + // When enabled, the agent generates a W3C Verifiable Credential for each + // reasoner execution and stores it on the control plane for audit trails. + // Optional. Default: false. + VCEnabled bool + + // Tags are metadata labels attached to the agent during registration. + // Used by the control plane for protection rules (e.g., agents tagged + // "sensitive" require permission for cross-agent calls). + // Optional. Default: nil. + Tags []string + + // InternalToken is validated on incoming requests when RequireOriginAuth + // is true. The control plane sends this token as Authorization: Bearer + // when forwarding execution requests. If empty, Token is used instead. + // Optional. Default: "" (falls back to Token). + InternalToken string + + // RequireOriginAuth when true, validates that incoming execution + // requests include an Authorization header matching InternalToken + // (or Token if InternalToken is empty). This ensures only the + // control plane can invoke reasoners, blocking direct access to the + // agent's HTTP port. /health and /discover endpoints remain open. + // Optional. Default: false. + RequireOriginAuth bool + + // LocalVerification enables decentralized verification of incoming + // requests using cached policies, revocations, and the admin's public key. + // When enabled, the agent verifies DID signatures locally without + // hitting the control plane for every call. + // Optional. Default: false. + LocalVerification bool + + // VerificationRefreshInterval controls how often the local verifier + // refreshes its caches from the control plane. + // Optional. Default: 5 minutes. + VerificationRefreshInterval time.Duration } // CLIConfig controls CLI behaviour and presentation. @@ -202,6 +309,14 @@ type Agent struct { aiClient *ai.Client // AI/LLM client memory *Memory // Memory system for state management + // DID/VC subsystem + didManager *did.Manager + vcGenerator *did.VCGenerator + + // Local verification (decentralized mode) + localVerifier *LocalVerifier + realtimeValidationFunctions map[string]struct{} + serverMu sync.RWMutex server *http.Server @@ -260,17 +375,32 @@ func New(cfg Config) (*Agent, error) { } a := &Agent{ - cfg: cfg, - httpClient: httpClient, - reasoners: make(map[string]*Reasoner), - aiClient: aiClient, - memory: NewMemory(cfg.MemoryBackend), - stopLease: make(chan struct{}), - logger: cfg.Logger, + cfg: cfg, + httpClient: httpClient, + reasoners: make(map[string]*Reasoner), + aiClient: aiClient, + memory: NewMemory(cfg.MemoryBackend), + stopLease: make(chan struct{}), + logger: cfg.Logger, + realtimeValidationFunctions: make(map[string]struct{}), + } + + // Initialize local verifier if enabled + if cfg.LocalVerification && cfg.AgentFieldURL != "" { + refreshInterval := cfg.VerificationRefreshInterval + if refreshInterval <= 0 { + refreshInterval = 5 * time.Minute + } + a.localVerifier = NewLocalVerifier(cfg.AgentFieldURL, refreshInterval, cfg.Token) + cfg.Logger.Printf("Local verification enabled (refresh every %s)", refreshInterval) } if strings.TrimSpace(cfg.AgentFieldURL) != "" { - c, err := client.New(cfg.AgentFieldURL, client.WithHTTPClient(httpClient), client.WithBearerToken(cfg.Token)) + opts := []client.Option{client.WithHTTPClient(httpClient), client.WithBearerToken(cfg.Token)} + if cfg.DID != "" && cfg.PrivateKeyJWK != "" { + opts = append(opts, client.WithDIDAuth(cfg.DID, cfg.PrivateKeyJWK)) + } + c, err := client.New(cfg.AgentFieldURL, opts...) if err != nil { return nil, err } @@ -326,6 +456,9 @@ func (ec ExecutionContext) ChildContext(agentNodeID, reasonerName string) Execut AgentNodeID: agentNodeID, ReasonerName: reasonerName, StartedAt: time.Now(), + CallerDID: ec.CallerDID, + TargetDID: ec.TargetDID, + AgentNodeDID: ec.AgentNodeDID, } } @@ -395,6 +528,10 @@ func (a *Agent) RegisterReasoner(name string, handler HandlerFunc, opts ...Reaso } } + if meta.RequireRealtimeValidation { + a.realtimeValidationFunctions[name] = struct{}{} + } + a.reasoners[name] = meta } @@ -419,6 +556,17 @@ func (a *Agent) Initialize(ctx context.Context) error { return fmt.Errorf("register node: %w", err) } + // Auto-register DIDs if enabled and not already configured. + if a.cfg.EnableDID || a.cfg.VCEnabled { + if err := a.initializeDIDSystem(ctx); err != nil { + a.logger.Printf("warn: DID initialization failed: %v (continuing without DID)", err) + } + } + + // Mark agent as ready. The control plane protects pending_approval state + // (returns 409 if still pending), so this is safe to call unconditionally. + // For agents that went through tag approval, the admin process transitions + // them to "starting" first, so markReady correctly advances to "ready". if err := a.markReady(ctx); err != nil { a.logger.Printf("warn: initial status update failed: %v", err) } @@ -474,6 +622,8 @@ func (a *Agent) registerNode(ctx context.Context) error { ID: reasoner.Name, InputSchema: reasoner.InputSchema, OutputSchema: reasoner.OutputSchema, + Tags: reasoner.Tags, + ProposedTags: reasoner.Tags, }) } @@ -499,24 +649,66 @@ func (a *Agent) registerNode(ctx context.Context) error { "sdk": map[string]any{ "language": "go", }, + "tags": a.cfg.Tags, }, Features: map[string]any{}, DeploymentType: a.cfg.DeploymentType, } - _, err := a.client.RegisterNode(ctx, payload) + resp, err := a.client.RegisterNode(ctx, payload) if err != nil { return err } + // Handle pending approval state: poll until approved + if resp != nil && resp.Status == "pending_approval" { + a.logger.Printf("node %s registered but awaiting tag approval (pending tags: %v)", a.cfg.NodeID, resp.PendingTags) + if err := a.waitForApproval(ctx); err != nil { + return fmt.Errorf("tag approval wait failed: %w", err) + } + a.logger.Printf("node %s tag approval granted", a.cfg.NodeID) + return nil + } + a.logger.Printf("node %s registered with AgentField", a.cfg.NodeID) return nil } +func (a *Agent) waitForApproval(ctx context.Context) error { + const approvalTimeout = 5 * time.Minute + ctx, cancel := context.WithTimeout(ctx, approvalTimeout) + defer cancel() + + ticker := time.NewTicker(5 * time.Second) + defer ticker.Stop() + + for { + select { + case <-ctx.Done(): + if ctx.Err() == context.DeadlineExceeded { + return fmt.Errorf("tag approval timed out after %s", approvalTimeout) + } + return ctx.Err() + case <-ticker.C: + node, err := a.client.GetNode(ctx, a.cfg.NodeID) + if err != nil { + a.logger.Printf("polling for approval status failed: %v", err) + continue + } + status, _ := node["lifecycle_status"].(string) + if status != "" && status != "pending_approval" { + return nil + } + a.logger.Printf("node %s still pending approval...", a.cfg.NodeID) + } + } +} + func (a *Agent) markReady(ctx context.Context) error { score := 100 _, err := a.client.UpdateStatus(ctx, a.cfg.NodeID, types.NodeStatusUpdate{ Phase: "ready", + Version: a.cfg.Version, HealthScore: &score, }) return err @@ -616,11 +808,182 @@ func (a *Agent) handler() http.Handler { mux.HandleFunc("/execute", a.handleExecute) mux.HandleFunc("/execute/", a.handleExecute) mux.HandleFunc("/reasoners/", a.handleReasoner) - a.router = mux + + var handler http.Handler = mux + + // Apply local verification middleware if enabled + if a.localVerifier != nil { + handler = a.localVerificationMiddleware(handler) + } + + originToken := a.cfg.InternalToken + if originToken == "" { + originToken = a.cfg.Token + } + if a.cfg.RequireOriginAuth && originToken != "" { + a.router = a.originAuthMiddleware(handler, originToken) + } else { + a.router = handler + } }) return a.router } +// originAuthMiddleware validates that incoming requests to execute/reasoner +// endpoints include an Authorization header matching the expected token. +// Health and discovery endpoints are exempt. +func (a *Agent) originAuthMiddleware(next http.Handler, token string) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + path := r.URL.Path + if path == "/health" || path == "/discover" { + next.ServeHTTP(w, r) + return + } + + expected := "Bearer " + token + if r.Header.Get("Authorization") != expected { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusUnauthorized) + w.Write([]byte(`{"error":"unauthorized","message":"valid Authorization header required"}`)) + return + } + + next.ServeHTTP(w, r) + }) +} + +// localVerificationMiddleware verifies incoming DID signatures locally +// using cached admin public key and checks revocation lists. +func (a *Agent) localVerificationMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + path := r.URL.Path + + // Only verify execution endpoints + if path == "/health" || path == "/discover" { + next.ServeHTTP(w, r) + return + } + + // Extract function name to check realtime validation requirement + funcName := "" + if strings.HasPrefix(path, "/execute/") { + funcName = strings.TrimPrefix(path, "/execute/") + } else if strings.HasPrefix(path, "/reasoners/") { + funcName = strings.TrimPrefix(path, "/reasoners/") + } + funcName = strings.TrimSuffix(funcName, "/") + + // Skip local verification for realtime-validated functions + if _, skip := a.realtimeValidationFunctions[funcName]; skip { + next.ServeHTTP(w, r) + return + } + + // Refresh cache if stale — block until refresh completes so that + // registration and revocation checks use up-to-date data. + if a.localVerifier.NeedsRefresh() { + if err := a.localVerifier.Refresh(); err != nil { + a.logger.Printf("warn: local verification cache refresh failed: %v", err) + } + } + + // Allow trusted control-plane requests to bypass DID verification. + // The control plane sends Authorization: Bearer when + // forwarding execution requests on behalf of callers. + internalToken := a.cfg.InternalToken + if internalToken == "" { + internalToken = a.cfg.Token + } + if internalToken != "" { + if r.Header.Get("Authorization") == "Bearer "+internalToken { + next.ServeHTTP(w, r) + return + } + } + + // Extract DID auth headers + callerDID := r.Header.Get("X-Caller-DID") + signature := r.Header.Get("X-DID-Signature") + timestamp := r.Header.Get("X-DID-Timestamp") + nonce := r.Header.Get("X-DID-Nonce") + + // Require DID authentication — fail closed when no caller DID provided. + if callerDID == "" { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusUnauthorized) + json.NewEncoder(w).Encode(map[string]string{ + "error": "did_auth_required", + "message": "DID authentication required", + }) + return + } + + // Require signature when caller DID is present. + if signature == "" { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusUnauthorized) + json.NewEncoder(w).Encode(map[string]string{ + "error": "signature_required", + "message": "DID signature required", + }) + return + } + + // Check revocation + if a.localVerifier.CheckRevocation(callerDID) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusForbidden) + json.NewEncoder(w).Encode(map[string]string{ + "error": "did_revoked", + "message": "Caller DID " + callerDID + " has been revoked", + }) + return + } + + // Check registration — reject DIDs not registered with the control plane + if !a.localVerifier.CheckRegistration(callerDID) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusForbidden) + json.NewEncoder(w).Encode(map[string]string{ + "error": "did_not_registered", + "message": "Caller DID " + callerDID + " is not registered with the control plane", + }) + return + } + + // Verify signature — need to read and buffer the body + body, err := io.ReadAll(r.Body) + if err != nil { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusBadRequest) + w.Write([]byte(`{"error":"body_read_error","message":"Failed to read request body"}`)) + return + } + // Restore body for downstream handlers + r.Body = io.NopCloser(bytes.NewReader(body)) + + if !a.localVerifier.VerifySignature(callerDID, signature, timestamp, body, nonce) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusUnauthorized) + w.Write([]byte(`{"error":"signature_invalid","message":"DID signature verification failed"}`)) + return + } + + // Evaluate access policies after successful signature verification. + if !a.localVerifier.EvaluatePolicy(nil, a.cfg.Tags, funcName, nil) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusForbidden) + json.NewEncoder(w).Encode(map[string]string{ + "error": "policy_denied", + "message": "Access denied by policy", + }) + return + } + + next.ServeHTTP(w, r) + }) +} + func (a *Agent) healthHandler(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, map[string]any{"status": "ok"}) } @@ -697,15 +1060,38 @@ func (a *Agent) handleExecute(w http.ResponseWriter, r *http.Request) { input := extractInputFromServerless(payload) execCtx := a.buildExecutionContextFromServerless(r, payload, reasonerName) + a.fillDIDContext(&execCtx) ctx := contextWithExecution(r.Context(), execCtx) + start := time.Now() result, err := reasoner.Handler(ctx, input) + durationMS := time.Since(start).Milliseconds() + if err != nil { a.logger.Printf("reasoner %s failed: %v", reasonerName, err) + a.maybeGenerateVC(execCtx, input, nil, "failed", err.Error(), durationMS, reasoner) + // Propagate structured error details (e.g. from a failed inner Call) + // so the control plane can expose them to the original caller. + var execErr *ExecuteError + if errors.As(err, &execErr) { + response := map[string]any{"error": execErr.Message} + if execErr.ErrorDetails != nil { + response["error_details"] = execErr.ErrorDetails + } + // Propagate the upstream HTTP status code (e.g. 403 from permission + // middleware) so the control plane can forward it to the original caller. + statusCode := execErr.StatusCode + if statusCode < 400 { + statusCode = http.StatusInternalServerError + } + writeJSON(w, statusCode, response) + return + } writeJSON(w, http.StatusInternalServerError, map[string]any{"error": err.Error()}) return } + a.maybeGenerateVC(execCtx, input, result, "succeeded", "", durationMS, reasoner) writeJSON(w, http.StatusOK, result) } @@ -744,6 +1130,9 @@ func (a *Agent) buildExecutionContextFromServerless(r *http.Request, payload map AgentNodeID: a.cfg.NodeID, ReasonerName: reasonerName, StartedAt: time.Now(), + CallerDID: strings.TrimSpace(r.Header.Get("X-Caller-DID")), + TargetDID: strings.TrimSpace(r.Header.Get("X-Target-DID")), + AgentNodeDID: strings.TrimSpace(r.Header.Get("X-Agent-Node-DID")), } if ctxMap, ok := payload["execution_context"].(map[string]any); ok { @@ -821,6 +1210,9 @@ func (a *Agent) handleReasoner(w http.ResponseWriter, r *http.Request) { AgentNodeID: a.cfg.NodeID, ReasonerName: name, StartedAt: time.Now(), + CallerDID: r.Header.Get("X-Caller-DID"), + TargetDID: r.Header.Get("X-Target-DID"), + AgentNodeDID: r.Header.Get("X-Agent-Node-DID"), } if execCtx.WorkflowID == "" { execCtx.WorkflowID = execCtx.RunID @@ -828,6 +1220,7 @@ func (a *Agent) handleReasoner(w http.ResponseWriter, r *http.Request) { if execCtx.RootWorkflowID == "" { execCtx.RootWorkflowID = execCtx.WorkflowID } + a.fillDIDContext(&execCtx) ctx := contextWithExecution(r.Context(), execCtx) @@ -844,16 +1237,36 @@ func (a *Agent) handleReasoner(w http.ResponseWriter, r *http.Request) { return } + start := time.Now() result, err := reasoner.Handler(ctx, input) + durationMS := time.Since(start).Milliseconds() + if err != nil { a.logger.Printf("reasoner %s failed: %v", name, err) - response := map[string]any{ - "error": err.Error(), + a.maybeGenerateVC(execCtx, input, nil, "failed", err.Error(), durationMS, reasoner) + // Preserve structured downstream errors (e.g. policy denies from inner + // agent calls) so local endpoint callers receive the correct status code. + var execErr *ExecuteError + if errors.As(err, &execErr) { + response := map[string]any{"error": execErr.Message} + if execErr.ErrorDetails != nil { + response["error_details"] = execErr.ErrorDetails + } + statusCode := execErr.StatusCode + if statusCode < 400 { + statusCode = http.StatusInternalServerError + } + writeJSON(w, statusCode, response) + return } - writeJSON(w, http.StatusInternalServerError, response) + + writeJSON(w, http.StatusInternalServerError, map[string]any{ + "error": err.Error(), + }) return } + a.maybeGenerateVC(execCtx, input, result, "succeeded", "", durationMS, reasoner) writeJSON(w, http.StatusOK, result) } @@ -864,15 +1277,17 @@ func (a *Agent) executeReasonerAsync(reasoner *Reasoner, input map[string]any, e defer func() { if rec := recover(); rec != nil { errMsg := fmt.Sprintf("panic: %v", rec) + durationMS := time.Since(start).Milliseconds() payload := map[string]any{ "status": "failed", "error": errMsg, "execution_id": execCtx.ExecutionID, "run_id": execCtx.RunID, "completed_at": time.Now().UTC().Format(time.RFC3339), - "duration_ms": time.Since(start).Milliseconds(), + "duration_ms": durationMS, "reasoner_name": reasoner.Name, } + a.maybeGenerateVC(execCtx, input, nil, "failed", errMsg, durationMS, reasoner) if err := a.sendExecutionStatus(execCtx.ExecutionID, payload); err != nil { a.logger.Printf("failed to send panic status: %v", err) } @@ -880,20 +1295,23 @@ func (a *Agent) executeReasonerAsync(reasoner *Reasoner, input map[string]any, e }() result, err := reasoner.Handler(ctx, input) + durationMS := time.Since(start).Milliseconds() payload := map[string]any{ "execution_id": execCtx.ExecutionID, "run_id": execCtx.RunID, "completed_at": time.Now().UTC().Format(time.RFC3339), - "duration_ms": time.Since(start).Milliseconds(), + "duration_ms": durationMS, "reasoner_name": reasoner.Name, } if err != nil { payload["status"] = "failed" payload["error"] = err.Error() + a.maybeGenerateVC(execCtx, input, nil, "failed", err.Error(), durationMS, reasoner) } else { payload["status"] = "succeeded" payload["result"] = result + a.maybeGenerateVC(execCtx, input, result, "succeeded", "", durationMS, reasoner) } if err := a.sendExecutionStatus(execCtx.ExecutionID, payload); err != nil { @@ -925,6 +1343,16 @@ func (a *Agent) postExecutionStatus(ctx context.Context, callbackURL string, pay } req.Header.Set("Content-Type", "application/json") + // Include API auth headers (Bearer token / API key) + if a.cfg.Token != "" { + req.Header.Set("Authorization", "Bearer "+a.cfg.Token) + } + + // Sign request with DID auth headers if configured + if a.client != nil { + a.client.SignHTTPRequest(req, payload) + } + resp, err := a.httpClient.Do(req) if err != nil { lastErr = err @@ -987,10 +1415,25 @@ func (a *Agent) Call(ctx context.Context, target string, input map[string]any) ( if execCtx.ActorID != "" { req.Header.Set("X-Actor-ID", execCtx.ActorID) } + // DID metadata headers for execution context propagation. + if a.didManager != nil && a.didManager.IsRegistered() { + req.Header.Set("X-Agent-Node-DID", a.didManager.GetAgentDID()) + } + if execCtx.AgentNodeDID != "" { + req.Header.Set("X-Agent-Node-DID", execCtx.AgentNodeDID) + } + // Include caller agent identity for permission middleware + req.Header.Set("X-Caller-Agent-ID", a.cfg.NodeID) + if a.cfg.Token != "" { req.Header.Set("Authorization", "Bearer "+a.cfg.Token) } + // Sign request with DID auth headers if configured + if a.client != nil { + a.client.SignHTTPRequest(req, body) + } + resp, err := a.httpClient.Do(req) if err != nil { return nil, fmt.Errorf("perform execute call: %w", err) @@ -1003,7 +1446,22 @@ func (a *Agent) Call(ctx context.Context, target string, input map[string]any) ( } if resp.StatusCode != http.StatusOK { - return nil, fmt.Errorf("execute failed: %s", strings.TrimSpace(string(bodyBytes))) + // Try to parse structured error from control plane response. + var errResp struct { + Error string `json:"error"` + ErrorDetails interface{} `json:"error_details"` + } + if json.Unmarshal(bodyBytes, &errResp) == nil && errResp.Error != "" { + return nil, &ExecuteError{ + StatusCode: resp.StatusCode, + Message: errResp.Error, + ErrorDetails: errResp.ErrorDetails, + } + } + return nil, &ExecuteError{ + StatusCode: resp.StatusCode, + Message: fmt.Sprintf("execute failed (%d): %s", resp.StatusCode, strings.TrimSpace(string(bodyBytes))), + } } var execResp struct { @@ -1012,16 +1470,25 @@ func (a *Agent) Call(ctx context.Context, target string, input map[string]any) ( Status string `json:"status"` Result map[string]any `json:"result"` ErrorMessage *string `json:"error_message"` + ErrorDetails interface{} `json:"error_details"` } if err := json.Unmarshal(bodyBytes, &execResp); err != nil { return nil, fmt.Errorf("decode execute response: %w", err) } if execResp.ErrorMessage != nil && *execResp.ErrorMessage != "" { - return nil, fmt.Errorf("execute error: %s", *execResp.ErrorMessage) + return nil, &ExecuteError{ + StatusCode: resp.StatusCode, + Message: *execResp.ErrorMessage, + ErrorDetails: execResp.ErrorDetails, + } } if !strings.EqualFold(execResp.Status, "succeeded") { - return nil, fmt.Errorf("execute status %s", execResp.Status) + return nil, &ExecuteError{ + StatusCode: resp.StatusCode, + Message: fmt.Sprintf("execute status %s", execResp.Status), + ErrorDetails: execResp.ErrorDetails, + } } return execResp.Result, nil @@ -1096,6 +1563,11 @@ func (a *Agent) sendWorkflowEvent(event types.WorkflowExecutionEvent) error { req.Header.Set("Authorization", "Bearer "+a.cfg.Token) } + // Sign request with DID auth headers if configured + if a.client != nil { + a.client.SignHTTPRequest(req, body) + } + resp, err := a.httpClient.Do(req) if err != nil { return fmt.Errorf("send request: %w", err) @@ -1200,7 +1672,7 @@ func (a *Agent) startLeaseLoop() { func (a *Agent) shutdown(ctx context.Context) error { close(a.stopLease) - if _, err := a.client.Shutdown(ctx, a.cfg.NodeID, types.ShutdownRequest{Reason: "shutdown"}); err != nil { + if _, err := a.client.Shutdown(ctx, a.cfg.NodeID, types.ShutdownRequest{Reason: "shutdown", Version: a.cfg.Version}); err != nil { a.logger.Printf("failed to notify shutdown: %v", err) } @@ -1278,3 +1750,138 @@ func ExecutionContextFrom(ctx context.Context) ExecutionContext { func (a *Agent) Memory() *Memory { return a.memory } + +// DIDManager returns the agent's DID manager, or nil if DID is not enabled. +func (a *Agent) DIDManager() *did.Manager { + return a.didManager +} + +// VCGenerator returns the agent's VC generator, or nil if VC generation is not enabled. +func (a *Agent) VCGenerator() *did.VCGenerator { + return a.vcGenerator +} + +// initializeDIDSystem sets up DID registration and VC generation. +// If DID/PrivateKeyJWK are already configured, it skips auto-registration +// but still sets up the DID manager and VC generator. +func (a *Agent) initializeDIDSystem(ctx context.Context) error { + // Create DID HTTP client for DID endpoints. + didClientOpts := []did.ClientOption{did.WithHTTPClient(a.httpClient)} + if a.cfg.Token != "" { + didClientOpts = append(didClientOpts, did.WithToken(a.cfg.Token)) + } + didClient := did.NewClient(a.cfg.AgentFieldURL, didClientOpts...) + + // Create DID manager. + mgr := did.NewManager(didClient, a.logger) + + if a.cfg.DID != "" && a.cfg.PrivateKeyJWK != "" { + // Agent already has credentials — skip registration, just populate the manager. + mgr.SetIdentityFromCredentials(a.cfg.DID, a.cfg.PrivateKeyJWK) + } else { + // Auto-register with the control plane's DID service. + reasonerNames := make([]string, 0, len(a.reasoners)) + for name := range a.reasoners { + reasonerNames = append(reasonerNames, name) + } + + if err := mgr.RegisterAgent(ctx, a.cfg.NodeID, reasonerNames, nil); err != nil { + return fmt.Errorf("DID registration: %w", err) + } + + // Wire the new credentials into the HTTP client. + agentDID := mgr.GetAgentDID() + privateKey := mgr.GetAgentPrivateKeyJWK() + if agentDID != "" && privateKey != "" { + if err := a.client.SetDIDCredentials(agentDID, privateKey); err != nil { + return fmt.Errorf("set DID credentials: %w", err) + } + // Update config so Call() and other paths can see the DID. + a.cfg.DID = agentDID + a.cfg.PrivateKeyJWK = privateKey + } + } + + a.didManager = mgr + + // Wire the sign function on the DID client so VC generation requests are DID-signed. + didClient.SetSignFunc(func(body []byte) map[string]string { + if a.client == nil { + return nil + } + return a.client.SignBody(body) + }) + + // Set up VC generator if enabled and DID auth is configured. + if a.cfg.VCEnabled && a.client != nil && a.client.DIDAuthConfigured() { + gen := did.NewVCGenerator(didClient, mgr, a.logger) + gen.SetEnabled(true) + a.vcGenerator = gen + a.logger.Printf("VC generation enabled") + } + + return nil +} + +// fillDIDContext populates DID fields on an execution context from the agent's +// DID manager, if available and not already set from headers. +func (a *Agent) fillDIDContext(ec *ExecutionContext) { + if a.didManager == nil || !a.didManager.IsRegistered() { + return + } + if ec.AgentNodeDID == "" { + ec.AgentNodeDID = a.didManager.GetAgentDID() + } +} + +// maybeGenerateVC fires a background VC generation request if the agent and +// reasoner configuration allow it. +func (a *Agent) maybeGenerateVC( + execCtx ExecutionContext, + input any, + output any, + status string, + errMsg string, + durationMS int64, + reasoner *Reasoner, +) { + if !a.shouldGenerateVC(reasoner) { + return + } + + if execCtx.CallerDID == "" { + a.logger.Printf("⚠️ VC generation for %s: CallerDID is empty (anonymous caller?), control plane will use fallback DID", execCtx.ExecutionID) + } + + didExecCtx := did.ExecutionContext{ + ExecutionID: execCtx.ExecutionID, + WorkflowID: execCtx.WorkflowID, + SessionID: execCtx.SessionID, + CallerDID: execCtx.CallerDID, + TargetDID: execCtx.TargetDID, + AgentNodeDID: execCtx.AgentNodeDID, + } + + go func() { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if _, err := a.vcGenerator.GenerateExecutionVC(ctx, didExecCtx, input, output, status, errMsg, durationMS); err != nil { + a.logger.Printf("VC generation failed for %s: %v", execCtx.ExecutionID, err) + } + }() +} + +// shouldGenerateVC checks agent-level and reasoner-level VC settings. +func (a *Agent) shouldGenerateVC(reasoner *Reasoner) bool { + if a.vcGenerator == nil || !a.vcGenerator.IsEnabled() { + return false + } + if a.didManager == nil || !a.didManager.IsRegistered() { + return false + } + // Per-reasoner override takes precedence. + if reasoner != nil && reasoner.VCEnabled != nil { + return *reasoner.VCEnabled + } + return true +} diff --git a/sdk/go/agent/verification.go b/sdk/go/agent/verification.go new file mode 100644 index 00000000..9e0b0ffb --- /dev/null +++ b/sdk/go/agent/verification.go @@ -0,0 +1,464 @@ +package agent + +import ( + "crypto/ed25519" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "fmt" + "io" + "math" + "net/http" + "sort" + "strconv" + "strings" + "sync" + "time" +) + +// LocalVerifier verifies incoming requests locally using cached policies, +// revocation lists, registered DIDs, and the admin's Ed25519 public key. +// Periodically refreshes caches from the control plane. +type LocalVerifier struct { + agentFieldURL string + refreshInterval time.Duration + timestampWindow int64 + apiKey string + + mu sync.RWMutex + policies []PolicyEntry + revokedDIDs map[string]struct{} + registeredDIDs map[string]struct{} + adminPublicKey ed25519.PublicKey + issuerDID string + lastRefresh time.Time + initialized bool +} + +// PolicyEntry represents a cached access policy for local evaluation. +type PolicyEntry struct { + Name string `json:"name"` + CallerTags []string `json:"caller_tags"` + TargetTags []string `json:"target_tags"` + AllowFunctions []string `json:"allow_functions"` + DenyFunctions []string `json:"deny_functions"` + Constraints map[string]ConstraintEntry `json:"constraints"` + Action string `json:"action"` + Priority int `json:"priority"` + Enabled *bool `json:"enabled"` +} + +// ConstraintEntry represents a parameter constraint in a policy. +type ConstraintEntry struct { + Operator string `json:"operator"` + Value float64 `json:"value"` +} + +// NewLocalVerifier creates a new local verifier. +func NewLocalVerifier(agentFieldURL string, refreshInterval time.Duration, apiKey string) *LocalVerifier { + return &LocalVerifier{ + agentFieldURL: strings.TrimRight(agentFieldURL, "/"), + refreshInterval: refreshInterval, + timestampWindow: 300, + apiKey: apiKey, + revokedDIDs: make(map[string]struct{}), + registeredDIDs: make(map[string]struct{}), + } +} + +// Refresh fetches policies, revocations, registered DIDs, and admin public key from the control plane. +func (v *LocalVerifier) Refresh() error { + client := &http.Client{Timeout: 10 * time.Second} + + // Fetch policies + policies, err := v.fetchPolicies(client) + if err != nil { + return fmt.Errorf("fetch policies: %w", err) + } + + // Fetch revocations + revoked, err := v.fetchRevocations(client) + if err != nil { + return fmt.Errorf("fetch revocations: %w", err) + } + + // Fetch registered DIDs + registered, err := v.fetchRegisteredDIDs(client) + if err != nil { + return fmt.Errorf("fetch registered DIDs: %w", err) + } + + // Fetch admin public key + pubKey, issuerDID, err := v.fetchAdminPublicKey(client) + if err != nil { + return fmt.Errorf("fetch admin public key: %w", err) + } + + v.mu.Lock() + defer v.mu.Unlock() + v.policies = policies + v.revokedDIDs = revoked + v.registeredDIDs = registered + v.adminPublicKey = pubKey + v.issuerDID = issuerDID + v.lastRefresh = time.Now() + v.initialized = true + return nil +} + +// NeedsRefresh returns true if the cache is stale. +func (v *LocalVerifier) NeedsRefresh() bool { + v.mu.RLock() + defer v.mu.RUnlock() + return time.Since(v.lastRefresh) > v.refreshInterval +} + +// CheckRevocation returns true if the DID is revoked. +func (v *LocalVerifier) CheckRevocation(callerDID string) bool { + v.mu.RLock() + defer v.mu.RUnlock() + _, revoked := v.revokedDIDs[callerDID] + return revoked +} + +// CheckRegistration returns true if the caller DID is registered with the control plane. +// When the cache is empty (not yet loaded), returns true to avoid blocking requests +// before the first refresh completes. +func (v *LocalVerifier) CheckRegistration(callerDID string) bool { + v.mu.RLock() + defer v.mu.RUnlock() + if len(v.registeredDIDs) == 0 { + return true // Cache not populated yet — allow + } + _, registered := v.registeredDIDs[callerDID] + return registered +} + +// resolvePublicKey resolves the public key bytes from a DID. +// For did:key, the public key is self-contained in the identifier: +// +// did:key:z +// +// For other DID methods, falls back to the admin public key. +func (v *LocalVerifier) resolvePublicKey(callerDID string) ed25519.PublicKey { + if strings.HasPrefix(callerDID, "did:key:z") { + encoded := callerDID[len("did:key:z"):] + decoded, err := base64.RawURLEncoding.DecodeString(encoded) + if err != nil { + return nil + } + // Verify Ed25519 multicodec prefix: 0xed, 0x01 + if len(decoded) >= 34 && decoded[0] == 0xed && decoded[1] == 0x01 { + return ed25519.PublicKey(decoded[2:34]) + } + return nil + } + + // Fallback: use admin public key for non-did:key methods + v.mu.RLock() + defer v.mu.RUnlock() + return v.adminPublicKey +} + +// VerifySignature verifies an Ed25519 DID signature on an incoming request. +// Resolves the caller's public key from their DID (did:key embeds the key +// directly; other methods fall back to the admin public key). +func (v *LocalVerifier) VerifySignature(callerDID, signatureB64, timestamp string, body []byte, nonce string) bool { + // Validate timestamp window + ts, err := strconv.ParseInt(timestamp, 10, 64) + if err != nil { + return false + } + now := time.Now().Unix() + if abs64(now-ts) > v.timestampWindow { + return false + } + + // Resolve public key from the caller's DID + pubKey := v.resolvePublicKey(callerDID) + if len(pubKey) == 0 { + return false + } + + // Decode signature + sigBytes, err := base64.StdEncoding.DecodeString(signatureB64) + if err != nil { + return false + } + + // Reconstruct the signed payload: "{timestamp}[:{nonce}]:{sha256(body)}" + // Must match the format used by SDK signing (DIDAuthenticator) + bodyHash := sha256.Sum256(body) + var payload string + if nonce != "" { + payload = fmt.Sprintf("%s:%s:%x", timestamp, nonce, bodyHash) + } else { + payload = fmt.Sprintf("%s:%x", timestamp, bodyHash) + } + + return ed25519.Verify(pubKey, []byte(payload), sigBytes) +} + +func (v *LocalVerifier) doRequest(client *http.Client, path string) (*http.Response, error) { + req, err := http.NewRequest(http.MethodGet, v.agentFieldURL+path, nil) + if err != nil { + return nil, err + } + if v.apiKey != "" { + req.Header.Set("X-API-Key", v.apiKey) + } + return client.Do(req) +} + +func (v *LocalVerifier) fetchPolicies(client *http.Client) ([]PolicyEntry, error) { + resp, err := v.doRequest(client, "/api/v1/policies") + if err != nil { + return nil, err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("HTTP %d", resp.StatusCode) + } + var result struct { + Policies []PolicyEntry `json:"policies"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return nil, err + } + return result.Policies, nil +} + +func (v *LocalVerifier) fetchRevocations(client *http.Client) (map[string]struct{}, error) { + resp, err := v.doRequest(client, "/api/v1/revocations") + if err != nil { + return nil, err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("HTTP %d", resp.StatusCode) + } + var result struct { + RevokedDIDs []string `json:"revoked_dids"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return nil, err + } + revoked := make(map[string]struct{}, len(result.RevokedDIDs)) + for _, d := range result.RevokedDIDs { + revoked[d] = struct{}{} + } + return revoked, nil +} + +func (v *LocalVerifier) fetchRegisteredDIDs(client *http.Client) (map[string]struct{}, error) { + resp, err := v.doRequest(client, "/api/v1/registered-dids") + if err != nil { + return nil, err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("HTTP %d", resp.StatusCode) + } + var result struct { + RegisteredDIDs []string `json:"registered_dids"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return nil, err + } + registered := make(map[string]struct{}, len(result.RegisteredDIDs)) + for _, d := range result.RegisteredDIDs { + registered[d] = struct{}{} + } + return registered, nil +} + +func (v *LocalVerifier) fetchAdminPublicKey(client *http.Client) (ed25519.PublicKey, string, error) { + resp, err := v.doRequest(client, "/api/v1/admin/public-key") + if err != nil { + return nil, "", err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + body, _ := io.ReadAll(resp.Body) + return nil, "", fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body)) + } + var result struct { + IssuerDID string `json:"issuer_did"` + PublicKeyJWK map[string]interface{} `json:"public_key_jwk"` + } + if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { + return nil, "", err + } + + // Parse Ed25519 public key from JWK + xValue, ok := result.PublicKeyJWK["x"].(string) + if !ok { + return nil, "", fmt.Errorf("missing 'x' in public key JWK") + } + pubKeyBytes, err := base64.RawURLEncoding.DecodeString(xValue) + if err != nil { + return nil, "", fmt.Errorf("decode public key: %w", err) + } + if len(pubKeyBytes) != ed25519.PublicKeySize { + return nil, "", fmt.Errorf("invalid public key size: %d", len(pubKeyBytes)) + } + return ed25519.PublicKey(pubKeyBytes), result.IssuerDID, nil +} + +func abs64(x int64) int64 { + if x < 0 { + neg := -x + if neg < 0 { + // Overflow: -math.MinInt64 overflows back to negative. + return math.MaxInt64 + } + return neg + } + return x +} + +// EvaluatePolicy evaluates access policies locally. +func (v *LocalVerifier) EvaluatePolicy(callerTags, targetTags []string, functionName string, inputParams map[string]any) bool { + v.mu.RLock() + policies := make([]PolicyEntry, len(v.policies)) + copy(policies, v.policies) + v.mu.RUnlock() + + if len(policies) == 0 { + return false // No policies — fail closed + } + + // Sort by priority descending so highest-priority policies are evaluated first. + sort.Slice(policies, func(i, j int) bool { + return policies[i].Priority > policies[j].Priority + }) + + for _, policy := range policies { + if policy.Enabled != nil && !*policy.Enabled { + continue + } + + // Check caller tags match + if len(policy.CallerTags) > 0 && !anyTagMatch(callerTags, policy.CallerTags) { + continue + } + + // Check target tags match + if len(policy.TargetTags) > 0 && !anyTagMatch(targetTags, policy.TargetTags) { + continue + } + + // Check deny functions first + if len(policy.DenyFunctions) > 0 && functionMatches(functionName, policy.DenyFunctions) { + return false + } + + // Check allow functions + if len(policy.AllowFunctions) > 0 && !functionMatches(functionName, policy.AllowFunctions) { + continue + } + + // Check constraints + if len(policy.Constraints) > 0 && inputParams != nil { + if !evaluateConstraints(policy.Constraints, functionName, inputParams) { + return false + } + } + + action := policy.Action + if action == "" { + action = "allow" + } + return action == "allow" + } + + return true // No matching policy — allow by default +} + +func anyTagMatch(have, want []string) bool { + for _, w := range want { + for _, h := range have { + if h == w { + return true + } + } + } + return false +} + +func functionMatches(name string, patterns []string) bool { + for _, p := range patterns { + if matchWildcard(name, p) { + return true + } + } + return false +} + +func matchWildcard(name, pattern string) bool { + if pattern == "*" { + return true + } + if strings.HasSuffix(pattern, "*") { + return strings.HasPrefix(name, strings.TrimSuffix(pattern, "*")) + } + if strings.HasPrefix(pattern, "*") { + return strings.HasSuffix(name, strings.TrimPrefix(pattern, "*")) + } + return name == pattern +} + +func evaluateConstraints(constraints map[string]ConstraintEntry, functionName string, inputParams map[string]any) bool { + for paramName, constraint := range constraints { + val, ok := inputParams[paramName] + if !ok { + return false // Fail closed: constrained parameter missing from input + } + numVal, err := toFloat64(val) + if err != nil { + return false // Fail closed: cannot convert constrained parameter to numeric + } + switch constraint.Operator { + case "<=": + if numVal > constraint.Value { + return false + } + case ">=": + if numVal < constraint.Value { + return false + } + case "<": + if numVal >= constraint.Value { + return false + } + case ">": + if numVal <= constraint.Value { + return false + } + case "==": + if math.Abs(numVal-constraint.Value) > 1e-9 { + return false + } + } + } + return true +} + +func toFloat64(v any) (float64, error) { + switch val := v.(type) { + case float64: + return val, nil + case float32: + return float64(val), nil + case int: + return float64(val), nil + case int64: + return float64(val), nil + case json.Number: + return val.Float64() + case string: + return strconv.ParseFloat(val, 64) + default: + return 0, fmt.Errorf("unsupported type %T", v) + } +} diff --git a/sdk/go/client/client.go b/sdk/go/client/client.go index 6f225fbe..9ae69d96 100644 --- a/sdk/go/client/client.go +++ b/sdk/go/client/client.go @@ -6,6 +6,7 @@ import ( "encoding/json" "fmt" "io" + "log" "net/http" "net/url" "path" @@ -17,10 +18,11 @@ import ( // Client provides a thin wrapper over the AgentField control plane REST API. type Client struct { - baseURL *url.URL - httpClient *http.Client - token string - apiKey string + baseURL *url.URL + httpClient *http.Client + token string + apiKey string + didAuthenticator *DIDAuthenticator } // Option mutates Client configuration. @@ -49,6 +51,20 @@ func WithAPIKey(key string) Option { } } +// WithDIDAuth configures DID authentication for agent-to-agent calls. +// The did parameter should be the agent's DID identifier (e.g., "did:web:example.com:agents:my-agent"). +// The privateKeyJWK should be the JWK-formatted Ed25519 private key for signing. +func WithDIDAuth(did, privateKeyJWK string) Option { + return func(c *Client) { + auth, err := NewDIDAuthenticator(did, privateKeyJWK) + if err != nil { + log.Printf("WARNING: DID auth disabled due to JWK parse error: %v", err) + return + } + c.didAuthenticator = auth + } +} + // New creates a new Client instance. func New(baseURL string, opts ...Option) (*Client, error) { if baseURL == "" { @@ -74,6 +90,19 @@ func New(baseURL string, opts ...Option) (*Client, error) { return c, nil } +// SignHTTPRequest applies DID authentication headers to an existing HTTP request. +// This is useful for code paths that construct their own requests (e.g., execute calls) +// rather than going through the client's do() method. +// If DID auth is not configured, this is a no-op. +func (c *Client) SignHTTPRequest(req *http.Request, body []byte) { + if c == nil || c.didAuthenticator == nil || !c.didAuthenticator.IsConfigured() { + return + } + for key, value := range c.didAuthenticator.SignRequest(body) { + req.Header.Set(key, value) + } +} + // RegisterNode registers or updates the agent node with the control plane. func (c *Client) RegisterNode(ctx context.Context, payload types.NodeRegistrationRequest) (*types.NodeRegistrationResponse, error) { payload.LastHeartbeat = payload.LastHeartbeat.UTC() @@ -93,6 +122,16 @@ func (c *Client) RegisterNode(ctx context.Context, payload types.NodeRegistratio return &resp, nil } +// GetNode retrieves node information from the control plane. +func (c *Client) GetNode(ctx context.Context, nodeID string) (map[string]interface{}, error) { + var resp map[string]interface{} + route := fmt.Sprintf("/api/v1/nodes/%s", url.PathEscape(nodeID)) + if err := c.do(ctx, http.MethodGet, route, nil, &resp); err != nil { + return nil, err + } + return resp, nil +} + // UpdateStatus renews the node lease and optionally reports lifecycle changes. func (c *Client) UpdateStatus(ctx context.Context, nodeID string, payload types.NodeStatusUpdate) (*types.LeaseResponse, error) { var resp types.LeaseResponse @@ -139,11 +178,15 @@ func (c *Client) do(ctx context.Context, method string, endpoint string, body an } } + var bodyBytes []byte var buf io.ReadWriter = &bytes.Buffer{} if body != nil { - if err := json.NewEncoder(buf).Encode(body); err != nil { + var err error + bodyBytes, err = json.Marshal(body) + if err != nil { return fmt.Errorf("encode request: %w", err) } + buf = bytes.NewBuffer(bodyBytes) } req, err := http.NewRequestWithContext(ctx, method, u.String(), buf) @@ -163,6 +206,14 @@ func (c *Client) do(ctx context.Context, method string, endpoint string, body an req.Header.Set("X-API-Key", c.apiKey) } + // Add DID authentication headers if configured + if c.didAuthenticator != nil && c.didAuthenticator.IsConfigured() { + didHeaders := c.didAuthenticator.SignRequest(bodyBytes) + for key, value := range didHeaders { + req.Header.Set(key, value) + } + } + resp, err := c.httpClient.Do(req) if err != nil { return fmt.Errorf("perform request: %w", err) @@ -204,6 +255,40 @@ func (c *Client) legacyHeartbeat(ctx context.Context, nodeID string, payload typ }, nil } +// SetDIDCredentials configures DID authentication credentials after client creation. +// Returns an error if the credentials are invalid. +func (c *Client) SetDIDCredentials(did, privateKeyJWK string) error { + auth, err := NewDIDAuthenticator(did, privateKeyJWK) + if err != nil { + return err + } + c.didAuthenticator = auth + return nil +} + +// DIDAuthConfigured returns true if DID authentication is configured. +func (c *Client) DIDAuthConfigured() bool { + return c.didAuthenticator != nil && c.didAuthenticator.IsConfigured() +} + +// DID returns the configured DID identifier, or empty string if not configured. +func (c *Client) DID() string { + if c.didAuthenticator == nil { + return "" + } + return c.didAuthenticator.DID() +} + +// SignBody returns DID authentication headers for the given request body. +// Returns nil if DID auth is not configured. This is used by the DID client +// to sign VC generation and other authenticated requests. +func (c *Client) SignBody(body []byte) map[string]string { + if c == nil || c.didAuthenticator == nil || !c.didAuthenticator.IsConfigured() { + return nil + } + return c.didAuthenticator.SignRequest(body) +} + // APIError captures non-success responses from the AgentField API. type APIError struct { StatusCode int diff --git a/sdk/go/client/did_auth.go b/sdk/go/client/did_auth.go new file mode 100644 index 00000000..d95b84e7 --- /dev/null +++ b/sdk/go/client/did_auth.go @@ -0,0 +1,132 @@ +package client + +import ( + "crypto/ed25519" + "crypto/rand" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "fmt" + "strconv" + "time" +) + +// DID Authentication header names +const ( + HeaderCallerDID = "X-Caller-DID" + HeaderDIDSignature = "X-DID-Signature" + HeaderDIDTimestamp = "X-DID-Timestamp" + HeaderDIDNonce = "X-DID-Nonce" +) + +// DIDAuthenticator handles DID authentication for agent requests. +type DIDAuthenticator struct { + did string + privateKey ed25519.PrivateKey +} + +// NewDIDAuthenticator creates a new DID authenticator. +func NewDIDAuthenticator(did string, privateKeyJWK string) (*DIDAuthenticator, error) { + if did == "" || privateKeyJWK == "" { + return nil, nil // Return nil authenticator if credentials not provided + } + + privateKey, err := parsePrivateKeyJWK(privateKeyJWK) + if err != nil { + return nil, fmt.Errorf("failed to parse private key: %w", err) + } + + return &DIDAuthenticator{ + did: did, + privateKey: privateKey, + }, nil +} + +// IsConfigured returns true if DID authentication is configured. +func (a *DIDAuthenticator) IsConfigured() bool { + return a != nil && a.did != "" && a.privateKey != nil +} + +// DID returns the configured DID identifier. +func (a *DIDAuthenticator) DID() string { + if a == nil { + return "" + } + return a.did +} + +// SignRequest creates DID authentication headers for a request body. +func (a *DIDAuthenticator) SignRequest(body []byte) map[string]string { + if !a.IsConfigured() { + return nil + } + + // Get current timestamp + timestamp := strconv.FormatInt(time.Now().Unix(), 10) + + // Generate per-request nonce to prevent replay detection when + // multiple requests have the same body within the same second + nonceBytes := make([]byte, 16) + if _, err := rand.Read(nonceBytes); err != nil { + return nil + } + nonce := hex.EncodeToString(nonceBytes) + + // Hash the body + bodyHash := sha256.Sum256(body) + + // Create payload: "{timestamp}:{nonce}:{body_hash}" + payload := fmt.Sprintf("%s:%s:%x", timestamp, nonce, bodyHash) + + // Sign the payload + signature := ed25519.Sign(a.privateKey, []byte(payload)) + + // Encode signature as base64 + signatureB64 := base64.StdEncoding.EncodeToString(signature) + + return map[string]string{ + HeaderCallerDID: a.did, + HeaderDIDSignature: signatureB64, + HeaderDIDTimestamp: timestamp, + HeaderDIDNonce: nonce, + } +} + +// jwk represents a JSON Web Key for Ed25519. +type jwk struct { + Kty string `json:"kty"` + Crv string `json:"crv"` + D string `json:"d"` + X string `json:"x"` +} + +// parsePrivateKeyJWK parses an Ed25519 private key from JWK format. +func parsePrivateKeyJWK(jwkJSON string) (ed25519.PrivateKey, error) { + var key jwk + if err := json.Unmarshal([]byte(jwkJSON), &key); err != nil { + return nil, fmt.Errorf("invalid JWK format: %w", err) + } + + // Verify key type + if key.Kty != "OKP" || key.Crv != "Ed25519" { + return nil, fmt.Errorf("invalid key type: expected Ed25519 OKP key") + } + + if key.D == "" { + return nil, fmt.Errorf("missing 'd' (private key) in JWK") + } + + // Decode base64url-encoded private key + privateKeyBytes, err := base64.RawURLEncoding.DecodeString(key.D) + if err != nil { + return nil, fmt.Errorf("invalid private key encoding: %w", err) + } + + // Ed25519 seed is 32 bytes + if len(privateKeyBytes) != ed25519.SeedSize { + return nil, fmt.Errorf("invalid private key length: expected %d bytes, got %d", ed25519.SeedSize, len(privateKeyBytes)) + } + + return ed25519.NewKeyFromSeed(privateKeyBytes), nil +} diff --git a/sdk/go/client/did_auth_test.go b/sdk/go/client/did_auth_test.go new file mode 100644 index 00000000..bdb6b773 --- /dev/null +++ b/sdk/go/client/did_auth_test.go @@ -0,0 +1,645 @@ +package client + +import ( + "context" + "crypto/ed25519" + "crypto/rand" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// testKeyPair generates a real Ed25519 key pair and returns the +// public key, private key, and JWK JSON string for the private key. +func testKeyPair(t *testing.T) (ed25519.PublicKey, ed25519.PrivateKey, string) { + t.Helper() + pub, priv, err := ed25519.GenerateKey(rand.Reader) + require.NoError(t, err) + + seed := priv.Seed() + jwkJSON, err := json.Marshal(jwk{ + Kty: "OKP", + Crv: "Ed25519", + D: base64.RawURLEncoding.EncodeToString(seed), + X: base64.RawURLEncoding.EncodeToString(pub), + }) + require.NoError(t, err) + + return pub, priv, string(jwkJSON) +} + +// ===================================================== +// NewDIDAuthenticator Tests +// ===================================================== + +func TestDIDNewDIDAuthenticator(t *testing.T) { + pub, _, jwkStr := testKeyPair(t) + _ = pub + + tests := []struct { + name string + did string + privateKeyJWK string + wantNil bool + wantErr bool + }{ + { + name: "valid credentials", + did: "did:web:example.com:agents:test-agent", + privateKeyJWK: jwkStr, + wantNil: false, + wantErr: false, + }, + { + name: "empty DID returns nil authenticator", + did: "", + privateKeyJWK: jwkStr, + wantNil: true, + wantErr: false, + }, + { + name: "empty JWK returns nil authenticator", + did: "did:web:example.com:agents:test-agent", + privateKeyJWK: "", + wantNil: true, + wantErr: false, + }, + { + name: "both empty returns nil authenticator", + did: "", + privateKeyJWK: "", + wantNil: true, + wantErr: false, + }, + { + name: "invalid JWK JSON", + did: "did:web:example.com:agents:test-agent", + privateKeyJWK: `{not valid json`, + wantNil: false, + wantErr: true, + }, + { + name: "wrong kty in JWK", + did: "did:web:example.com:agents:test-agent", + privateKeyJWK: `{"kty":"RSA","crv":"Ed25519","d":"AAAA"}`, + wantNil: false, + wantErr: true, + }, + { + name: "wrong crv in JWK", + did: "did:web:example.com:agents:test-agent", + privateKeyJWK: `{"kty":"OKP","crv":"P-256","d":"AAAA"}`, + wantNil: false, + wantErr: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + auth, err := NewDIDAuthenticator(tt.did, tt.privateKeyJWK) + if tt.wantErr { + assert.Error(t, err) + assert.Nil(t, auth) + } else { + assert.NoError(t, err) + if tt.wantNil { + assert.Nil(t, auth) + } else { + assert.NotNil(t, auth) + assert.Equal(t, tt.did, auth.DID()) + } + } + }) + } +} + +// ===================================================== +// IsConfigured Tests +// ===================================================== + +func TestDIDIsConfigured(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + + t.Run("configured authenticator returns true", func(t *testing.T) { + auth, err := NewDIDAuthenticator("did:web:example.com:agents:test", jwkStr) + require.NoError(t, err) + require.NotNil(t, auth) + assert.True(t, auth.IsConfigured()) + }) + + t.Run("nil authenticator returns false", func(t *testing.T) { + var auth *DIDAuthenticator + assert.False(t, auth.IsConfigured()) + }) + + t.Run("nil from empty credentials returns false", func(t *testing.T) { + auth, err := NewDIDAuthenticator("", "") + assert.NoError(t, err) + assert.Nil(t, auth) + // Calling IsConfigured on nil should be safe and return false + assert.False(t, auth.IsConfigured()) + }) +} + +// ===================================================== +// DID() accessor Tests +// ===================================================== + +func TestDIDAccessor(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + + t.Run("returns DID when configured", func(t *testing.T) { + auth, err := NewDIDAuthenticator("did:web:example.com:agents:my-agent", jwkStr) + require.NoError(t, err) + assert.Equal(t, "did:web:example.com:agents:my-agent", auth.DID()) + }) + + t.Run("returns empty on nil authenticator", func(t *testing.T) { + var auth *DIDAuthenticator + assert.Equal(t, "", auth.DID()) + }) +} + +// ===================================================== +// SignRequest Tests +// ===================================================== + +func TestDIDSignRequest(t *testing.T) { + pub, _, jwkStr := testKeyPair(t) + testDID := "did:web:example.com:agents:signer" + + t.Run("produces correct headers", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + body := []byte(`{"action":"test"}`) + headers := auth.SignRequest(body) + + require.NotNil(t, headers) + assert.Equal(t, testDID, headers[HeaderCallerDID]) + assert.NotEmpty(t, headers[HeaderDIDSignature]) + assert.NotEmpty(t, headers[HeaderDIDTimestamp]) + assert.NotEmpty(t, headers[HeaderDIDNonce]) + + // Verify exactly four headers are returned + assert.Len(t, headers, 4) + }) + + t.Run("timestamp is a valid unix timestamp", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + before := time.Now().Unix() + headers := auth.SignRequest([]byte("test")) + after := time.Now().Unix() + + ts, err := strconv.ParseInt(headers[HeaderDIDTimestamp], 10, 64) + require.NoError(t, err) + assert.GreaterOrEqual(t, ts, before) + assert.LessOrEqual(t, ts, after) + }) + + t.Run("signature is valid Ed25519 signature", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + body := []byte(`{"data":"hello world"}`) + headers := auth.SignRequest(body) + + // Decode signature + sigBytes, err := base64.StdEncoding.DecodeString(headers[HeaderDIDSignature]) + require.NoError(t, err) + assert.Len(t, sigBytes, ed25519.SignatureSize) + + // Reconstruct the payload: "{timestamp}:{nonce}:{sha256_hex_hash}" + bodyHash := sha256.Sum256(body) + payload := fmt.Sprintf("%s:%s:%x", headers[HeaderDIDTimestamp], headers[HeaderDIDNonce], bodyHash) + + // Verify with the public key + assert.True(t, ed25519.Verify(pub, []byte(payload), sigBytes), + "Ed25519 signature verification failed") + }) + + t.Run("payload format is timestamp:nonce:sha256hex", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + body := []byte("specific body content") + headers := auth.SignRequest(body) + + // Manually compute expected hash + expectedHash := sha256.Sum256(body) + expectedPayload := fmt.Sprintf("%s:%s:%x", headers[HeaderDIDTimestamp], headers[HeaderDIDNonce], expectedHash) + + // Decode signature and verify it was signed over the expected payload + sigBytes, err := base64.StdEncoding.DecodeString(headers[HeaderDIDSignature]) + require.NoError(t, err) + assert.True(t, ed25519.Verify(pub, []byte(expectedPayload), sigBytes)) + }) + + t.Run("different bodies produce different signatures", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + headers1 := auth.SignRequest([]byte("body one")) + headers2 := auth.SignRequest([]byte("body two")) + + assert.NotEqual(t, headers1[HeaderDIDSignature], headers2[HeaderDIDSignature]) + }) + + t.Run("same body produces different signatures via nonce", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + body := []byte(`{"same":"body"}`) + headers1 := auth.SignRequest(body) + headers2 := auth.SignRequest(body) + + // Nonces must differ + assert.NotEqual(t, headers1[HeaderDIDNonce], headers2[HeaderDIDNonce]) + // Signatures must differ (even with same body and potentially same timestamp) + assert.NotEqual(t, headers1[HeaderDIDSignature], headers2[HeaderDIDSignature]) + }) + + t.Run("empty body is signed correctly", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + headers := auth.SignRequest([]byte{}) + require.NotNil(t, headers) + + sigBytes, err := base64.StdEncoding.DecodeString(headers[HeaderDIDSignature]) + require.NoError(t, err) + + bodyHash := sha256.Sum256([]byte{}) + payload := fmt.Sprintf("%s:%s:%x", headers[HeaderDIDTimestamp], headers[HeaderDIDNonce], bodyHash) + assert.True(t, ed25519.Verify(pub, []byte(payload), sigBytes)) + }) + + t.Run("nil body is signed correctly", func(t *testing.T) { + auth, err := NewDIDAuthenticator(testDID, jwkStr) + require.NoError(t, err) + + headers := auth.SignRequest(nil) + require.NotNil(t, headers) + + sigBytes, err := base64.StdEncoding.DecodeString(headers[HeaderDIDSignature]) + require.NoError(t, err) + + // sha256.Sum256(nil) produces the hash of zero-length input + bodyHash := sha256.Sum256(nil) + payload := fmt.Sprintf("%s:%s:%x", headers[HeaderDIDTimestamp], headers[HeaderDIDNonce], bodyHash) + assert.True(t, ed25519.Verify(pub, []byte(payload), sigBytes)) + }) + + t.Run("returns nil when not configured", func(t *testing.T) { + var auth *DIDAuthenticator + headers := auth.SignRequest([]byte("test")) + assert.Nil(t, headers) + }) +} + +// ===================================================== +// parsePrivateKeyJWK Tests +// ===================================================== + +func TestDIDParsePrivateKeyJWK(t *testing.T) { + t.Run("valid JWK", func(t *testing.T) { + pub, priv, jwkStr := testKeyPair(t) + + parsed, err := parsePrivateKeyJWK(jwkStr) + require.NoError(t, err) + require.NotNil(t, parsed) + + // Verify the parsed key matches the original + assert.Equal(t, priv.Seed(), parsed.Seed()) + assert.Equal(t, ed25519.PublicKey(pub), parsed.Public().(ed25519.PublicKey)) + + // Verify signing with parsed key produces verifiable signatures + msg := []byte("test message") + sig := ed25519.Sign(parsed, msg) + assert.True(t, ed25519.Verify(pub, msg, sig)) + }) + + t.Run("wrong kty", func(t *testing.T) { + _, _, err := ed25519.GenerateKey(rand.Reader) + require.NoError(t, err) + + jwkJSON := `{"kty":"RSA","crv":"Ed25519","d":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}` + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid key type") + }) + + t.Run("wrong crv", func(t *testing.T) { + jwkJSON := `{"kty":"OKP","crv":"X25519","d":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}` + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid key type") + }) + + t.Run("missing d field", func(t *testing.T) { + jwkJSON := `{"kty":"OKP","crv":"Ed25519","x":"AAAA"}` + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "missing 'd'") + }) + + t.Run("invalid base64 in d field", func(t *testing.T) { + jwkJSON := `{"kty":"OKP","crv":"Ed25519","d":"!!!not-valid-base64!!!"}` + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid private key encoding") + }) + + t.Run("wrong key length - too short", func(t *testing.T) { + shortKey := base64.RawURLEncoding.EncodeToString([]byte("tooshort")) + jwkJSON := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","d":"%s"}`, shortKey) + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid private key length") + }) + + t.Run("wrong key length - too long", func(t *testing.T) { + longKey := make([]byte, 64) + _, err := rand.Read(longKey) + require.NoError(t, err) + encoded := base64.RawURLEncoding.EncodeToString(longKey) + jwkJSON := fmt.Sprintf(`{"kty":"OKP","crv":"Ed25519","d":"%s"}`, encoded) + key, err := parsePrivateKeyJWK(jwkJSON) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid private key length") + }) + + t.Run("invalid JSON", func(t *testing.T) { + key, err := parsePrivateKeyJWK(`{broken json`) + assert.Error(t, err) + assert.Nil(t, key) + assert.Contains(t, err.Error(), "invalid JWK format") + }) + + t.Run("empty string", func(t *testing.T) { + key, err := parsePrivateKeyJWK("") + assert.Error(t, err) + assert.Nil(t, key) + }) +} + +// ===================================================== +// Client.SignHTTPRequest Tests +// ===================================================== + +func TestDIDSignHTTPRequest(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + testDID := "did:web:example.com:agents:http-signer" + + t.Run("applies DID headers to http.Request", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth(testDID, jwkStr)) + require.NoError(t, err) + + body := []byte(`{"key":"value"}`) + req := httptest.NewRequest(http.MethodPost, "/test", strings.NewReader(string(body))) + + c.SignHTTPRequest(req, body) + + assert.Equal(t, testDID, req.Header.Get(HeaderCallerDID)) + assert.NotEmpty(t, req.Header.Get(HeaderDIDSignature)) + assert.NotEmpty(t, req.Header.Get(HeaderDIDTimestamp)) + assert.NotEmpty(t, req.Header.Get(HeaderDIDNonce)) + }) + + t.Run("no-op when DID auth not configured", func(t *testing.T) { + c, err := New("http://localhost:8080") + require.NoError(t, err) + + body := []byte(`{"key":"value"}`) + req := httptest.NewRequest(http.MethodPost, "/test", strings.NewReader(string(body))) + + c.SignHTTPRequest(req, body) + + assert.Empty(t, req.Header.Get(HeaderCallerDID)) + assert.Empty(t, req.Header.Get(HeaderDIDSignature)) + assert.Empty(t, req.Header.Get(HeaderDIDTimestamp)) + }) + + t.Run("no-op on nil client", func(t *testing.T) { + var c *Client + req := httptest.NewRequest(http.MethodGet, "/test", nil) + + // Should not panic + c.SignHTTPRequest(req, nil) + + assert.Empty(t, req.Header.Get(HeaderCallerDID)) + }) +} + +// ===================================================== +// Client DID credential management Tests +// ===================================================== + +func TestDIDClientSetDIDCredentials(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + testDID := "did:web:example.com:agents:setter" + + t.Run("set valid credentials after creation", func(t *testing.T) { + c, err := New("http://localhost:8080") + require.NoError(t, err) + assert.False(t, c.DIDAuthConfigured()) + + err = c.SetDIDCredentials(testDID, jwkStr) + assert.NoError(t, err) + assert.True(t, c.DIDAuthConfigured()) + assert.Equal(t, testDID, c.DID()) + }) + + t.Run("set invalid credentials returns error", func(t *testing.T) { + c, err := New("http://localhost:8080") + require.NoError(t, err) + + err = c.SetDIDCredentials(testDID, `{invalid json}`) + assert.Error(t, err) + assert.False(t, c.DIDAuthConfigured()) + }) + + t.Run("set empty credentials clears auth", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth(testDID, jwkStr)) + require.NoError(t, err) + assert.True(t, c.DIDAuthConfigured()) + + err = c.SetDIDCredentials("", "") + assert.NoError(t, err) + // Empty credentials produce nil authenticator + assert.False(t, c.DIDAuthConfigured()) + }) +} + +func TestDIDClientDIDAuthConfigured(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + + t.Run("true when configured via option", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth("did:web:example.com:agents:test", jwkStr)) + require.NoError(t, err) + assert.True(t, c.DIDAuthConfigured()) + }) + + t.Run("false when not configured", func(t *testing.T) { + c, err := New("http://localhost:8080") + require.NoError(t, err) + assert.False(t, c.DIDAuthConfigured()) + }) +} + +func TestDIDClientDID(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + + t.Run("returns DID when configured", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth("did:web:example.com:agents:test", jwkStr)) + require.NoError(t, err) + assert.Equal(t, "did:web:example.com:agents:test", c.DID()) + }) + + t.Run("returns empty when not configured", func(t *testing.T) { + c, err := New("http://localhost:8080") + require.NoError(t, err) + assert.Equal(t, "", c.DID()) + }) +} + +// ===================================================== +// WithDIDAuth Option Tests +// ===================================================== + +func TestDIDWithDIDAuthOption(t *testing.T) { + _, _, jwkStr := testKeyPair(t) + + t.Run("valid DID auth option", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth("did:web:example.com:agents:test", jwkStr)) + require.NoError(t, err) + assert.True(t, c.DIDAuthConfigured()) + }) + + t.Run("invalid JWK silently disables DID auth", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth("did:web:example.com:agents:test", `{bad json}`)) + require.NoError(t, err) + // WithDIDAuth logs a warning but doesn't fail + assert.False(t, c.DIDAuthConfigured()) + }) + + t.Run("empty credentials produce no authenticator", func(t *testing.T) { + c, err := New("http://localhost:8080", WithDIDAuth("", "")) + require.NoError(t, err) + assert.False(t, c.DIDAuthConfigured()) + }) +} + +// ===================================================== +// Integration: DID headers in do() method +// ===================================================== + +func TestDIDHeadersInDoMethod(t *testing.T) { + pub, _, jwkStr := testKeyPair(t) + testDID := "did:web:example.com:agents:integration" + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Verify DID headers are present + callerDID := r.Header.Get(HeaderCallerDID) + assert.Equal(t, testDID, callerDID) + + sig := r.Header.Get(HeaderDIDSignature) + assert.NotEmpty(t, sig) + + ts := r.Header.Get(HeaderDIDTimestamp) + assert.NotEmpty(t, ts) + + nonce := r.Header.Get(HeaderDIDNonce) + assert.NotEmpty(t, nonce) + + // Verify the signature is valid + sigBytes, err := base64.StdEncoding.DecodeString(sig) + require.NoError(t, err) + + // The do() method serializes the body to JSON, so we need to read and + // reconstruct the expected hash. The body sent was {"msg":"hello"}. + bodyHash := sha256.Sum256([]byte(`{"msg":"hello"}`)) + payload := fmt.Sprintf("%s:%s:%x", ts, nonce, bodyHash) + assert.True(t, ed25519.Verify(pub, []byte(payload), sigBytes), + "server-side signature verification failed") + + w.WriteHeader(http.StatusOK) + w.Write([]byte(`{}`)) + })) + defer server.Close() + + c, err := New(server.URL, WithDIDAuth(testDID, jwkStr)) + require.NoError(t, err) + + var resp map[string]interface{} + err = c.do(nil, http.MethodPost, "/test", map[string]string{"msg": "hello"}, &resp) + // context.Background() is nil-safe in newer Go, but let's use a real context + // Actually, http.NewRequestWithContext with nil context will panic. Re-test: + assert.Error(t, err) // nil context causes error +} + +func TestDIDHeadersInDoMethodWithContext(t *testing.T) { + pub, _, jwkStr := testKeyPair(t) + testDID := "did:web:example.com:agents:integration" + + var capturedBody []byte + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Verify DID headers are present + callerDID := r.Header.Get(HeaderCallerDID) + assert.Equal(t, testDID, callerDID) + + sig := r.Header.Get(HeaderDIDSignature) + assert.NotEmpty(t, sig) + + ts := r.Header.Get(HeaderDIDTimestamp) + assert.NotEmpty(t, ts) + + nonce := r.Header.Get(HeaderDIDNonce) + assert.NotEmpty(t, nonce) + + // Decode signature + sigBytes, err := base64.StdEncoding.DecodeString(sig) + require.NoError(t, err) + + // Reconstruct payload. The body is json-marshaled by do(). + bodyHash := sha256.Sum256(capturedBody) + payload := fmt.Sprintf("%s:%s:%x", ts, nonce, bodyHash) + assert.True(t, ed25519.Verify(pub, []byte(payload), sigBytes), + "server-side signature verification failed") + + w.WriteHeader(http.StatusOK) + w.Write([]byte(`{"status":"ok"}`)) + })) + defer server.Close() + + c, err := New(server.URL, WithDIDAuth(testDID, jwkStr)) + require.NoError(t, err) + + requestBody := map[string]string{"msg": "hello"} + // Pre-compute what the do() method will marshal + capturedBody, err = json.Marshal(requestBody) + require.NoError(t, err) + + var resp map[string]interface{} + err = c.do(context.Background(), http.MethodPost, "/test", requestBody, &resp) + assert.NoError(t, err) + assert.Equal(t, "ok", resp["status"]) +} diff --git a/sdk/go/did/did_client.go b/sdk/go/did/did_client.go new file mode 100644 index 00000000..31eca325 --- /dev/null +++ b/sdk/go/did/did_client.go @@ -0,0 +1,161 @@ +package did + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strings" + "time" +) + +// SignRequestFunc returns DID authentication headers for a request body. +// It is set after DID registration, once the agent has credentials. +type SignRequestFunc func(body []byte) map[string]string + +// Client handles HTTP communication with the control plane's DID and VC endpoints. +type Client struct { + baseURL string + httpClient *http.Client + token string + signFn SignRequestFunc +} + +// ClientOption configures a Client. +type ClientOption func(*Client) + +// WithHTTPClient sets a custom HTTP client. +func WithHTTPClient(c *http.Client) ClientOption { + return func(dc *Client) { + if c != nil { + dc.httpClient = c + } + } +} + +// WithToken sets a bearer token for authenticated requests. +func WithToken(token string) ClientOption { + return func(dc *Client) { + dc.token = token + } +} + +// NewClient creates a DID client for the given control plane URL. +func NewClient(baseURL string, opts ...ClientOption) *Client { + c := &Client{ + baseURL: strings.TrimSuffix(baseURL, "/"), + httpClient: &http.Client{ + Timeout: 15 * time.Second, + }, + } + for _, opt := range opts { + opt(c) + } + return c +} + +// SetSignFunc configures DID request signing. Call this after DID registration +// once the agent has valid credentials. +func (c *Client) SetSignFunc(fn SignRequestFunc) { + c.signFn = fn +} + +// RegisterAgent registers the agent with the control plane's DID service +// and returns the identity package containing all generated DIDs and keys. +func (c *Client) RegisterAgent(ctx context.Context, req RegistrationRequest) (*RegistrationResponse, error) { + var resp RegistrationResponse + if err := c.do(ctx, http.MethodPost, "/api/v1/did/register", req, &resp); err != nil { + return nil, fmt.Errorf("DID registration failed: %w", err) + } + if !resp.Success { + msg := resp.Error + if msg == "" { + msg = "server returned success=false" + } + return nil, fmt.Errorf("DID registration failed: %s", msg) + } + return &resp, nil +} + +// GenerateExecutionVC requests the control plane to generate a Verifiable +// Credential for a completed execution. +func (c *Client) GenerateExecutionVC(ctx context.Context, req VCGenerationRequest) (*ExecutionVC, error) { + var resp ExecutionVC + if err := c.do(ctx, http.MethodPost, "/api/v1/execution/vc", req, &resp); err != nil { + return nil, fmt.Errorf("VC generation failed: %w", err) + } + return &resp, nil +} + +// ExportWorkflowVCChain retrieves the complete VC chain for a workflow, +// suitable for offline verification and auditing. +func (c *Client) ExportWorkflowVCChain(ctx context.Context, workflowID string) (*WorkflowVCChain, error) { + endpoint := fmt.Sprintf("/api/v1/did/workflow/%s/vc-chain", url.PathEscape(workflowID)) + var resp WorkflowVCChain + if err := c.do(ctx, http.MethodGet, endpoint, nil, &resp); err != nil { + return nil, fmt.Errorf("export VC chain failed: %w", err) + } + return &resp, nil +} + +func (c *Client) do(ctx context.Context, method, endpoint string, body any, out any) error { + fullURL := c.baseURL + endpoint + + var bodyBytes []byte + var bodyReader io.Reader + if body != nil { + var err error + bodyBytes, err = json.Marshal(body) + if err != nil { + return fmt.Errorf("encode request: %w", err) + } + bodyReader = bytes.NewReader(bodyBytes) + } + + req, err := http.NewRequestWithContext(ctx, method, fullURL, bodyReader) + if err != nil { + return fmt.Errorf("build request: %w", err) + } + + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + req.Header.Set("Accept", "application/json") + + if c.token != "" { + req.Header.Set("Authorization", "Bearer "+c.token) + } + + // Apply DID authentication if configured. + if c.signFn != nil && bodyBytes != nil { + for k, v := range c.signFn(bodyBytes) { + req.Header.Set(k, v) + } + } + + resp, err := c.httpClient.Do(req) + if err != nil { + return fmt.Errorf("perform request: %w", err) + } + defer resp.Body.Close() + + respBody, err := io.ReadAll(resp.Body) + if err != nil { + return fmt.Errorf("read response: %w", err) + } + + if resp.StatusCode >= 400 { + return fmt.Errorf("server returned %d: %s", resp.StatusCode, strings.TrimSpace(string(respBody))) + } + + if out != nil && len(respBody) > 0 { + if err := json.Unmarshal(respBody, out); err != nil { + return fmt.Errorf("decode response: %w", err) + } + } + + return nil +} diff --git a/sdk/go/did/did_client_test.go b/sdk/go/did/did_client_test.go new file mode 100644 index 00000000..6228b55c --- /dev/null +++ b/sdk/go/did/did_client_test.go @@ -0,0 +1,249 @@ +package did + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestNewClient(t *testing.T) { + c := NewClient("http://localhost:8080") + assert.NotNil(t, c) + assert.Equal(t, "http://localhost:8080", c.baseURL) + assert.NotNil(t, c.httpClient) +} + +func TestNewClient_TrimsTrailingSlash(t *testing.T) { + c := NewClient("http://localhost:8080/") + assert.Equal(t, "http://localhost:8080", c.baseURL) +} + +func TestClient_RegisterAgent_Success(t *testing.T) { + identityPkg := DIDIdentityPackage{ + AgentDID: DIDIdentity{ + DID: "did:web:localhost:agents:test-agent", + PrivateKeyJWK: `{"kty":"OKP","crv":"Ed25519","d":"dGVzdC1wcml2YXRlLWtleS1zZWVkMDAwMDAwMA","x":"dGVzdC1wdWJsaWMta2V5LXZhbHVl"}`, + PublicKeyJWK: `{"kty":"OKP","crv":"Ed25519","x":"dGVzdC1wdWJsaWMta2V5LXZhbHVl"}`, + ComponentType: "agent", + }, + ReasonerDIDs: map[string]DIDIdentity{ + "greet": { + DID: "did:web:localhost:agents:test-agent:reasoners:greet", + ComponentType: "reasoner", + FunctionName: "greet", + }, + }, + SkillDIDs: map[string]DIDIdentity{}, + AgentFieldServerID: "localhost:8080", + } + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/did/register", r.URL.Path) + assert.Equal(t, "POST", r.Method) + assert.Equal(t, "application/json", r.Header.Get("Content-Type")) + + var req RegistrationRequest + err := json.NewDecoder(r.Body).Decode(&req) + require.NoError(t, err) + assert.Equal(t, "test-agent", req.AgentNodeID) + assert.Len(t, req.Reasoners, 1) + assert.Equal(t, "greet", req.Reasoners[0].ID) + + resp := RegistrationResponse{ + Success: true, + IdentityPackage: identityPkg, + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + c := NewClient(server.URL) + resp, err := c.RegisterAgent(context.Background(), RegistrationRequest{ + AgentNodeID: "test-agent", + Reasoners: []FunctionDef{{ID: "greet"}}, + Skills: []FunctionDef{}, + }) + + require.NoError(t, err) + assert.True(t, resp.Success) + assert.Equal(t, "did:web:localhost:agents:test-agent", resp.IdentityPackage.AgentDID.DID) + assert.Contains(t, resp.IdentityPackage.ReasonerDIDs, "greet") +} + +func TestClient_RegisterAgent_ServerError(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusInternalServerError) + w.Write([]byte(`{"error": "internal server error"}`)) + })) + defer server.Close() + + c := NewClient(server.URL) + resp, err := c.RegisterAgent(context.Background(), RegistrationRequest{ + AgentNodeID: "test-agent", + }) + + assert.Error(t, err) + assert.Nil(t, resp) + assert.Contains(t, err.Error(), "500") +} + +func TestClient_RegisterAgent_SuccessFalse(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + resp := RegistrationResponse{ + Success: false, + Error: "agent already registered with conflicting config", + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + c := NewClient(server.URL) + resp, err := c.RegisterAgent(context.Background(), RegistrationRequest{ + AgentNodeID: "test-agent", + }) + + assert.Error(t, err) + assert.Nil(t, resp) + assert.Contains(t, err.Error(), "agent already registered") +} + +func TestClient_GenerateExecutionVC_Success(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/execution/vc", r.URL.Path) + assert.Equal(t, "POST", r.Method) + + var req VCGenerationRequest + err := json.NewDecoder(r.Body).Decode(&req) + require.NoError(t, err) + assert.Equal(t, "exec-123", req.ExecutionContext.ExecutionID) + assert.Equal(t, "succeeded", req.Status) + + vc := ExecutionVC{ + VCID: "vc-456", + ExecutionID: "exec-123", + WorkflowID: "wf-789", + IssuerDID: "did:web:localhost:agents:caller", + TargetDID: "did:web:localhost:agents:target", + Status: "completed", + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(vc) + })) + defer server.Close() + + c := NewClient(server.URL) + vc, err := c.GenerateExecutionVC(context.Background(), VCGenerationRequest{ + ExecutionContext: ExecutionContext{ + ExecutionID: "exec-123", + WorkflowID: "wf-789", + }, + Status: "succeeded", + }) + + require.NoError(t, err) + assert.Equal(t, "vc-456", vc.VCID) + assert.Equal(t, "exec-123", vc.ExecutionID) +} + +func TestClient_GenerateExecutionVC_WithDIDAuth(t *testing.T) { + var receivedDID string + var receivedSig string + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + receivedDID = r.Header.Get("X-Caller-DID") + receivedSig = r.Header.Get("X-DID-Signature") + + vc := ExecutionVC{VCID: "vc-signed"} + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(vc) + })) + defer server.Close() + + c := NewClient(server.URL) + c.SetSignFunc(func(body []byte) map[string]string { + return map[string]string{ + "X-Caller-DID": "did:web:test-agent", + "X-DID-Signature": "test-signature", + "X-DID-Timestamp": "1234567890", + } + }) + + vc, err := c.GenerateExecutionVC(context.Background(), VCGenerationRequest{ + ExecutionContext: ExecutionContext{ExecutionID: "exec-1"}, + Status: "succeeded", + }) + + require.NoError(t, err) + assert.Equal(t, "vc-signed", vc.VCID) + assert.Equal(t, "did:web:test-agent", receivedDID) + assert.Equal(t, "test-signature", receivedSig) +} + +func TestClient_ExportWorkflowVCChain_Success(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/did/workflow/wf-123/vc-chain", r.URL.Path) + assert.Equal(t, "GET", r.Method) + + chain := WorkflowVCChain{ + WorkflowID: "wf-123", + ExecutionVCs: []ExecutionVC{ + {VCID: "vc-1", ExecutionID: "exec-1"}, + {VCID: "vc-2", ExecutionID: "exec-2"}, + }, + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(chain) + })) + defer server.Close() + + c := NewClient(server.URL) + chain, err := c.ExportWorkflowVCChain(context.Background(), "wf-123") + + require.NoError(t, err) + assert.Equal(t, "wf-123", chain.WorkflowID) + assert.Len(t, chain.ExecutionVCs, 2) +} + +func TestClient_WithBearerToken(t *testing.T) { + var receivedAuth string + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + receivedAuth = r.Header.Get("Authorization") + resp := RegistrationResponse{ + Success: true, + IdentityPackage: DIDIdentityPackage{ + AgentDID: DIDIdentity{DID: "did:web:test"}, + }, + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + c := NewClient(server.URL, WithToken("my-secret-token")) + _, err := c.RegisterAgent(context.Background(), RegistrationRequest{AgentNodeID: "test"}) + + require.NoError(t, err) + assert.Equal(t, "Bearer my-secret-token", receivedAuth) +} + +func TestClient_ContextCancellation(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Never respond — client should cancel + select {} + })) + defer server.Close() + + c := NewClient(server.URL) + ctx, cancel := context.WithCancel(context.Background()) + cancel() // Cancel immediately + + _, err := c.RegisterAgent(ctx, RegistrationRequest{AgentNodeID: "test"}) + assert.Error(t, err) +} diff --git a/sdk/go/did/did_manager.go b/sdk/go/did/did_manager.go new file mode 100644 index 00000000..23952ae8 --- /dev/null +++ b/sdk/go/did/did_manager.go @@ -0,0 +1,128 @@ +package did + +import ( + "context" + "fmt" + "log" + "sync" +) + +// Manager handles DID registration with the control plane and stores +// the resulting identity package (agent DID, per-reasoner DIDs, per-skill DIDs). +type Manager struct { + client *Client + identityPkg *DIDIdentityPackage + mu sync.RWMutex + logger *log.Logger +} + +// NewManager creates a DID manager backed by the given client. +func NewManager(client *Client, logger *log.Logger) *Manager { + if logger == nil { + logger = log.Default() + } + return &Manager{ + client: client, + logger: logger, + } +} + +// RegisterAgent registers the agent and its functions with the control plane's +// DID service. On success, the identity package (containing agent DID, private +// key, and per-function DIDs) is stored locally. +func (m *Manager) RegisterAgent(ctx context.Context, nodeID string, reasonerNames, skillNames []string) error { + reasoners := make([]FunctionDef, len(reasonerNames)) + for i, name := range reasonerNames { + reasoners[i] = FunctionDef{ID: name} + } + skills := make([]FunctionDef, len(skillNames)) + for i, name := range skillNames { + skills[i] = FunctionDef{ID: name} + } + + resp, err := m.client.RegisterAgent(ctx, RegistrationRequest{ + AgentNodeID: nodeID, + Reasoners: reasoners, + Skills: skills, + }) + if err != nil { + return err + } + + m.mu.Lock() + m.identityPkg = &resp.IdentityPackage + m.mu.Unlock() + + m.logger.Printf("DID registered: %s", resp.IdentityPackage.AgentDID.DID) + return nil +} + +// IsRegistered returns true if DID registration has completed successfully. +func (m *Manager) IsRegistered() bool { + m.mu.RLock() + defer m.mu.RUnlock() + return m.identityPkg != nil && m.identityPkg.AgentDID.DID != "" +} + +// GetAgentDID returns the agent's DID, or empty string if not registered. +func (m *Manager) GetAgentDID() string { + m.mu.RLock() + defer m.mu.RUnlock() + if m.identityPkg == nil { + return "" + } + return m.identityPkg.AgentDID.DID +} + +// GetAgentPrivateKeyJWK returns the agent's private key in JWK format, +// or empty string if not registered. +func (m *Manager) GetAgentPrivateKeyJWK() string { + m.mu.RLock() + defer m.mu.RUnlock() + if m.identityPkg == nil { + return "" + } + return m.identityPkg.AgentDID.PrivateKeyJWK +} + +// GetFunctionDID resolves the DID for a specific reasoner or skill by name. +// Falls back to the agent-level DID if no function-specific DID is found. +func (m *Manager) GetFunctionDID(name string) string { + m.mu.RLock() + defer m.mu.RUnlock() + if m.identityPkg == nil { + return "" + } + if id, ok := m.identityPkg.ReasonerDIDs[name]; ok { + return id.DID + } + if id, ok := m.identityPkg.SkillDIDs[name]; ok { + return id.DID + } + return m.identityPkg.AgentDID.DID +} + +// GetIdentityPackage returns the full identity package, or nil if not registered. +func (m *Manager) GetIdentityPackage() *DIDIdentityPackage { + m.mu.RLock() + defer m.mu.RUnlock() + return m.identityPkg +} + +// SetIdentityFromCredentials initializes the manager with pre-existing DID credentials +// (for agents that already have DID/PrivateKeyJWK configured). This allows the VC +// generator and DID context propagation to work without calling RegisterAgent. +func (m *Manager) SetIdentityFromCredentials(agentDID, privateKeyJWK string) { + m.mu.Lock() + defer m.mu.Unlock() + m.identityPkg = &DIDIdentityPackage{ + AgentDID: DIDIdentity{ + DID: agentDID, + PrivateKeyJWK: privateKeyJWK, + ComponentType: "agent", + }, + ReasonerDIDs: make(map[string]DIDIdentity), + SkillDIDs: make(map[string]DIDIdentity), + } + m.logger.Printf("DID credentials set: %s", fmt.Sprintf("%.40s...", agentDID)) +} diff --git a/sdk/go/did/did_manager_test.go b/sdk/go/did/did_manager_test.go new file mode 100644 index 00000000..82b7824b --- /dev/null +++ b/sdk/go/did/did_manager_test.go @@ -0,0 +1,193 @@ +package did + +import ( + "context" + "encoding/json" + "log" + "net/http" + "net/http/httptest" + "os" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func newTestLogger() *log.Logger { + return log.New(os.Stdout, "[test] ", log.LstdFlags) +} + +func newTestIdentityPackage() DIDIdentityPackage { + return DIDIdentityPackage{ + AgentDID: DIDIdentity{ + DID: "did:web:localhost:agents:test-agent", + PrivateKeyJWK: `{"kty":"OKP","crv":"Ed25519","d":"dGVzdC1wcml2YXRlLWtleS1zZWVkMDAwMDAwMA","x":"dGVzdC1wdWJsaWMta2V5LXZhbHVl"}`, + PublicKeyJWK: `{"kty":"OKP","crv":"Ed25519","x":"dGVzdC1wdWJsaWMta2V5LXZhbHVl"}`, + DerivationPath: "m/44'/0'/0'", + ComponentType: "agent", + }, + ReasonerDIDs: map[string]DIDIdentity{ + "greet": { + DID: "did:web:localhost:agents:test-agent:reasoners:greet", + ComponentType: "reasoner", + FunctionName: "greet", + }, + "analyze": { + DID: "did:web:localhost:agents:test-agent:reasoners:analyze", + ComponentType: "reasoner", + FunctionName: "analyze", + }, + }, + SkillDIDs: map[string]DIDIdentity{ + "format": { + DID: "did:web:localhost:agents:test-agent:skills:format", + ComponentType: "skill", + FunctionName: "format", + }, + }, + AgentFieldServerID: "localhost:8080", + } +} + +func TestManager_RegisterAgent_Success(t *testing.T) { + identityPkg := newTestIdentityPackage() + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var req RegistrationRequest + json.NewDecoder(r.Body).Decode(&req) + + assert.Equal(t, "test-agent", req.AgentNodeID) + assert.Len(t, req.Reasoners, 2) + assert.Len(t, req.Skills, 0) + + resp := RegistrationResponse{ + Success: true, + IdentityPackage: identityPkg, + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + mgr := NewManager(NewClient(server.URL), newTestLogger()) + + err := mgr.RegisterAgent(context.Background(), "test-agent", []string{"greet", "analyze"}, nil) + require.NoError(t, err) + + assert.True(t, mgr.IsRegistered()) + assert.Equal(t, "did:web:localhost:agents:test-agent", mgr.GetAgentDID()) + assert.NotEmpty(t, mgr.GetAgentPrivateKeyJWK()) +} + +func TestManager_RegisterAgent_Failure(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusInternalServerError) + w.Write([]byte(`{"error": "server error"}`)) + })) + defer server.Close() + + mgr := NewManager(NewClient(server.URL), newTestLogger()) + + err := mgr.RegisterAgent(context.Background(), "test-agent", []string{"greet"}, nil) + assert.Error(t, err) + assert.False(t, mgr.IsRegistered()) + assert.Empty(t, mgr.GetAgentDID()) +} + +func TestManager_GetFunctionDID(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + resp := RegistrationResponse{ + Success: true, + IdentityPackage: newTestIdentityPackage(), + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + mgr := NewManager(NewClient(server.URL), newTestLogger()) + err := mgr.RegisterAgent(context.Background(), "test-agent", []string{"greet", "analyze"}, nil) + require.NoError(t, err) + + // Reasoner DID + assert.Equal(t, "did:web:localhost:agents:test-agent:reasoners:greet", mgr.GetFunctionDID("greet")) + assert.Equal(t, "did:web:localhost:agents:test-agent:reasoners:analyze", mgr.GetFunctionDID("analyze")) + + // Skill DID + assert.Equal(t, "did:web:localhost:agents:test-agent:skills:format", mgr.GetFunctionDID("format")) + + // Unknown function falls back to agent DID + assert.Equal(t, "did:web:localhost:agents:test-agent", mgr.GetFunctionDID("unknown")) +} + +func TestManager_IsRegistered_BeforeRegistration(t *testing.T) { + mgr := NewManager(NewClient("http://localhost:8080"), newTestLogger()) + assert.False(t, mgr.IsRegistered()) + assert.Empty(t, mgr.GetAgentDID()) + assert.Empty(t, mgr.GetAgentPrivateKeyJWK()) + assert.Empty(t, mgr.GetFunctionDID("anything")) + assert.Nil(t, mgr.GetIdentityPackage()) +} + +func TestManager_SetIdentityFromCredentials(t *testing.T) { + mgr := NewManager(NewClient("http://localhost:8080"), newTestLogger()) + + assert.False(t, mgr.IsRegistered()) + + mgr.SetIdentityFromCredentials("did:web:test", `{"kty":"OKP","crv":"Ed25519","d":"test"}`) + + assert.True(t, mgr.IsRegistered()) + assert.Equal(t, "did:web:test", mgr.GetAgentDID()) + assert.Equal(t, `{"kty":"OKP","crv":"Ed25519","d":"test"}`, mgr.GetAgentPrivateKeyJWK()) + + // Function DID falls back to agent DID when no per-function DIDs are set. + assert.Equal(t, "did:web:test", mgr.GetFunctionDID("any-reasoner")) +} + +func TestManager_GetIdentityPackage(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + resp := RegistrationResponse{ + Success: true, + IdentityPackage: newTestIdentityPackage(), + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + mgr := NewManager(NewClient(server.URL), newTestLogger()) + err := mgr.RegisterAgent(context.Background(), "test-agent", nil, nil) + require.NoError(t, err) + + pkg := mgr.GetIdentityPackage() + require.NotNil(t, pkg) + assert.Equal(t, "did:web:localhost:agents:test-agent", pkg.AgentDID.DID) + assert.Equal(t, "localhost:8080", pkg.AgentFieldServerID) + assert.Len(t, pkg.ReasonerDIDs, 2) + assert.Len(t, pkg.SkillDIDs, 1) +} + +func TestManager_RegisterAgent_WithSkills(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var req RegistrationRequest + json.NewDecoder(r.Body).Decode(&req) + + assert.Equal(t, "agent-with-skills", req.AgentNodeID) + assert.Len(t, req.Skills, 2) + assert.Equal(t, "format", req.Skills[0].ID) + assert.Equal(t, "validate", req.Skills[1].ID) + + resp := RegistrationResponse{ + Success: true, + IdentityPackage: newTestIdentityPackage(), + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + })) + defer server.Close() + + mgr := NewManager(NewClient(server.URL), newTestLogger()) + err := mgr.RegisterAgent(context.Background(), "agent-with-skills", nil, []string{"format", "validate"}) + require.NoError(t, err) + assert.True(t, mgr.IsRegistered()) +} diff --git a/sdk/go/did/types.go b/sdk/go/did/types.go new file mode 100644 index 00000000..17f18e36 --- /dev/null +++ b/sdk/go/did/types.go @@ -0,0 +1,87 @@ +// Package did provides DID (Decentralized Identifier) authentication and +// Verifiable Credential generation for AgentField Go SDK agents. +package did + +// DIDIdentity represents a single DID with associated cryptographic keys. +type DIDIdentity struct { + DID string `json:"did"` + PrivateKeyJWK string `json:"private_key_jwk,omitempty"` + PublicKeyJWK string `json:"public_key_jwk"` + DerivationPath string `json:"derivation_path"` + ComponentType string `json:"component_type"` // "agent", "reasoner", "skill" + FunctionName string `json:"function_name,omitempty"` +} + +// DIDIdentityPackage is the complete set of DIDs returned by the control plane +// after agent registration. It includes the agent-level DID and per-function DIDs. +type DIDIdentityPackage struct { + AgentDID DIDIdentity `json:"agent_did"` + ReasonerDIDs map[string]DIDIdentity `json:"reasoner_dids"` + SkillDIDs map[string]DIDIdentity `json:"skill_dids"` + AgentFieldServerID string `json:"agentfield_server_id"` +} + +// RegistrationRequest is sent to the control plane to register agent DIDs. +type RegistrationRequest struct { + AgentNodeID string `json:"agent_node_id"` + Reasoners []FunctionDef `json:"reasoners"` + Skills []FunctionDef `json:"skills"` +} + +// FunctionDef identifies a reasoner or skill during DID registration. +type FunctionDef struct { + ID string `json:"id"` +} + +// RegistrationResponse is the response from the DID registration endpoint. +type RegistrationResponse struct { + Success bool `json:"success"` + IdentityPackage DIDIdentityPackage `json:"identity_package"` + Error string `json:"error,omitempty"` +} + +// ExecutionContext carries DID-specific metadata for a single execution, +// used when generating Verifiable Credentials. +type ExecutionContext struct { + ExecutionID string `json:"execution_id"` + WorkflowID string `json:"workflow_id,omitempty"` + SessionID string `json:"session_id,omitempty"` + CallerDID string `json:"caller_did,omitempty"` + TargetDID string `json:"target_did,omitempty"` + AgentNodeDID string `json:"agent_node_did,omitempty"` + Timestamp string `json:"timestamp,omitempty"` +} + +// VCGenerationRequest is the payload for generating a Verifiable Credential. +type VCGenerationRequest struct { + ExecutionContext ExecutionContext `json:"execution_context"` + InputData string `json:"input_data"` + OutputData string `json:"output_data"` + Status string `json:"status"` + ErrorMessage string `json:"error_message,omitempty"` + DurationMS int64 `json:"duration_ms,omitempty"` +} + +// ExecutionVC represents a Verifiable Credential generated for an execution. +type ExecutionVC struct { + VCID string `json:"vc_id"` + ExecutionID string `json:"execution_id"` + WorkflowID string `json:"workflow_id"` + SessionID string `json:"session_id,omitempty"` + IssuerDID string `json:"issuer_did"` + TargetDID string `json:"target_did"` + CallerDID string `json:"caller_did,omitempty"` + VCDocument any `json:"vc_document"` + Signature string `json:"signature"` + InputHash string `json:"input_hash"` + OutputHash string `json:"output_hash"` + Status string `json:"status"` + CreatedAt string `json:"created_at"` +} + +// WorkflowVCChain is the audit trail for a workflow, containing all execution VCs. +type WorkflowVCChain struct { + WorkflowID string `json:"workflow_id"` + ExecutionVCs []ExecutionVC `json:"execution_vcs"` + WorkflowVC any `json:"workflow_vc,omitempty"` +} diff --git a/sdk/go/did/vc_generator.go b/sdk/go/did/vc_generator.go new file mode 100644 index 00000000..60e97d17 --- /dev/null +++ b/sdk/go/did/vc_generator.go @@ -0,0 +1,114 @@ +package did + +import ( + "context" + "encoding/base64" + "encoding/json" + "log" + "sync" + "time" +) + +// VCGenerator handles Verifiable Credential generation for agent executions. +// After a reasoner completes, the generator sends execution metadata to the +// control plane which creates and stores a W3C-compliant VC for the audit trail. +type VCGenerator struct { + client *Client + manager *Manager + enabled bool + mu sync.RWMutex + logger *log.Logger +} + +// NewVCGenerator creates a VC generator. Generation is disabled by default; +// call SetEnabled(true) after DID registration succeeds. +func NewVCGenerator(client *Client, manager *Manager, logger *log.Logger) *VCGenerator { + if logger == nil { + logger = log.Default() + } + return &VCGenerator{ + client: client, + manager: manager, + logger: logger, + } +} + +// SetEnabled enables or disables VC generation. +func (g *VCGenerator) SetEnabled(enabled bool) { + g.mu.Lock() + g.enabled = enabled + g.mu.Unlock() +} + +// IsEnabled returns true if VC generation is active. +func (g *VCGenerator) IsEnabled() bool { + g.mu.RLock() + defer g.mu.RUnlock() + return g.enabled +} + +// GenerateExecutionVC creates a Verifiable Credential for a completed execution. +// The input and output are serialized to JSON and base64-encoded before being +// sent to the control plane, matching the Python and TypeScript SDK behavior. +func (g *VCGenerator) GenerateExecutionVC( + ctx context.Context, + execCtx ExecutionContext, + input any, + output any, + status string, + errMsg string, + durationMS int64, +) (*ExecutionVC, error) { + if !g.IsEnabled() { + return nil, nil + } + + // Fill in agent's own DID if not already set from headers. + // CallerDID and TargetDID come from X-Caller-DID / X-Target-DID headers + // forwarded by the control plane — we must NOT overwrite them with the + // agent's own DID. + if execCtx.AgentNodeDID == "" && g.manager != nil { + execCtx.AgentNodeDID = g.manager.GetAgentDID() + } + if execCtx.Timestamp == "" { + execCtx.Timestamp = time.Now().UTC().Format(time.RFC3339) + } + + inputData := encodeData(input) + outputData := encodeData(output) + + req := VCGenerationRequest{ + ExecutionContext: execCtx, + InputData: inputData, + OutputData: outputData, + Status: status, + ErrorMessage: errMsg, + DurationMS: durationMS, + } + + vc, err := g.client.GenerateExecutionVC(ctx, req) + if err != nil { + return nil, err + } + + g.logger.Printf("generated VC %s for execution %s", vc.VCID, execCtx.ExecutionID) + return vc, nil +} + +// ExportWorkflowVCChain retrieves the complete VC chain for a workflow. +func (g *VCGenerator) ExportWorkflowVCChain(ctx context.Context, workflowID string) (*WorkflowVCChain, error) { + return g.client.ExportWorkflowVCChain(ctx, workflowID) +} + +// encodeData serializes a value to a base64-encoded JSON string, +// matching the Python and TypeScript SDK convention. +func encodeData(v any) string { + if v == nil { + return "" + } + b, err := json.Marshal(v) + if err != nil { + return "" + } + return base64.StdEncoding.EncodeToString(b) +} diff --git a/sdk/go/did/vc_generator_test.go b/sdk/go/did/vc_generator_test.go new file mode 100644 index 00000000..aeb7b5d6 --- /dev/null +++ b/sdk/go/did/vc_generator_test.go @@ -0,0 +1,258 @@ +package did + +import ( + "context" + "encoding/base64" + "encoding/json" + "log" + "net/http" + "net/http/httptest" + "os" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestVCGenerator_GenerateExecutionVC_Success(t *testing.T) { + var receivedReq VCGenerationRequest + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/execution/vc", r.URL.Path) + json.NewDecoder(r.Body).Decode(&receivedReq) + + vc := ExecutionVC{ + VCID: "vc-gen-1", + ExecutionID: "exec-100", + WorkflowID: "wf-200", + IssuerDID: "did:web:localhost:agents:caller", + TargetDID: "did:web:localhost:agents:target", + Status: "completed", + InputHash: "sha256:abc", + OutputHash: "sha256:def", + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(vc) + })) + defer server.Close() + + client := NewClient(server.URL) + logger := log.New(os.Stdout, "[test] ", log.LstdFlags) + + mgr := NewManager(client, logger) + mgr.SetIdentityFromCredentials("did:web:localhost:agents:test", "key") + + gen := NewVCGenerator(client, mgr, logger) + gen.SetEnabled(true) + + execCtx := ExecutionContext{ + ExecutionID: "exec-100", + WorkflowID: "wf-200", + SessionID: "sess-300", + } + + input := map[string]any{"query": "test"} + output := map[string]any{"result": "ok"} + + vc, err := gen.GenerateExecutionVC( + context.Background(), + execCtx, + input, + output, + "succeeded", + "", + 150, + ) + + require.NoError(t, err) + require.NotNil(t, vc) + assert.Equal(t, "vc-gen-1", vc.VCID) + assert.Equal(t, "exec-100", vc.ExecutionID) + + // Verify request was properly constructed. + assert.Equal(t, "exec-100", receivedReq.ExecutionContext.ExecutionID) + assert.Equal(t, "wf-200", receivedReq.ExecutionContext.WorkflowID) + assert.Equal(t, "succeeded", receivedReq.Status) + assert.Equal(t, int64(150), receivedReq.DurationMS) + + // AgentNodeDID should be filled from manager; CallerDID comes from + // X-Caller-DID header (not auto-filled to avoid misattribution). + assert.Equal(t, "did:web:localhost:agents:test", receivedReq.ExecutionContext.AgentNodeDID) + assert.Empty(t, receivedReq.ExecutionContext.CallerDID) + + // Input/output should be base64-encoded JSON. + assert.NotEmpty(t, receivedReq.InputData) + inputBytes, err := base64.StdEncoding.DecodeString(receivedReq.InputData) + require.NoError(t, err) + var decodedInput map[string]any + json.Unmarshal(inputBytes, &decodedInput) + assert.Equal(t, "test", decodedInput["query"]) +} + +func TestVCGenerator_Disabled(t *testing.T) { + gen := NewVCGenerator(NewClient("http://unused"), nil, newTestLogger()) + // Not enabled — should return nil, nil + vc, err := gen.GenerateExecutionVC( + context.Background(), + ExecutionContext{ExecutionID: "exec-1"}, + nil, nil, "succeeded", "", 0, + ) + assert.NoError(t, err) + assert.Nil(t, vc) +} + +func TestVCGenerator_EnableDisable(t *testing.T) { + gen := NewVCGenerator(NewClient("http://unused"), nil, newTestLogger()) + assert.False(t, gen.IsEnabled()) + + gen.SetEnabled(true) + assert.True(t, gen.IsEnabled()) + + gen.SetEnabled(false) + assert.False(t, gen.IsEnabled()) +} + +func TestVCGenerator_GenerateExecutionVC_WithError(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var req VCGenerationRequest + json.NewDecoder(r.Body).Decode(&req) + + assert.Equal(t, "failed", req.Status) + assert.Equal(t, "division by zero", req.ErrorMessage) + + vc := ExecutionVC{ + VCID: "vc-error", + Status: "failed", + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(vc) + })) + defer server.Close() + + client := NewClient(server.URL) + gen := NewVCGenerator(client, nil, newTestLogger()) + gen.SetEnabled(true) + + vc, err := gen.GenerateExecutionVC( + context.Background(), + ExecutionContext{ExecutionID: "exec-fail"}, + map[string]any{"x": 1}, + nil, + "failed", + "division by zero", + 50, + ) + + require.NoError(t, err) + assert.Equal(t, "vc-error", vc.VCID) +} + +func TestVCGenerator_GenerateExecutionVC_ServerError(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusInternalServerError) + w.Write([]byte(`{"error": "vc generation failed"}`)) + })) + defer server.Close() + + client := NewClient(server.URL) + gen := NewVCGenerator(client, nil, newTestLogger()) + gen.SetEnabled(true) + + vc, err := gen.GenerateExecutionVC( + context.Background(), + ExecutionContext{ExecutionID: "exec-1"}, + nil, nil, "succeeded", "", 0, + ) + + assert.Error(t, err) + assert.Nil(t, vc) + assert.Contains(t, err.Error(), "VC generation failed") +} + +func TestVCGenerator_ExportWorkflowVCChain(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/did/workflow/wf-export/vc-chain", r.URL.Path) + + chain := WorkflowVCChain{ + WorkflowID: "wf-export", + ExecutionVCs: []ExecutionVC{ + {VCID: "vc-1"}, + {VCID: "vc-2"}, + {VCID: "vc-3"}, + }, + } + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(chain) + })) + defer server.Close() + + client := NewClient(server.URL) + gen := NewVCGenerator(client, nil, newTestLogger()) + + chain, err := gen.ExportWorkflowVCChain(context.Background(), "wf-export") + require.NoError(t, err) + assert.Equal(t, "wf-export", chain.WorkflowID) + assert.Len(t, chain.ExecutionVCs, 3) +} + +func TestVCGenerator_NilInput(t *testing.T) { + var receivedReq VCGenerationRequest + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + json.NewDecoder(r.Body).Decode(&receivedReq) + vc := ExecutionVC{VCID: "vc-nil"} + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(vc) + })) + defer server.Close() + + client := NewClient(server.URL) + gen := NewVCGenerator(client, nil, newTestLogger()) + gen.SetEnabled(true) + + vc, err := gen.GenerateExecutionVC( + context.Background(), + ExecutionContext{ExecutionID: "exec-nil"}, + nil, nil, "succeeded", "", 0, + ) + + require.NoError(t, err) + assert.Equal(t, "vc-nil", vc.VCID) + // Nil input/output should produce empty strings. + assert.Empty(t, receivedReq.InputData) + assert.Empty(t, receivedReq.OutputData) +} + +func TestEncodeData(t *testing.T) { + tests := []struct { + name string + input any + empty bool + }{ + {"nil", nil, true}, + {"map", map[string]any{"key": "value"}, false}, + {"string", "hello", false}, + {"number", 42, false}, + {"slice", []int{1, 2, 3}, false}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := encodeData(tt.input) + if tt.empty { + assert.Empty(t, result) + return + } + + // Should be valid base64 + decoded, err := base64.StdEncoding.DecodeString(result) + require.NoError(t, err) + assert.NotEmpty(t, decoded) + + // Should be valid JSON + var parsed any + err = json.Unmarshal(decoded, &parsed) + assert.NoError(t, err) + }) + } +} diff --git a/sdk/go/types/types.go b/sdk/go/types/types.go index cf68b372..27c54781 100644 --- a/sdk/go/types/types.go +++ b/sdk/go/types/types.go @@ -10,13 +10,16 @@ type ReasonerDefinition struct { ID string `json:"id"` InputSchema json.RawMessage `json:"input_schema"` OutputSchema json.RawMessage `json:"output_schema"` + Tags []string `json:"tags,omitempty"` + ProposedTags []string `json:"proposed_tags,omitempty"` } // SkillDefinition is included for completeness. type SkillDefinition struct { - ID string `json:"id"` - InputSchema json.RawMessage `json:"input_schema"` - Tags []string `json:"tags,omitempty"` + ID string `json:"id"` + InputSchema json.RawMessage `json:"input_schema"` + Tags []string `json:"tags,omitempty"` + ProposedTags []string `json:"proposed_tags,omitempty"` } // CommunicationConfig declares supported protocols for the agent. @@ -54,11 +57,16 @@ type NodeRegistrationResponse struct { Message string `json:"message,omitempty"` Success bool `json:"success"` RegisteredAt time.Time `json:"-"` + Status string `json:"status,omitempty"` + ProposedTags []string `json:"proposed_tags,omitempty"` + PendingTags []string `json:"pending_tags,omitempty"` + AutoApprovedTags []string `json:"auto_approved_tags,omitempty"` } // NodeStatusUpdate is used for lease renewals. type NodeStatusUpdate struct { Phase string `json:"phase"` + Version string `json:"version,omitempty"` HealthScore *int `json:"health_score,omitempty"` } @@ -83,6 +91,7 @@ type ActionAckRequest struct { // ShutdownRequest notifies the control plane that the node is draining. type ShutdownRequest struct { Reason string `json:"reason,omitempty"` + Version string `json:"version,omitempty"` ExpectedRestart string `json:"expected_restart,omitempty"` } diff --git a/sdk/python/agentfield/__init__.py b/sdk/python/agentfield/__init__.py index acd7e232..b98bddcb 100644 --- a/sdk/python/agentfield/__init__.py +++ b/sdk/python/agentfield/__init__.py @@ -38,6 +38,14 @@ get_provider, register_provider, ) +from .did_auth import ( + DIDAuthenticator, + create_did_auth_headers, + sign_request, + HEADER_CALLER_DID, + HEADER_DID_SIGNATURE, + HEADER_DID_TIMESTAMP, +) from .exceptions import ( AgentFieldError, AgentFieldClientError, @@ -84,6 +92,13 @@ "OpenRouterProvider", "get_provider", "register_provider", + # DID authentication + "DIDAuthenticator", + "create_did_auth_headers", + "sign_request", + "HEADER_CALLER_DID", + "HEADER_DID_SIGNATURE", + "HEADER_DID_TIMESTAMP", # Exceptions "AgentFieldError", "AgentFieldClientError", diff --git a/sdk/python/agentfield/agent.py b/sdk/python/agentfield/agent.py index 80646a9e..d5f97d54 100644 --- a/sdk/python/agentfield/agent.py +++ b/sdk/python/agentfield/agent.py @@ -38,6 +38,7 @@ reset_execution_context, set_execution_context, ) +from agentfield.execution_state import ExecuteError from agentfield.did_manager import DIDManager from agentfield.vc_generator import VCGenerator from agentfield.mcp_client import MCPClientRegistry @@ -405,6 +406,8 @@ def __init__( api_key: Optional[str] = None, enable_mcp: bool = False, enable_did: bool = True, + local_verification: bool = False, + verification_refresh_interval: int = 300, **kwargs, ): """ @@ -525,6 +528,7 @@ def __init__( self.client = AgentFieldClient( base_url=agentfield_server, async_config=self.async_config, api_key=api_key ) + self.client.caller_agent_id = self.node_id self._current_execution_context: Optional[ExecutionContext] = None # Initialize async execution manager (will be lazily created when needed) @@ -604,10 +608,27 @@ def __init__( if self._enable_did: self._initialize_did_system() + # Initialize local verification (decentralized verification) + self._local_verification_enabled = local_verification + self._local_verifier = None + self._realtime_validation_functions: Set[str] = set() + if local_verification: + from agentfield.verification import LocalVerifier + self._local_verifier = LocalVerifier( + agentfield_url=agentfield_server, + refresh_interval=verification_refresh_interval, + api_key=api_key, + ) + log_info("Local verification enabled (decentralized mode)") + # Setup standard AgentField routes and memory event listeners self.server_handler.setup_agentfield_routes() self._register_memory_event_listeners() + # Add local verification middleware if enabled + if self._local_verifier is not None: + self._add_local_verification_middleware() + # Register this agent instance for automatic workflow tracking set_current_agent(self) @@ -688,6 +709,7 @@ def _entry_to_metadata(self, entry: Union[ReasonerEntry, SkillEntry], kind: str) "memory_config": self.memory_config.to_dict(), "return_type_hint": getattr(entry.output_type, "__name__", str(entry.output_type)), "tags": entry.tags, + "proposed_tags": entry.tags, "vc_enabled": entry.vc_enabled if entry.vc_enabled is not None else self._agent_vc_enabled, } return metadata @@ -1345,11 +1367,10 @@ async def _generate_vc_async( error_message=error_message, duration_ms=duration_ms, ) - if vc and self.dev_mode: - log_debug(f"Generated VC {vc.vc_id} for {function_name}") + if vc: + log_info(f"Generated VC {vc.vc_id} for {function_name}") except Exception as e: - if self.dev_mode: - log_error(f"Failed to generate VC for {function_name}: {e}") + log_warn(f"Failed to generate VC for {function_name}: {e}") def _build_callback_discovery_payload(self) -> Optional[Dict[str, Any]]: """Prepare discovery metadata for agent registration.""" @@ -1457,12 +1478,21 @@ def _register_agent_with_did(self) -> bool: self.did_enabled = True if self.dev_mode: log_debug(f"DID registration successful for agent: {self.node_id}") + + # Wire DID credentials to the HTTP client for request signing + agent_did = self.did_manager.get_agent_did() + agent_private_key = None + if self.did_manager.identity_package: + agent_private_key = self.did_manager.identity_package.agent_did.private_key_jwk + if agent_did and agent_private_key: + self.client.set_did_credentials(agent_did, agent_private_key) + # Enable VC generation if self.vc_generator: self.vc_generator.set_enabled(True) if self.dev_mode: log_info(f"Agent {self.node_id} registered with DID system") - log_info(f"DID: {self.did_manager.get_agent_did()}") + log_info(f"DID: {agent_did}") else: if self.dev_mode: log_warn(f"Failed to register agent {self.node_id} with DID system") @@ -1492,6 +1522,7 @@ def reasoner( tags: Optional[List[str]] = None, *, vc_enabled: Optional[bool] = None, + require_realtime_validation: bool = False, ): """ Decorator to register a reasoner function. @@ -1545,6 +1576,8 @@ def decorator(func: Callable) -> Callable: # Persist VC override preference self._set_reasoner_vc_override(reasoner_id, vc_enabled) + if require_realtime_validation: + self._realtime_validation_functions.add(reasoner_id) # Get output schema from return type hint return_type = type_hints.get("return", dict) @@ -1809,6 +1842,28 @@ async def _execute_reasoner_endpoint( parent_execution_id=execution_context.parent_execution_id, ) raise cancel_err + except ExecuteError as exec_err: + # Propagate upstream HTTP status codes from cross-agent calls. + # Without this, a 403 from the inner call would become 500 + # (unhandled exception) and then 502 at the outer control plane. + if hasattr(self, "workflow_handler") and self.workflow_handler: + end_time = time.time() + await self.workflow_handler.notify_call_error( + execution_context.execution_id, + execution_context.workflow_id, + str(exec_err), + int((end_time - start_time) * 1000), + execution_context, + input_data=payload_dict, + parent_execution_id=execution_context.parent_execution_id, + ) + detail = {"error": str(exec_err)} + if exec_err.error_details: + detail["error_details"] = exec_err.error_details + raise HTTPException( + status_code=exec_err.status_code, + detail=detail, + ) except HTTPException as http_exc: if hasattr(self, "workflow_handler") and self.workflow_handler: end_time = time.time() @@ -1868,9 +1923,11 @@ async def _execute_async_with_callback( } log_info(f"Execution {execution_id} completed asynchronously") except Exception as exc: + error_details = getattr(exc, "error_details", None) payload = { "status": "failed", "error": str(exc), + "error_details": error_details, "duration_ms": int((time.time() - start_time) * 1000), "completed_at": datetime.now(timezone.utc).isoformat(), "execution_id": execution_id, @@ -1998,6 +2055,7 @@ def skill( name: Optional[str] = None, *, vc_enabled: Optional[bool] = None, + require_realtime_validation: bool = False, ): """ Decorator to register a skill function. @@ -2112,6 +2170,8 @@ def decorator(func: Callable) -> Callable: skill_id = decorator_name or func_name endpoint_path = decorator_path or f"/skills/{func_name}" self._set_skill_vc_override(skill_id, vc_enabled) + if require_realtime_validation: + self._realtime_validation_functions.add(skill_id) # Get type hints for input schema type_hints = get_type_hints(func) @@ -3241,6 +3301,12 @@ async def call(self, target: str, *args, **kwargs) -> dict: f"Async execution failed: {type(async_error).__name__}: {str(async_error)}" ) + # Never fall back on authorization errors (401/403) — + # these are permanent failures that retrying won't fix. + _err_status = getattr(async_error, "status", None) + if _err_status in (401, 403): + raise async_error + if not self.async_config.fallback_to_sync: raise async_error @@ -3872,6 +3938,120 @@ def get_status() -> dict: # Run in server mode self.serve(**serve_kwargs) + def _add_local_verification_middleware(self): + """Add FastAPI middleware for local DID signature verification.""" + from starlette.middleware.base import BaseHTTPMiddleware + from starlette.responses import JSONResponse as StarletteJSONResponse + + agent = self + + class LocalVerificationMiddleware(BaseHTTPMiddleware): + async def dispatch(self, request, call_next): + path = request.url.path + + # Only verify execution endpoints (reasoners and skills) + if not (path.startswith("/reasoners/") or path.startswith("/skills/")): + return await call_next(request) + + verifier = agent._local_verifier + if verifier is None: + return await call_next(request) + + # Extract function name from path + parts = path.strip("/").split("/") + function_name = parts[-1] if len(parts) >= 2 else "" + + # Check if function requires realtime validation (skip local) + if function_name in agent._realtime_validation_functions: + return await call_next(request) + + # Refresh cache if stale + if verifier.needs_refresh: + try: + await verifier.refresh() + except Exception as e: + log_warn(f"Failed to refresh local verifier cache: {e}") + + # Extract DID auth headers + caller_did = request.headers.get("X-Caller-DID", "") + signature = request.headers.get("X-DID-Signature", "") + timestamp = request.headers.get("X-DID-Timestamp", "") + nonce = request.headers.get("X-DID-Nonce", "") + + # C4: DID authentication is required for all execution endpoints + if not caller_did: + return StarletteJSONResponse( + status_code=401, + content={ + "error": "did_auth_required", + "message": "DID authentication required for this endpoint", + }, + ) + + # C5: Signature is required when caller DID is provided + if not signature: + return StarletteJSONResponse( + status_code=401, + content={ + "error": "signature_required", + "message": "DID signature required when caller DID is provided", + }, + ) + + # Check revocation + if verifier.check_revocation(caller_did): + return StarletteJSONResponse( + status_code=403, + content={ + "error": "did_revoked", + "message": f"Caller DID {caller_did} has been revoked", + }, + ) + + # Check registration — reject DIDs not registered with the control plane + if not verifier.check_registration(caller_did): + return StarletteJSONResponse( + status_code=403, + content={ + "error": "did_not_registered", + "message": f"Caller DID {caller_did} is not registered with the control plane", + }, + ) + + # Verify signature + body = await request.body() + if not verifier.verify_signature( + caller_did, signature, timestamp, body, nonce + ): + return StarletteJSONResponse( + status_code=401, + content={ + "error": "signature_invalid", + "message": "DID signature verification failed", + }, + ) + + # C6: Evaluate access policies + # Caller tags cannot be resolved at agent-side middleware level + # (would require a control plane lookup). Pass empty array — policies + # that require specific caller tags will not match, which is correct + # fail-open behavior. The control plane remains the primary policy + # enforcement point with full caller context. + agent_tags = getattr(agent, 'agent_tags', []) or [] + func_name = request.url.path.rstrip('/').split('/')[-1] if request.url.path else '' + if not verifier.evaluate_policy([], agent_tags, func_name, {}): + return StarletteJSONResponse( + status_code=403, + content={ + "error": "policy_denied", + "message": "Access denied by cached policy", + }, + ) + + return await call_next(request) + + self.add_middleware(LocalVerificationMiddleware) + def serve( # pragma: no cover - requires full server runtime integration self, port: Optional[int] = None, diff --git a/sdk/python/agentfield/agent_ai.py b/sdk/python/agentfield/agent_ai.py index 181a37e4..c7aa22f5 100644 --- a/sdk/python/agentfield/agent_ai.py +++ b/sdk/python/agentfield/agent_ai.py @@ -389,8 +389,17 @@ def trim_messages(messages: List[dict], model: str, max_tokens: int) -> List[dic litellm_params["messages"] = messages if schema: - # Use LiteLLM's native Pydantic model support for structured outputs - litellm_params["response_format"] = schema + # Convert Pydantic model to JSON schema format for LiteLLM + # This workaround prevents "Object of type ModelMetaclass is not JSON serializable" error + # See: https://github.com/BerriAI/litellm/issues/6830 + litellm_params["response_format"] = { + "type": "json_schema", + "json_schema": { + "schema": schema.model_json_schema(), + "name": schema.__name__, + "strict": True + } + } # Define the LiteLLM call function for rate limiter async def _make_litellm_call(): diff --git a/sdk/python/agentfield/agent_field_handler.py b/sdk/python/agentfield/agent_field_handler.py index 376552d7..b7c2acd2 100644 --- a/sdk/python/agentfield/agent_field_handler.py +++ b/sdk/python/agentfield/agent_field_handler.py @@ -131,13 +131,27 @@ async def register_with_agentfield_server(self, port: int): vc_metadata=self.agent._build_vc_metadata(), version=self.agent.version, agent_metadata=self.agent._build_agent_metadata(), + tags=self.agent.agent_tags, ) if success: if payload: self.agent._apply_discovery_response(payload) - log_success( - f"Registered node '{self.agent.node_id}' with AgentField server" - ) + + # Check for pending_approval status + if payload and payload.get("status") == "pending_approval": + pending_tags = payload.get("pending_tags", []) + log_info( + f"Node '{self.agent.node_id}' registered but awaiting tag approval " + f"(pending tags: {pending_tags})" + ) + await self._wait_for_approval() + log_success( + f"Node '{self.agent.node_id}' tag approval granted" + ) + else: + log_success( + f"Registered node '{self.agent.node_id}' with AgentField server" + ) self.agent.agentfield_connected = True # Attempt DID registration after successful AgentField registration @@ -169,6 +183,46 @@ async def register_with_agentfield_server(self, port: int): log_warn(f"Response text: {e.response.text}") raise + async def _wait_for_approval(self, timeout: int = 300): + """Poll the control plane until the agent is no longer in pending_approval status. + + Args: + timeout: Maximum seconds to wait for approval before raising an error. + Defaults to 300 (5 minutes). + """ + import asyncio + + poll_interval = 5 # seconds + elapsed = 0 + while elapsed < timeout: + await asyncio.sleep(poll_interval) + elapsed += poll_interval + try: + resp = await self.agent.client._async_request( + "GET", + f"{self.agent.client.api_base}/nodes/{self.agent.node_id}", + headers=self.agent.client._get_auth_headers(), + timeout=10.0, + ) + if resp.status_code == 200: + data = resp.json() + status = data.get("lifecycle_status", "") + if status and status != "pending_approval": + return + log_debug( + f"Node '{self.agent.node_id}' still pending approval..." + ) + except Exception as e: + log_debug(f"Polling for approval status failed: {e}") + + log_error( + f"Node '{self.agent.node_id}' approval timed out after {timeout}s" + ) + raise TimeoutError( + f"Agent '{self.agent.node_id}' tag approval timed out after {timeout} seconds. " + "Please approve the agent's tags in the control plane admin UI." + ) + def send_heartbeat(self): """Send heartbeat to AgentField server""" if not self.agent.agentfield_connected: @@ -248,6 +302,7 @@ async def send_enhanced_heartbeat(self) -> bool: status=self.agent._current_status, mcp_servers=mcp_servers, timestamp=datetime.now().isoformat(), + version=getattr(self.agent, 'version', '') or '', ) # Send enhanced heartbeat @@ -431,6 +486,7 @@ async def register_with_fast_lifecycle( vc_metadata=self.agent._build_vc_metadata(), version=self.agent.version, agent_metadata=self.agent._build_agent_metadata(), + tags=self.agent.agent_tags, ) if success: diff --git a/sdk/python/agentfield/async_execution_manager.py b/sdk/python/agentfield/async_execution_manager.py index fadfd09e..1afd4191 100644 --- a/sdk/python/agentfield/async_execution_manager.py +++ b/sdk/python/agentfield/async_execution_manager.py @@ -17,7 +17,7 @@ import aiohttp from .async_config import AsyncConfig -from .execution_state import ExecutionPriority, ExecutionState, ExecutionStatus +from .execution_state import ExecuteError, ExecutionPriority, ExecutionState, ExecutionStatus from .http_connection_manager import ConnectionManager from .logger import get_logger from .result_cache import ResultCache @@ -179,6 +179,7 @@ def __init__( connection_manager: Optional[ConnectionManager] = None, result_cache: Optional[ResultCache] = None, auth_headers: Optional[Dict[str, str]] = None, + did_authenticator: Optional[Any] = None, ): """ Initialize the async execution manager. @@ -190,6 +191,7 @@ def __init__( result_cache: Optional ResultCache instance auth_headers: Optional auth headers (e.g. X-API-Key) included in every polling request to the control plane + did_authenticator: Optional DIDAuthenticator for signing requests """ self.base_url = base_url.rstrip("/") self.config = config or AsyncConfig() @@ -201,6 +203,7 @@ def __init__( # Initialize components self.connection_manager = connection_manager or ConnectionManager(self.config) self.result_cache = result_cache or ResultCache(self.config) + self._did_authenticator = did_authenticator # Execution tracking self._executions: Dict[str, ExecutionState] = {} @@ -382,6 +385,14 @@ async def submit_execution( else: raise TypeError("webhook must be a WebhookConfig or dict") + # Serialize with compact separators so the signed bytes match what gets sent. + body_bytes = json.dumps(payload, separators=(",", ":")).encode("utf-8") + + # Add DID authentication headers if configured + if self._did_authenticator is not None and self._did_authenticator.is_configured: + did_headers = self._did_authenticator.sign_headers(body_bytes) + request_headers.update(did_headers) + # Set timeout execution_timeout = timeout or self.config.default_execution_timeout @@ -391,11 +402,20 @@ async def submit_execution( async with self.connection_manager.get_session() as session: response = await session.post( url, - json=payload, + data=body_bytes, headers=request_headers, timeout=self.config.polling_timeout, ) - response.raise_for_status() + if response.status >= 400: + try: + error_body = await response.json() + except Exception: + error_body = None + body_msg = "" + if isinstance(error_body, dict): + body_msg = error_body.get("message") or error_body.get("error") or "" + msg = f"{response.status}, {body_msg}" if body_msg else str(response.status) + raise ExecuteError(response.status, msg, error_body) result = await response.json() execution_id = result.get("execution_id") diff --git a/sdk/python/agentfield/client.py b/sdk/python/agentfield/client.py index 6d329f22..c6f97f5d 100644 --- a/sdk/python/agentfield/client.py +++ b/sdk/python/agentfield/client.py @@ -18,12 +18,13 @@ WebhookConfig, ) from .async_config import AsyncConfig -from .execution_state import ExecutionStatus +from .execution_state import ExecuteError, ExecutionStatus from .result_cache import ResultCache from .async_execution_manager import AsyncExecutionManager from .logger import get_logger from .status import normalize_status from .execution_context import generate_run_id +from .did_auth import DIDAuthenticator from .exceptions import ( AgentFieldError, AgentFieldClientError, @@ -99,11 +100,16 @@ def __init__( base_url: str = "http://localhost:8080", api_key: Optional[str] = None, async_config: Optional[AsyncConfig] = None, + did: Optional[str] = None, + private_key_jwk: Optional[str] = None, ): self.base_url = base_url self.api_base = f"{base_url}/api/v1" self.api_key = api_key + # DID authentication for agent-to-agent calls + self._did_authenticator = DIDAuthenticator(did=did, private_key_jwk=private_key_jwk) + # Async execution components self.async_config = async_config or AsyncConfig() self._async_execution_manager: Optional[AsyncExecutionManager] = None @@ -112,6 +118,8 @@ def __init__( self._result_cache = ResultCache(self.async_config) self._latest_event_stream_headers: Dict[str, str] = {} self._current_workflow_context = None + # Caller agent ID for cross-agent call identification (set by Agent after init) + self.caller_agent_id: Optional[str] = None # Initialize shared sync session if not already created if AgentFieldClient._shared_sync_session is None: @@ -164,6 +172,42 @@ def _get_auth_headers(self) -> Dict[str, str]: return {} return {"X-API-Key": self.api_key} + def set_did_credentials(self, did: str, private_key_jwk: str) -> bool: + """ + Set DID authentication credentials for agent-to-agent calls. + + Args: + did: The agent's DID identifier (e.g., 'did:web:example.com:agents:my-agent') + private_key_jwk: JWK-formatted Ed25519 private key for signing + + Returns: + True if credentials were set successfully, False otherwise + """ + return self._did_authenticator.set_credentials(did, private_key_jwk) + + def get_did_auth_headers(self, body: bytes) -> Dict[str, str]: + """ + Get DID authentication headers for signing a request. + + Args: + body: Request body bytes to sign + + Returns: + Dictionary with DID auth headers (X-Caller-DID, X-DID-Signature, X-DID-Timestamp) + Empty dict if DID auth is not configured + """ + return self._did_authenticator.sign_headers(body) + + @property + def did(self) -> Optional[str]: + """Get the configured DID identifier.""" + return self._did_authenticator.did + + @property + def did_auth_configured(self) -> bool: + """Check if DID authentication is configured.""" + return self._did_authenticator.is_configured + def _get_headers_with_context( self, headers: Optional[Dict[str, str]] = None ) -> Dict[str, str]: @@ -544,6 +588,7 @@ async def register_agent( vc_metadata: Optional[Dict[str, Any]] = None, version: str = "1.0.0", agent_metadata: Optional[Dict[str, Any]] = None, + tags: Optional[List[str]] = None, ) -> Tuple[bool, Optional[Dict[str, Any]]]: """Register or update agent information with AgentField server.""" try: @@ -551,6 +596,7 @@ async def register_agent( if agent_metadata: custom_metadata.update(agent_metadata) + agent_tags = tags or [] registration_data = { "id": node_id, "team_id": "default", @@ -558,6 +604,7 @@ async def register_agent( "version": version, "reasoners": reasoners, "skills": skills, + "proposed_tags": agent_tags, "communication_config": { "protocols": ["http"], "websocket_endpoint": "", @@ -697,6 +744,10 @@ def _prepare_execution_headers( if actor_id: final_headers["X-Actor-ID"] = actor_id + # Include caller agent ID for permission middleware identification + if self.caller_agent_id and "X-Caller-Agent-ID" not in final_headers: + final_headers["X-Caller-Agent-ID"] = self.caller_agent_id + sanitized_headers = self._sanitize_header_values(final_headers) self._maybe_update_event_stream_headers(sanitized_headers) return sanitized_headers @@ -707,19 +758,40 @@ def _submit_execution_sync( input_data: Dict[str, Any], headers: Dict[str, str], ) -> _Submission: + import json as json_module + payload = {"input": input_data} + # Serialize once so the signed bytes are exactly what gets sent. + body_bytes = json_module.dumps(payload, separators=(",", ":")).encode("utf-8") + + # Add DID authentication headers if configured + final_headers = dict(headers) + final_headers["Content-Type"] = "application/json" + if self._did_authenticator.is_configured: + did_headers = self._did_authenticator.sign_headers(body_bytes) + final_headers.update(did_headers) + try: response = requests.post( f"{self.api_base}/execute/async/{target}", - json=payload, - headers=headers, + data=body_bytes, + headers=final_headers, timeout=self.async_config.polling_timeout, ) except requests.RequestException as exc: raise AgentFieldClientError(f"Failed to submit execution: {exc}") from exc - response.raise_for_status() + if response.status_code >= 400: + try: + error_body = response.json() + except Exception: + error_body = None + body_msg = "" + if isinstance(error_body, dict): + body_msg = error_body.get("message") or error_body.get("error") or "" + msg = f"{response.status_code}, {body_msg}" if body_msg else str(response.status_code) + raise ExecuteError(response.status_code, msg, error_body) body = response.json() - return self._parse_submission(body, headers, target) + return self._parse_submission(body, final_headers, target) async def _submit_execution_async( self, @@ -727,17 +799,40 @@ async def _submit_execution_async( input_data: Dict[str, Any], headers: Dict[str, str], ) -> _Submission: + import json as json_module + payload = {"input": input_data} + # Serialize once so the signed bytes are exactly what gets sent. + # httpx uses compact separators (',', ':') which differ from + # json.dumps() defaults (', ', ': '), causing signature mismatch. + body_bytes = json_module.dumps(payload, separators=(",", ":")).encode("utf-8") + + # Add DID authentication headers if configured + final_headers = dict(headers) + final_headers["Content-Type"] = "application/json" + if self._did_authenticator.is_configured: + did_headers = self._did_authenticator.sign_headers(body_bytes) + final_headers.update(did_headers) + response = await self._async_request( "POST", f"{self.api_base}/execute/async/{target}", - json=payload, - headers=headers, + content=body_bytes, + headers=final_headers, timeout=self.async_config.polling_timeout, ) - response.raise_for_status() + if response.status_code >= 400: + try: + error_body = response.json() + except Exception: + error_body = None + body_msg = "" + if isinstance(error_body, dict): + body_msg = error_body.get("message") or error_body.get("error") or "" + msg = f"{response.status_code}, {body_msg}" if body_msg else str(response.status_code) + raise ExecuteError(response.status_code, msg, error_body) body = response.json() - return self._parse_submission(body, headers, target) + return self._parse_submission(body, final_headers, target) def _parse_submission( self, @@ -874,6 +969,7 @@ def _format_execution_result( "completed_at": payload.get("completed_at"), "node_id": node_id, "error_message": payload.get("error_message") or payload.get("error"), + "error_details": payload.get("error_details"), } if metadata.get("completed_at"): @@ -911,6 +1007,8 @@ def _build_execute_response( else: response_result = result_value + error_details = metadata.get("error_details") + response = { "execution_id": metadata.get("execution_id"), "run_id": metadata.get("run_id"), @@ -923,6 +1021,7 @@ def _build_execute_response( or datetime.datetime.utcnow().isoformat(), "result": response_result, "error_message": error_message, + "error_details": error_details, "cost": payload.get("cost"), } @@ -1046,6 +1145,7 @@ async def register_agent_with_status( vc_metadata: Optional[Dict[str, Any]] = None, version: str = "1.0.0", agent_metadata: Optional[Dict[str, Any]] = None, + tags: Optional[List[str]] = None, ) -> Tuple[bool, Optional[Dict[str, Any]]]: """Register agent with immediate status reporting for fast lifecycle.""" try: @@ -1053,6 +1153,7 @@ async def register_agent_with_status( if agent_metadata: custom_metadata.update(agent_metadata) + agent_tags = tags or [] registration_data = { "id": node_id, "team_id": "default", @@ -1060,6 +1161,7 @@ async def register_agent_with_status( "version": version, "reasoners": reasoners, "skills": skills, + "proposed_tags": agent_tags, "lifecycle_status": status.value, "communication_config": { "protocols": ["http"], @@ -1153,6 +1255,7 @@ async def _get_async_execution_manager(self) -> AsyncExecutionManager: base_url=self.base_url, config=self.async_config, auth_headers=self._get_auth_headers(), + did_authenticator=self._did_authenticator, ) await self._async_execution_manager.start() self._maybe_update_event_stream_headers(None) @@ -1210,6 +1313,13 @@ async def execute_async( if isinstance(e, AgentFieldError): raise + # Never fall back on authorization errors (401/403) — these are + # permanent failures that retrying won't fix and would hit replay + # protection (Ed25519 signatures are deterministic within the same second). + _status = getattr(e, "status", None) + if _status in (401, 403): + raise + # Fallback to sync execution if enabled if self.async_config.fallback_to_sync: logger.warn(f"Falling back to sync execution for target {target}") diff --git a/sdk/python/agentfield/connection_manager.py b/sdk/python/agentfield/connection_manager.py index 65a063cf..60ebac48 100644 --- a/sdk/python/agentfield/connection_manager.py +++ b/sdk/python/agentfield/connection_manager.py @@ -143,6 +143,7 @@ async def _attempt_connection(self) -> bool: vc_metadata=self.agent._build_vc_metadata(), version=self.agent.version, agent_metadata=self.agent._build_agent_metadata(), + tags=self.agent.agent_tags, ) finally: # Restore original logging levels @@ -152,6 +153,17 @@ async def _attempt_connection(self) -> bool: if success: if payload: self.agent._apply_discovery_response(payload) + + # Check for pending_approval status (tag approval required) + if payload and payload.get("status") == "pending_approval": + pending_tags = payload.get("pending_tags", []) + log_info( + f"Node '{self.agent.node_id}' registered but awaiting tag approval " + f"(pending tags: {pending_tags})" + ) + await self.agent.agentfield_handler._wait_for_approval() + log_info(f"Node '{self.agent.node_id}' tag approval granted") + if self.agent.did_manager and not self.agent.did_enabled: self.agent._register_agent_with_did() self.state = ConnectionState.CONNECTED diff --git a/sdk/python/agentfield/did_auth.py b/sdk/python/agentfield/did_auth.py new file mode 100644 index 00000000..79274302 --- /dev/null +++ b/sdk/python/agentfield/did_auth.py @@ -0,0 +1,245 @@ +""" +DID Authentication for AgentField SDK + +Provides cryptographic signing for agent-to-agent requests using Ed25519 signatures. +This module handles the creation of DID authentication headers for protected agent calls. +""" + +import base64 +import hashlib +import json +import os +import time +from typing import Dict, Optional, Tuple + +from .logger import get_logger + +logger = get_logger(__name__) + +# Headers used for DID authentication +HEADER_CALLER_DID = "X-Caller-DID" +HEADER_DID_SIGNATURE = "X-DID-Signature" +HEADER_DID_TIMESTAMP = "X-DID-Timestamp" +HEADER_DID_NONCE = "X-DID-Nonce" + + +def _load_ed25519_private_key(private_key_jwk: str): + """ + Load Ed25519 private key from JWK format. + + Args: + private_key_jwk: JWK-formatted private key string + + Returns: + Ed25519PrivateKey object + + Raises: + ImportError: If cryptography library is not installed + ValueError: If key format is invalid + """ + try: + from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey + except ImportError: + raise ImportError( + "The 'cryptography' library is required for DID authentication. " + "Install it with: pip install cryptography" + ) + + try: + jwk = json.loads(private_key_jwk) if isinstance(private_key_jwk, str) else private_key_jwk + + # Verify key type + if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519": + raise ValueError("Invalid key type: expected Ed25519 OKP key") + + # Extract 'd' (private key bytes) from JWK + d_value = jwk.get("d") + if not d_value: + raise ValueError("Missing 'd' (private key) in JWK") + + # Decode base64url-encoded private key + # Add padding if needed for base64url decoding + padding = 4 - (len(d_value) % 4) + if padding != 4: + d_value += "=" * padding + + private_key_bytes = base64.urlsafe_b64decode(d_value) + + return Ed25519PrivateKey.from_private_bytes(private_key_bytes) + + except json.JSONDecodeError as e: + raise ValueError(f"Invalid JWK format: {e}") + + +def sign_request( + body: bytes, + private_key_jwk: str, + did: str, +) -> Tuple[str, str, str]: + """ + Sign a request body for DID authentication. + + Creates the signature payload as "{timestamp}:{nonce}:{sha256(body)}" and signs it + with the Ed25519 private key. The nonce ensures each signature is unique even when + the same body is signed within the same second. + + Args: + body: Request body bytes to sign + private_key_jwk: JWK-formatted private key string + did: Caller's DID identifier + + Returns: + Tuple of (signature_base64, timestamp_str, nonce, did) + + Raises: + ImportError: If cryptography library is not installed + ValueError: If key format is invalid + """ + # Load private key + private_key = _load_ed25519_private_key(private_key_jwk) + + # Get current timestamp + timestamp = str(int(time.time())) + + # Generate per-request nonce to prevent replay detection when + # multiple requests have the same body within the same second + # (Ed25519 is deterministic, so same payload = same signature) + nonce = os.urandom(16).hex() + + # Hash the body + body_hash = hashlib.sha256(body).hexdigest() + + # Create payload: "{timestamp}:{nonce}:{body_hash}" + payload = f"{timestamp}:{nonce}:{body_hash}".encode("utf-8") + + # Sign the payload + signature = private_key.sign(payload) + + # Encode signature as base64 + signature_b64 = base64.b64encode(signature).decode("ascii") + + return signature_b64, timestamp, nonce, did + + +def create_did_auth_headers( + body: bytes, + private_key_jwk: str, + did: str, +) -> Dict[str, str]: + """ + Create DID authentication headers for a request. + + Args: + body: Request body bytes + private_key_jwk: JWK-formatted private key string + did: Caller's DID identifier + + Returns: + Dictionary with DID authentication headers + + Raises: + ImportError: If cryptography library is not installed + ValueError: If key format is invalid + """ + signature, timestamp, nonce, caller_did = sign_request(body, private_key_jwk, did) + + return { + HEADER_CALLER_DID: caller_did, + HEADER_DID_SIGNATURE: signature, + HEADER_DID_TIMESTAMP: timestamp, + HEADER_DID_NONCE: nonce, + } + + +class DIDAuthenticator: + """ + Handles DID authentication for agent requests. + + This class manages the signing credentials and provides methods + for creating authenticated request headers. + """ + + def __init__(self, did: Optional[str] = None, private_key_jwk: Optional[str] = None): + """ + Initialize DID authenticator. + + Args: + did: The agent's DID identifier + private_key_jwk: JWK-formatted private key for signing + """ + self._did = did + self._private_key_jwk = private_key_jwk + self._private_key = None + + # Pre-load the private key if provided + if private_key_jwk: + try: + self._private_key = _load_ed25519_private_key(private_key_jwk) + except (ImportError, ValueError) as e: + logger.warning(f"Could not load private key for DID auth: {e}") + + @property + def did(self) -> Optional[str]: + """Get the DID identifier.""" + return self._did + + @property + def is_configured(self) -> bool: + """Check if DID authentication is configured.""" + return self._did is not None and self._private_key is not None + + def set_credentials(self, did: str, private_key_jwk: str) -> bool: + """ + Set DID authentication credentials. + + Args: + did: The agent's DID identifier + private_key_jwk: JWK-formatted private key for signing + + Returns: + True if credentials were set successfully, False otherwise + """ + try: + self._private_key = _load_ed25519_private_key(private_key_jwk) + self._did = did + self._private_key_jwk = private_key_jwk + logger.debug(f"DID authentication configured for {did}") + return True + except (ImportError, ValueError) as e: + logger.error(f"Failed to set DID credentials: {e}") + return False + + def sign_headers(self, body: bytes) -> Dict[str, str]: + """ + Create DID authentication headers for a request. + + Args: + body: Request body bytes to sign + + Returns: + Dictionary with DID authentication headers, empty if not configured + + Note: + Returns empty dict if DID auth is not configured, allowing + requests to proceed without authentication. + """ + if not self.is_configured: + return {} + + try: + return create_did_auth_headers(body, self._private_key_jwk, self._did) + except Exception as e: + logger.error(f"Failed to sign request: {e}") + return {} + + def get_auth_info(self) -> Dict[str, any]: + """ + Get information about the authentication configuration. + + Returns: + Dictionary with authentication info (no private key) + """ + return { + "configured": self.is_configured, + "did": self._did, + } diff --git a/sdk/python/agentfield/did_manager.py b/sdk/python/agentfield/did_manager.py index eedec4a8..a6d10bf8 100644 --- a/sdk/python/agentfield/did_manager.py +++ b/sdk/python/agentfield/did_manager.py @@ -20,7 +20,7 @@ class DIDIdentity: """Represents a DID identity with cryptographic keys.""" did: str - private_key_jwk: str + private_key_jwk: Optional[str] public_key_jwk: str derivation_path: str component_type: str @@ -282,7 +282,7 @@ def _parse_identity_package( agent_data = package_data["agent_did"] agent_did = DIDIdentity( did=agent_data["did"], - private_key_jwk=agent_data["private_key_jwk"], + private_key_jwk=agent_data.get("private_key_jwk"), public_key_jwk=agent_data["public_key_jwk"], derivation_path=agent_data["derivation_path"], component_type=agent_data["component_type"], @@ -294,7 +294,7 @@ def _parse_identity_package( for name, reasoner_data in package_data["reasoner_dids"].items(): reasoner_dids[name] = DIDIdentity( did=reasoner_data["did"], - private_key_jwk=reasoner_data["private_key_jwk"], + private_key_jwk=reasoner_data.get("private_key_jwk"), public_key_jwk=reasoner_data["public_key_jwk"], derivation_path=reasoner_data["derivation_path"], component_type=reasoner_data["component_type"], @@ -306,7 +306,7 @@ def _parse_identity_package( for name, skill_data in package_data["skill_dids"].items(): skill_dids[name] = DIDIdentity( did=skill_data["did"], - private_key_jwk=skill_data["private_key_jwk"], + private_key_jwk=skill_data.get("private_key_jwk"), public_key_jwk=skill_data["public_key_jwk"], derivation_path=skill_data["derivation_path"], component_type=skill_data["component_type"], diff --git a/sdk/python/agentfield/execution_state.py b/sdk/python/agentfield/execution_state.py index e1d04ec7..faf91369 100644 --- a/sdk/python/agentfield/execution_state.py +++ b/sdk/python/agentfield/execution_state.py @@ -12,6 +12,21 @@ import time +class ExecuteError(Exception): + """Error from a failed execution HTTP request with structured error details preserved.""" + + def __init__( + self, + status_code: int, + message: str, + error_details: Optional[Dict[str, Any]] = None, + ): + self.status_code = status_code + self.status = status_code # Compat with existing getattr(e, "status") checks + self.error_details = error_details + super().__init__(message) + + class ExecutionStatus(Enum): """Enumeration of possible execution statuses.""" diff --git a/sdk/python/agentfield/types.py b/sdk/python/agentfield/types.py index 385de850..89f30b63 100644 --- a/sdk/python/agentfield/types.py +++ b/sdk/python/agentfield/types.py @@ -36,12 +36,14 @@ class HeartbeatData: status: AgentStatus mcp_servers: List[MCPServerHealth] timestamp: str + version: str = "" def to_dict(self) -> Dict[str, Any]: return { "status": self.status.value, "mcp_servers": [server.to_dict() for server in self.mcp_servers], "timestamp": self.timestamp, + "version": self.version, } diff --git a/sdk/python/agentfield/verification.py b/sdk/python/agentfield/verification.py new file mode 100644 index 00000000..f0d171d7 --- /dev/null +++ b/sdk/python/agentfield/verification.py @@ -0,0 +1,426 @@ +""" +Local verification for AgentField SDK. + +Provides decentralized verification of incoming requests by caching policies, +revocation lists, and the admin's public key from the control plane. Agents +can verify DID signatures and evaluate access policies locally without +hitting the control plane for every call. +""" + +import base64 +import hashlib +import time +from typing import Any, Dict, List, Optional, Set + +from .logger import get_logger + +logger = get_logger(__name__) + +# DID auth headers (same as did_auth.py) +HEADER_CALLER_DID = "X-Caller-DID" +HEADER_DID_SIGNATURE = "X-DID-Signature" +HEADER_DID_TIMESTAMP = "X-DID-Timestamp" + + +class LocalVerifier: + """ + Verifies incoming requests locally using cached policies, revocations, + and the admin's Ed25519 public key. + + Periodically refreshes caches from the control plane. If the control plane + is unreachable, continues using stale caches until TTL expires. + """ + + def __init__( + self, + agentfield_url: str, + refresh_interval: int = 300, + timestamp_window: int = 300, + api_key: Optional[str] = None, + ): + """ + Initialize the local verifier. + + Args: + agentfield_url: Base URL of the AgentField control plane + refresh_interval: Seconds between cache refreshes (default: 300 = 5 min) + timestamp_window: Allowed timestamp skew in seconds (default: 300 = 5 min) + api_key: Optional API key for authenticating with the control plane + """ + self.agentfield_url = agentfield_url.rstrip("/") + self.refresh_interval = refresh_interval + self.timestamp_window = timestamp_window + self.api_key = api_key + + # Cached data + self.policies: List[Dict[str, Any]] = [] + self.revoked_dids: Set[str] = set() + self.registered_dids: Set[str] = set() + self.admin_public_key_jwk: Optional[Dict[str, Any]] = None + self.issuer_did: Optional[str] = None + + # Cache metadata + self._last_refresh: float = 0 + self._initialized: bool = False + + async def refresh(self) -> bool: + """ + Fetch policies, revocations, and admin public key from the control plane. + + Returns: + True if refresh succeeded, False otherwise (stale cache still used) + """ + try: + import aiohttp + except ImportError: + logger.warning("aiohttp not available, cannot refresh verification cache") + return False + + headers = {} + if self.api_key: + headers["X-API-Key"] = self.api_key + + success = True + async with aiohttp.ClientSession() as session: + # Fetch policies + try: + async with session.get( + f"{self.agentfield_url}/api/v1/policies", + headers=headers, + timeout=aiohttp.ClientTimeout(total=10), + ) as resp: + if resp.status == 200: + data = await resp.json() + self.policies = data.get("policies", []) or [] + logger.debug(f"Refreshed {len(self.policies)} policies") + else: + logger.warning(f"Failed to fetch policies: HTTP {resp.status}") + success = False + except Exception as e: + logger.warning(f"Failed to fetch policies: {e}") + success = False + + # Fetch revocations + try: + async with session.get( + f"{self.agentfield_url}/api/v1/revocations", + headers=headers, + timeout=aiohttp.ClientTimeout(total=10), + ) as resp: + if resp.status == 200: + data = await resp.json() + self.revoked_dids = set(data.get("revoked_dids", [])) + logger.debug(f"Refreshed {len(self.revoked_dids)} revoked DIDs") + else: + logger.warning(f"Failed to fetch revocations: HTTP {resp.status}") + success = False + except Exception as e: + logger.warning(f"Failed to fetch revocations: {e}") + success = False + + # Fetch registered DIDs + try: + async with session.get( + f"{self.agentfield_url}/api/v1/registered-dids", + headers=headers, + timeout=aiohttp.ClientTimeout(total=10), + ) as resp: + if resp.status == 200: + data = await resp.json() + self.registered_dids = set(data.get("registered_dids", [])) + logger.debug(f"Refreshed {len(self.registered_dids)} registered DIDs") + else: + logger.warning(f"Failed to fetch registered DIDs: HTTP {resp.status}") + success = False + except Exception as e: + logger.warning(f"Failed to fetch registered DIDs: {e}") + success = False + + # Fetch admin public key + try: + async with session.get( + f"{self.agentfield_url}/api/v1/admin/public-key", + headers=headers, + timeout=aiohttp.ClientTimeout(total=10), + ) as resp: + if resp.status == 200: + data = await resp.json() + self.admin_public_key_jwk = data.get("public_key_jwk") + self.issuer_did = data.get("issuer_did") + logger.debug(f"Refreshed admin public key (issuer: {self.issuer_did})") + else: + logger.warning(f"Failed to fetch admin public key: HTTP {resp.status}") + success = False + except Exception as e: + logger.warning(f"Failed to fetch admin public key: {e}") + success = False + + if success: + self._last_refresh = time.time() + self._initialized = True + + return success + + @property + def needs_refresh(self) -> bool: + """Check if the cache is stale and needs refreshing.""" + if not self._initialized: + return True + return time.time() - self._last_refresh > self.refresh_interval + + def check_revocation(self, caller_did: str) -> bool: + """ + Check if a caller DID is in the revocation list. + + Args: + caller_did: The DID to check + + Returns: + True if revoked, False if not revoked + """ + return caller_did in self.revoked_dids + + def check_registration(self, caller_did: str) -> bool: + """ + Check if a caller DID is registered with the control plane. + + Returns True if registered (known), False if unknown. When the + registered DIDs cache is empty (not yet loaded), returns True to + avoid blocking requests before the first refresh completes. + """ + if not self.registered_dids: + # Cache not yet populated — allow to avoid blocking before first refresh. + return True + return caller_did in self.registered_dids + + def verify_signature( + self, + caller_did: str, + signature_b64: str, + timestamp: str, + body: bytes, + nonce: str = "", + ) -> bool: + """ + Verify an Ed25519 DID signature on an incoming request. + + Resolves the caller's public key from their DID (did:key embeds the key + directly; other methods fall back to the admin public key). + + Args: + caller_did: Caller's DID identifier + signature_b64: Base64-encoded Ed25519 signature + timestamp: Unix timestamp string from the request + body: Request body bytes + nonce: Optional nonce from X-DID-Nonce header + + Returns: + True if signature is valid, False otherwise + """ + # Validate timestamp window + try: + ts = int(timestamp) + now = int(time.time()) + if abs(now - ts) > self.timestamp_window: + logger.debug(f"Timestamp expired: {now - ts}s drift (window: {self.timestamp_window}s)") + return False + except (ValueError, TypeError): + logger.debug("Invalid timestamp format") + return False + + try: + from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey + except ImportError: + logger.warning("cryptography library not available for signature verification") + return False + + try: + # Resolve public key from the caller's DID + public_key_bytes = self._resolve_public_key(caller_did) + if public_key_bytes is None: + logger.debug(f"Could not resolve public key for DID: {caller_did}") + return False + public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes) + + # Reconstruct the signed payload: "{timestamp}[:{nonce}]:{sha256(body)}" + # Must match the format used by SDK signing (did_auth.py) + body_hash = hashlib.sha256(body).hexdigest() + if nonce: + payload = f"{timestamp}:{nonce}:{body_hash}".encode("utf-8") + else: + payload = f"{timestamp}:{body_hash}".encode("utf-8") + + # Decode the signature + signature_bytes = base64.b64decode(signature_b64) + + # Verify + public_key.verify(signature_bytes, payload) + return True + + except Exception as e: + logger.debug(f"Signature verification failed: {e}") + return False + + def _resolve_public_key(self, caller_did: str) -> Optional[bytes]: + """ + Resolve the public key bytes from a DID. + + For did:key, the public key is self-contained in the identifier: + did:key:z + + For other DID methods, falls back to the admin public key. + """ + if caller_did.startswith("did:key:z"): + try: + encoded = caller_did[len("did:key:z"):] + decoded = base64.urlsafe_b64decode(encoded + "==") + # Verify Ed25519 multicodec prefix: 0xed, 0x01 + if len(decoded) >= 34 and decoded[0] == 0xED and decoded[1] == 0x01: + return decoded[2:34] + logger.debug(f"Invalid multicodec prefix in did:key: {decoded[:2].hex()}") + return None + except Exception as e: + logger.debug(f"Failed to decode did:key public key: {e}") + return None + + # Fallback: use admin public key for non-did:key methods + if self.admin_public_key_jwk: + try: + x_value = self.admin_public_key_jwk.get("x", "") + padding = 4 - (len(x_value) % 4) + if padding != 4: + x_value += "=" * padding + return base64.urlsafe_b64decode(x_value) + except Exception as e: + logger.debug(f"Failed to decode admin public key: {e}") + return None + + logger.debug("No public key available for verification") + return None + + def evaluate_policy( + self, + caller_tags: List[str], + target_tags: List[str], + function_name: str, + input_params: Optional[Dict[str, Any]] = None, + ) -> bool: + """ + Evaluate access policies locally. + + Finds matching policies based on caller/target tags and function name, + then evaluates constraints. + + Args: + caller_tags: Tags associated with the calling agent + target_tags: Tags associated with the target agent + function_name: Name of the function being called + input_params: Input parameters for constraint evaluation + + Returns: + True if access is allowed, False if denied + """ + if not self.policies: + # Fail closed: no policies loaded means we cannot verify access. + # This prevents bypassing authorization when policies fail to load. + return False + + # Sort policies by priority (descending) + sorted_policies = sorted( + self.policies, + key=lambda p: p.get("priority", 0), + reverse=True, + ) + + for policy in sorted_policies: + if not policy.get("enabled", True): + continue + + # Check if caller tags match + policy_caller_tags = policy.get("caller_tags", []) + if policy_caller_tags and not any(t in caller_tags for t in policy_caller_tags): + continue + + # Check if target tags match + policy_target_tags = policy.get("target_tags", []) + if policy_target_tags and not any(t in target_tags for t in policy_target_tags): + continue + + # Check function allow/deny lists + allow_functions = policy.get("allow_functions", []) + deny_functions = policy.get("deny_functions", []) + + # Check deny list first + if deny_functions and _function_matches(function_name, deny_functions): + return False + + # Check allow list + if allow_functions and not _function_matches(function_name, allow_functions): + continue + + # Check constraints + constraints = policy.get("constraints", {}) + if constraints and input_params: + if not _evaluate_constraints(constraints, function_name, input_params): + return False + + # Policy action + action = policy.get("action", "allow") + return action == "allow" + + # No matching policy found — allow by default + return True + + +def _function_matches(function_name: str, patterns: List[str]) -> bool: + """Check if a function name matches any of the patterns (supports * wildcards).""" + import fnmatch + + for pattern in patterns: + if fnmatch.fnmatch(function_name, pattern): + return True + return False + + +def _evaluate_constraints( + constraints: Dict[str, Any], + function_name: str, + input_params: Dict[str, Any], +) -> bool: + """Evaluate parameter constraints for a function call.""" + # Constraints can be keyed by function name or parameter name + func_constraints = constraints.get(function_name, constraints) + if not isinstance(func_constraints, dict): + return True + + for param_name, constraint in func_constraints.items(): + if param_name not in input_params: + continue + + value = input_params[param_name] + if isinstance(constraint, dict): + operator = constraint.get("operator", "") + threshold = constraint.get("value") + if threshold is None: + continue + + try: + value = float(value) + threshold = float(threshold) + except (ValueError, TypeError): + # Fail closed: invalid constraint values should deny access + # rather than silently skipping the constraint check + return False + + if operator == "<=" and value > threshold: + return False + elif operator == ">=" and value < threshold: + return False + elif operator == "<" and value >= threshold: + return False + elif operator == ">" and value <= threshold: + return False + elif operator == "==" and value != threshold: + return False + + return True diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml index 760ae08e..55321862 100644 --- a/sdk/python/pyproject.toml +++ b/sdk/python/pyproject.toml @@ -36,7 +36,8 @@ dependencies = [ "PyYAML>=6.0", "aiohttp>=3.8", "websockets", - "fal-client>=0.5.0" + "fal-client>=0.5.0", + "cryptography>=41.0" ] keywords = ["agentfield", "sdk", "agents"] diff --git a/sdk/python/tests/helpers.py b/sdk/python/tests/helpers.py index 49dd9e90..5a257a4f 100644 --- a/sdk/python/tests/helpers.py +++ b/sdk/python/tests/helpers.py @@ -30,6 +30,7 @@ async def register_agent( vc_metadata=None, version: str = "1.0.0", agent_metadata=None, + tags=None, ) -> Tuple[bool, Optional[Dict[str, Any]]]: self.register_calls.append( { @@ -41,6 +42,7 @@ async def register_agent( "vc_metadata": vc_metadata, "version": version, "agent_metadata": agent_metadata, + "tags": tags, } ) return True, {"resolved_base_url": base_url} @@ -106,6 +108,7 @@ class StubAgent: ) reasoners: List[Dict[str, Any]] = field(default_factory=list) skills: List[Dict[str, Any]] = field(default_factory=list) + agent_tags: List[str] = field(default_factory=list) agentfield_connected: bool = True _current_status: AgentStatus = AgentStatus.STARTING callback_candidates: List[str] = field(default_factory=list) @@ -264,6 +267,11 @@ def __init__(self, base_url: str, async_config: Any = None, api_key: Optional[st self.api_base = f"{base_url}/api/v1" self.async_config = async_config self.api_key = api_key + self.did_credentials: Optional[Tuple[str, str]] = None + + def set_did_credentials(self, did: str, private_key_jwk: str) -> bool: + self.did_credentials = (did, private_key_jwk) + return True def _agentfield_client_factory( base_url: str, async_config: Any = None, api_key: Optional[str] = None @@ -403,6 +411,16 @@ def __init__(self, agentfield_server: str, node: str, api_key: Optional[str] = N self.node_id = node self.api_key = api_key self.registered: Dict[str, Any] = {} + self.identity_package = SimpleNamespace( + agent_did=SimpleNamespace( + did=f"did:agent:{node}", + private_key_jwk='{"kty":"OKP","crv":"Ed25519","d":"fake-key"}', + public_key_jwk='{"kty":"OKP","crv":"Ed25519","x":"fake-pub"}', + ), + reasoner_dids={}, + skill_dids={}, + agentfield_server_id="test-server", + ) def register_agent(self, reasoners: List[dict], skills: List[dict]) -> bool: self.registered = {"reasoners": reasoners, "skills": skills} diff --git a/sdk/python/tests/test_agent_networking.py b/sdk/python/tests/test_agent_networking.py index 63b41966..8050ed53 100644 --- a/sdk/python/tests/test_agent_networking.py +++ b/sdk/python/tests/test_agent_networking.py @@ -163,6 +163,9 @@ def test_register_agent_with_did_enables_vc(monkeypatch): assert result is True assert agent.did_enabled is True assert agent.vc_generator.is_enabled() is True + # Verify DID credentials were wired to the HTTP client + assert agent.client.did_credentials is not None + assert agent.client.did_credentials[0] == "did:agent:test-agent" def test_populate_execution_context_with_did(monkeypatch): diff --git a/sdk/python/tests/test_async_execution_manager_paths.py b/sdk/python/tests/test_async_execution_manager_paths.py index ba6ebfa0..f1fb7a67 100644 --- a/sdk/python/tests/test_async_execution_manager_paths.py +++ b/sdk/python/tests/test_async_execution_manager_paths.py @@ -11,8 +11,9 @@ class _DummyResponse: - def __init__(self, payload): + def __init__(self, payload, status=200): self._payload = payload + self.status = status def raise_for_status(self): return None @@ -129,7 +130,8 @@ async def get_session(self): assert session_post.await_count == 1 call = session_post.await_args assert call.args[0] == "http://example/api/v1/execute/async/node.reasoner" - assert call.kwargs["json"] == {"input": {"foo": "bar"}} + import json as json_module + assert json_module.loads(call.kwargs["data"]) == {"input": {"foo": "bar"}} @pytest.mark.asyncio diff --git a/sdk/python/tests/test_client.py b/sdk/python/tests/test_client.py index cd35c60a..73108d89 100644 --- a/sdk/python/tests/test_client.py +++ b/sdk/python/tests/test_client.py @@ -77,7 +77,7 @@ async def aclose(self): def test_execute_sync_injects_run_id(monkeypatch): captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["post"] = (url, headers) return DummyResponse( { @@ -121,7 +121,7 @@ def fake_get(url, headers=None, timeout=None): def test_execute_sync_respects_parent_header(monkeypatch): captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["post"] = headers return DummyResponse( { diff --git a/sdk/python/tests/test_client_auth.py b/sdk/python/tests/test_client_auth.py index 50601065..deb2423d 100644 --- a/sdk/python/tests/test_client_auth.py +++ b/sdk/python/tests/test_client_auth.py @@ -104,7 +104,7 @@ def test_execute_sync_includes_api_key(self, monkeypatch): """execute_sync should include X-API-Key header in requests.""" captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["post_headers"] = headers return DummyResponse( { @@ -142,7 +142,7 @@ def test_execute_sync_no_api_key_when_not_set(self, monkeypatch): """execute_sync should not include X-API-Key when not configured.""" captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["post_headers"] = headers return DummyResponse( { @@ -237,7 +237,7 @@ def test_api_key_merged_with_custom_headers(self, monkeypatch): """API key should be merged with user-provided headers.""" captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["headers"] = headers return DummyResponse( { @@ -277,7 +277,7 @@ def test_custom_header_does_not_override_api_key(self, monkeypatch): """User-provided X-API-Key header should not override configured key.""" captured = {} - def fake_post(url, json, headers, timeout): + def fake_post(url, data=None, json=None, headers=None, timeout=None, **kwargs): captured["headers"] = headers return DummyResponse( { diff --git a/sdk/python/tests/test_connection_manager.py b/sdk/python/tests/test_connection_manager.py index 663a63f5..ab8c6073 100644 --- a/sdk/python/tests/test_connection_manager.py +++ b/sdk/python/tests/test_connection_manager.py @@ -311,6 +311,42 @@ async def capture_state(**kwargs): assert ConnectionState.CONNECTING in states_observed + @pytest.mark.asyncio + async def test_attempt_connection_pending_approval_blocks(self, mock_agent): + """Test that pending_approval status blocks until approved (D1 fix).""" + # Registration returns pending_approval + mock_agent.client.register_agent_with_status = AsyncMock( + return_value=(True, {"status": "pending_approval", "pending_tags": ["sensitive"]}) + ) + mock_agent.agent_tags = ["sensitive"] + + # Mock _wait_for_approval to resolve immediately + mock_agent.agentfield_handler._wait_for_approval = AsyncMock() + + manager = ConnectionManager(mock_agent) + result = await manager._attempt_connection() + + assert result is True + assert manager.state == ConnectionState.CONNECTED + # Verify _wait_for_approval was called + mock_agent.agentfield_handler._wait_for_approval.assert_awaited_once() + + @pytest.mark.asyncio + async def test_attempt_connection_no_pending_approval_does_not_block(self, mock_agent): + """Test that non-pending registration does not call _wait_for_approval.""" + mock_agent.client.register_agent_with_status = AsyncMock( + return_value=(True, {"status": "ready"}) + ) + mock_agent.agentfield_handler._wait_for_approval = AsyncMock() + + manager = ConnectionManager(mock_agent) + result = await manager._attempt_connection() + + assert result is True + assert manager.state == ConnectionState.CONNECTED + # Verify _wait_for_approval was NOT called + mock_agent.agentfield_handler._wait_for_approval.assert_not_awaited() + # Reconnection Loop Tests diff --git a/sdk/python/tests/test_did_auth.py b/sdk/python/tests/test_did_auth.py new file mode 100644 index 00000000..6c80e7d6 --- /dev/null +++ b/sdk/python/tests/test_did_auth.py @@ -0,0 +1,440 @@ +"""Tests for DID authentication module (agentfield/did_auth.py).""" + +import base64 +import hashlib +import json +import time + +import pytest +from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey +from cryptography.hazmat.primitives import serialization + +from agentfield.did_auth import ( + HEADER_CALLER_DID, + HEADER_DID_SIGNATURE, + HEADER_DID_TIMESTAMP, + HEADER_DID_NONCE, + DIDAuthenticator, + _load_ed25519_private_key, + create_did_auth_headers, + sign_request, +) + + +# --------------------------------------------------------------------------- +# Helpers: generate a real Ed25519 key pair in JWK format +# --------------------------------------------------------------------------- + +def _generate_ed25519_jwk(): + """Generate a fresh Ed25519 key pair and return (private_key_jwk_str, public_key_obj, private_key_obj).""" + private_key = Ed25519PrivateKey.generate() + + # Extract raw 32-byte private key seed + raw_private = private_key.private_bytes( + encoding=serialization.Encoding.Raw, + format=serialization.PrivateFormat.Raw, + encryption_algorithm=serialization.NoEncryption(), + ) + + # Extract raw 32-byte public key + raw_public = private_key.public_key().public_bytes( + encoding=serialization.Encoding.Raw, + format=serialization.PublicFormat.Raw, + ) + + # Build JWK (base64url without padding) + d_b64 = base64.urlsafe_b64encode(raw_private).rstrip(b"=").decode("ascii") + x_b64 = base64.urlsafe_b64encode(raw_public).rstrip(b"=").decode("ascii") + + jwk = { + "kty": "OKP", + "crv": "Ed25519", + "d": d_b64, + "x": x_b64, + } + return json.dumps(jwk), private_key.public_key(), private_key + + +@pytest.fixture +def ed25519_jwk(): + """Fixture providing (jwk_str, public_key, private_key).""" + return _generate_ed25519_jwk() + + +@pytest.fixture +def did_string(): + return "did:web:example.com:agents:test-agent" + + +# =========================================================================== +# Tests for _load_ed25519_private_key +# =========================================================================== + +class TestLoadEd25519PrivateKey: + """Tests for _load_ed25519_private_key.""" + + def test_valid_jwk_loads_successfully(self, ed25519_jwk): + jwk_str, _public_key, _private_key = ed25519_jwk + loaded = _load_ed25519_private_key(jwk_str) + assert loaded is not None + # Verify the loaded key can sign + sig = loaded.sign(b"test payload") + assert len(sig) == 64 # Ed25519 signatures are 64 bytes + + def test_valid_jwk_as_dict(self, ed25519_jwk): + """The function should also accept a dict, not just a string.""" + jwk_str, _, _ = ed25519_jwk + jwk_dict = json.loads(jwk_str) + loaded = _load_ed25519_private_key(jwk_dict) + assert loaded is not None + + def test_loaded_key_matches_original(self, ed25519_jwk): + """Signing with loaded key should be verifiable with the original public key.""" + jwk_str, public_key, _ = ed25519_jwk + loaded = _load_ed25519_private_key(jwk_str) + message = b"verify me" + sig = loaded.sign(message) + # If verify fails, it raises InvalidSignature + public_key.verify(sig, message) + + def test_invalid_kty_raises_valueerror(self, ed25519_jwk): + jwk_str, _, _ = ed25519_jwk + jwk = json.loads(jwk_str) + jwk["kty"] = "RSA" + with pytest.raises(ValueError, match="Invalid key type"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_invalid_crv_raises_valueerror(self, ed25519_jwk): + jwk_str, _, _ = ed25519_jwk + jwk = json.loads(jwk_str) + jwk["crv"] = "P-256" + with pytest.raises(ValueError, match="Invalid key type"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_missing_kty_raises_valueerror(self): + jwk = {"crv": "Ed25519", "d": "AAAA"} + with pytest.raises(ValueError, match="Invalid key type"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_missing_crv_raises_valueerror(self): + jwk = {"kty": "OKP", "d": "AAAA"} + with pytest.raises(ValueError, match="Invalid key type"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_missing_d_field_raises_valueerror(self, ed25519_jwk): + jwk_str, _, _ = ed25519_jwk + jwk = json.loads(jwk_str) + del jwk["d"] + with pytest.raises(ValueError, match="Missing 'd'"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_empty_d_field_raises_valueerror(self): + jwk = {"kty": "OKP", "crv": "Ed25519", "d": ""} + with pytest.raises(ValueError, match="Missing 'd'"): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_invalid_base64_d_field_raises(self): + """An invalid base64 value for 'd' that decodes to the wrong number of bytes.""" + jwk = {"kty": "OKP", "crv": "Ed25519", "d": "!!!not-base64!!!"} + with pytest.raises(Exception): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_wrong_length_d_field_raises(self): + """A valid base64 string that decodes to the wrong byte length for Ed25519.""" + # 16 bytes instead of 32 + bad_d = base64.urlsafe_b64encode(b"\x00" * 16).rstrip(b"=").decode() + jwk = {"kty": "OKP", "crv": "Ed25519", "d": bad_d} + with pytest.raises(Exception): + _load_ed25519_private_key(json.dumps(jwk)) + + def test_invalid_json_raises_valueerror(self): + with pytest.raises(ValueError, match="Invalid JWK format"): + _load_ed25519_private_key("{not valid json") + + def test_non_json_string_raises_valueerror(self): + with pytest.raises(ValueError, match="Invalid JWK format"): + _load_ed25519_private_key("just a plain string") + + +# =========================================================================== +# Tests for sign_request +# =========================================================================== + +class TestSignRequest: + """Tests for the sign_request function.""" + + def test_returns_four_element_tuple(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + result = sign_request(b"hello", jwk_str, did_string) + assert isinstance(result, tuple) + assert len(result) == 4 + + def test_signature_is_valid_base64(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + sig_b64, _, _, _ = sign_request(b"body", jwk_str, did_string) + # Should decode without error + decoded = base64.b64decode(sig_b64) + assert len(decoded) == 64 # Ed25519 signature + + def test_timestamp_is_recent(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + before = int(time.time()) + _, timestamp_str, _, _ = sign_request(b"body", jwk_str, did_string) + after = int(time.time()) + ts = int(timestamp_str) + assert before <= ts <= after + + def test_nonce_is_hex_string(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + _, _, nonce, _ = sign_request(b"body", jwk_str, did_string) + assert len(nonce) == 32 # 16 bytes = 32 hex chars + int(nonce, 16) # Should not raise + + def test_did_is_returned_unchanged(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + _, _, _, returned_did = sign_request(b"body", jwk_str, did_string) + assert returned_did == did_string + + def test_signature_verifies_with_public_key(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + body = b"some request body" + sig_b64, timestamp_str, nonce, _ = sign_request(body, jwk_str, did_string) + + # Reconstruct the payload the same way sign_request does + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{timestamp_str}:{nonce}:{body_hash}".encode("utf-8") + + sig_bytes = base64.b64decode(sig_b64) + # verify raises InvalidSignature on failure + public_key.verify(sig_bytes, payload) + + def test_different_bodies_produce_different_signatures(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + sig1, _, _, _ = sign_request(b"body_a", jwk_str, did_string) + sig2, _, _, _ = sign_request(b"body_b", jwk_str, did_string) + # Signatures should differ (different body hash) + assert sig1 != sig2 + + def test_same_body_produces_different_signatures_via_nonce(self, ed25519_jwk, did_string): + """Two calls with the same body should produce different signatures due to nonce.""" + jwk_str, _, _ = ed25519_jwk + sig1, _, nonce1, _ = sign_request(b"same body", jwk_str, did_string) + sig2, _, nonce2, _ = sign_request(b"same body", jwk_str, did_string) + assert nonce1 != nonce2 + assert sig1 != sig2 + + def test_invalid_key_raises(self, did_string): + bad_jwk = json.dumps({"kty": "OKP", "crv": "Ed25519"}) + with pytest.raises(ValueError): + sign_request(b"body", bad_jwk, did_string) + + +# =========================================================================== +# Tests for create_did_auth_headers +# =========================================================================== + +class TestCreateDIDAuthHeaders: + """Tests for the create_did_auth_headers convenience function.""" + + def test_returns_all_four_headers(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + headers = create_did_auth_headers(b"body", jwk_str, did_string) + assert HEADER_CALLER_DID in headers + assert HEADER_DID_SIGNATURE in headers + assert HEADER_DID_TIMESTAMP in headers + assert HEADER_DID_NONCE in headers + + def test_caller_did_matches_input(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + headers = create_did_auth_headers(b"body", jwk_str, did_string) + assert headers[HEADER_CALLER_DID] == did_string + + def test_timestamp_header_is_numeric_string(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + headers = create_did_auth_headers(b"body", jwk_str, did_string) + assert headers[HEADER_DID_TIMESTAMP].isdigit() + + def test_nonce_header_is_hex(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + headers = create_did_auth_headers(b"body", jwk_str, did_string) + nonce = headers[HEADER_DID_NONCE] + assert len(nonce) == 32 + int(nonce, 16) # Should not raise + + +# =========================================================================== +# Tests for DIDAuthenticator +# =========================================================================== + +class TestDIDAuthenticator: + """Tests for the DIDAuthenticator class.""" + + # --- Unconfigured state --- + + def test_default_not_configured(self): + auth = DIDAuthenticator() + assert auth.is_configured is False + + def test_default_did_is_none(self): + auth = DIDAuthenticator() + assert auth.did is None + + def test_unconfigured_sign_headers_returns_empty(self): + auth = DIDAuthenticator() + assert auth.sign_headers(b"body") == {} + + def test_did_only_not_configured(self): + """Providing DID without key should NOT be configured.""" + auth = DIDAuthenticator(did="did:web:example") + assert auth.is_configured is False + + def test_key_only_not_configured(self, ed25519_jwk): + """Providing key without DID should NOT be configured.""" + jwk_str, _, _ = ed25519_jwk + auth = DIDAuthenticator(private_key_jwk=jwk_str) + assert auth.is_configured is False + + def test_invalid_key_not_configured(self): + """Invalid key should leave authenticator unconfigured (logged warning).""" + auth = DIDAuthenticator( + did="did:web:example", + private_key_jwk='{"kty":"RSA"}', + ) + assert auth.is_configured is False + + # --- Configured state --- + + def test_configured_with_valid_credentials(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + auth = DIDAuthenticator(did=did_string, private_key_jwk=jwk_str) + assert auth.is_configured is True + assert auth.did == did_string + + def test_sign_headers_returns_all_headers(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + auth = DIDAuthenticator(did=did_string, private_key_jwk=jwk_str) + headers = auth.sign_headers(b"body content") + assert HEADER_CALLER_DID in headers + assert HEADER_DID_SIGNATURE in headers + assert HEADER_DID_TIMESTAMP in headers + assert HEADER_DID_NONCE in headers + assert headers[HEADER_CALLER_DID] == did_string + + def test_sign_headers_signature_is_verifiable(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + auth = DIDAuthenticator(did=did_string, private_key_jwk=jwk_str) + body = b"test body" + headers = auth.sign_headers(body) + + sig_bytes = base64.b64decode(headers[HEADER_DID_SIGNATURE]) + ts = headers[HEADER_DID_TIMESTAMP] + nonce = headers[HEADER_DID_NONCE] + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + public_key.verify(sig_bytes, payload) + + # --- set_credentials --- + + def test_set_credentials_configures_authenticator(self, ed25519_jwk, did_string): + auth = DIDAuthenticator() + jwk_str, _, _ = ed25519_jwk + result = auth.set_credentials(did_string, jwk_str) + assert result is True + assert auth.is_configured is True + assert auth.did == did_string + + def test_set_credentials_with_invalid_key_returns_false(self): + auth = DIDAuthenticator() + result = auth.set_credentials("did:web:x", '{"kty":"RSA"}') + assert result is False + assert auth.is_configured is False + + def test_set_credentials_replaces_previous(self, did_string): + jwk1, pub1, _ = _generate_ed25519_jwk() + jwk2, pub2, _ = _generate_ed25519_jwk() + + auth = DIDAuthenticator(did="did:old", private_key_jwk=jwk1) + assert auth.did == "did:old" + + auth.set_credentials(did_string, jwk2) + assert auth.did == did_string + # Verify signing uses the new key + body = b"check" + headers = auth.sign_headers(body) + sig_bytes = base64.b64decode(headers[HEADER_DID_SIGNATURE]) + ts = headers[HEADER_DID_TIMESTAMP] + nonce = headers[HEADER_DID_NONCE] + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + pub2.verify(sig_bytes, payload) + + # --- get_auth_info --- + + def test_get_auth_info_unconfigured(self): + auth = DIDAuthenticator() + info = auth.get_auth_info() + assert info["configured"] is False + assert info["did"] is None + + def test_get_auth_info_configured(self, ed25519_jwk, did_string): + jwk_str, _, _ = ed25519_jwk + auth = DIDAuthenticator(did=did_string, private_key_jwk=jwk_str) + info = auth.get_auth_info() + assert info["configured"] is True + assert info["did"] == did_string + + +# =========================================================================== +# Edge cases +# =========================================================================== + +class TestEdgeCases: + """Edge-case tests for body signing.""" + + def test_empty_body(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + body = b"" + sig_b64, ts, nonce, _ = sign_request(body, jwk_str, did_string) + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + sig_bytes = base64.b64decode(sig_b64) + public_key.verify(sig_bytes, payload) + + def test_large_body(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + body = b"x" * (1024 * 1024) # 1 MB + sig_b64, ts, nonce, _ = sign_request(body, jwk_str, did_string) + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + sig_bytes = base64.b64decode(sig_b64) + public_key.verify(sig_bytes, payload) + + def test_non_ascii_body(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + body = "Unicode payload: \u00e9\u00e8\u00ea \u4e16\u754c \U0001f680".encode("utf-8") + sig_b64, ts, nonce, _ = sign_request(body, jwk_str, did_string) + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + sig_bytes = base64.b64decode(sig_b64) + public_key.verify(sig_bytes, payload) + + def test_binary_body(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + body = bytes(range(256)) + sig_b64, ts, nonce, _ = sign_request(body, jwk_str, did_string) + body_hash = hashlib.sha256(body).hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + sig_bytes = base64.b64decode(sig_b64) + public_key.verify(sig_bytes, payload) + + def test_sign_headers_empty_body_via_authenticator(self, ed25519_jwk, did_string): + jwk_str, public_key, _ = ed25519_jwk + auth = DIDAuthenticator(did=did_string, private_key_jwk=jwk_str) + headers = auth.sign_headers(b"") + assert HEADER_DID_SIGNATURE in headers + sig_bytes = base64.b64decode(headers[HEADER_DID_SIGNATURE]) + ts = headers[HEADER_DID_TIMESTAMP] + nonce = headers[HEADER_DID_NONCE] + body_hash = hashlib.sha256(b"").hexdigest() + payload = f"{ts}:{nonce}:{body_hash}".encode("utf-8") + public_key.verify(sig_bytes, payload) diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json index bf3de9ab..518ed847 100644 --- a/sdk/typescript/package-lock.json +++ b/sdk/typescript/package-lock.json @@ -1,13 +1,13 @@ { "name": "@agentfield/sdk", - "version": "0.1.25", + "version": "0.1.41-rc.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@agentfield/sdk", - "version": "0.1.25", - "license": "MIT", + "version": "0.1.41-rc.3", + "license": "Apache-2.0", "dependencies": { "@ai-sdk/anthropic": "^2.0.53", "@ai-sdk/cohere": "^2.0.20", @@ -21,6 +21,7 @@ "axios": "^1.6.2", "dotenv": "^16.4.5", "express": "^4.18.2", + "express-rate-limit": "^8.2.1", "ws": "^8.16.0", "zod": "^3.22.4", "zod-to-json-schema": "^3.25.0" @@ -1990,6 +1991,24 @@ "url": "https://opencollective.com/express" } }, + "node_modules/express-rate-limit": { + "version": "8.2.1", + "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.2.1.tgz", + "integrity": "sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==", + "license": "MIT", + "dependencies": { + "ip-address": "10.0.1" + }, + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://github.com/sponsors/express-rate-limit" + }, + "peerDependencies": { + "express": ">= 4.11" + } + }, "node_modules/fdir": { "version": "6.5.0", "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", @@ -2284,6 +2303,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/ip-address": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.0.1.tgz", + "integrity": "sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, "node_modules/ipaddr.js": { "version": "1.9.1", "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json index 4fb5543d..7813c239 100644 --- a/sdk/typescript/package.json +++ b/sdk/typescript/package.json @@ -37,6 +37,7 @@ "axios": "^1.6.2", "dotenv": "^16.4.5", "express": "^4.18.2", + "express-rate-limit": "^8.2.1", "ws": "^8.16.0", "zod": "^3.22.4", "zod-to-json-schema": "^3.25.0" diff --git a/sdk/typescript/src/agent/Agent.ts b/sdk/typescript/src/agent/Agent.ts index bb351d58..0b148fb8 100644 --- a/sdk/typescript/src/agent/Agent.ts +++ b/sdk/typescript/src/agent/Agent.ts @@ -1,4 +1,5 @@ import express from 'express'; +import rateLimit from 'express-rate-limit'; import type http from 'node:http'; import { randomUUID } from 'node:crypto'; import axios, { AxiosInstance } from 'axios'; @@ -37,6 +38,7 @@ import type { DiscoveryOptions } from '../types/agent.js'; import type { MCPToolRegistration } from '../types/mcp.js'; import { MCPClientRegistry } from '../mcp/MCPClientRegistry.js'; import { MCPToolRegistrar } from '../mcp/MCPToolRegistrar.js'; +import { LocalVerifier } from '../verification/LocalVerifier.js'; class TargetNotFoundError extends Error {} @@ -56,6 +58,8 @@ export class Agent { private readonly memoryWatchers: Array<{ pattern: string; handler: MemoryWatchHandler; scope?: string; scopeId?: string }> = []; private readonly mcpClientRegistry?: MCPClientRegistry; private readonly mcpToolRegistrar?: MCPToolRegistrar; + private readonly localVerifier?: LocalVerifier; + private readonly realtimeValidationFunctions = new Set(); constructor(config: AgentConfig) { const mcp = config.mcp @@ -96,6 +100,16 @@ export class Agent { this.mcpToolRegistrar.registerServers(this.config.mcp.servers); } + // Initialize local verifier for decentralized verification + if (this.config.localVerification && this.config.agentFieldUrl) { + this.localVerifier = new LocalVerifier( + this.config.agentFieldUrl, + this.config.verificationRefreshInterval ?? 300, + 300, + this.config.apiKey, + ); + } + this.registerDefaultRoutes(); } @@ -105,6 +119,9 @@ export class Agent { options?: ReasonerOptions ) { this.reasoners.register(name, handler, options); + if (options?.requireRealtimeValidation) { + this.realtimeValidationFunctions.add(name); + } return this; } @@ -114,6 +131,9 @@ export class Agent { options?: SkillOptions ) { this.skills.register(name, handler, options); + if (options?.requireRealtimeValidation) { + this.realtimeValidationFunctions.add(name); + } return this; } @@ -247,6 +267,19 @@ export class Agent { } await this.registerWithControlPlane(); + + // Perform a blocking initial refresh for local verification before accepting requests + if (this.localVerifier) { + try { + const ok = await this.localVerifier.refresh(); + if (!ok) { + console.warn('[LocalVerifier] Initial refresh partially failed — some verification data may be stale'); + } + } catch (err) { + console.warn('[LocalVerifier] Initial refresh failed:', err); + } + } + const port = this.config.port ?? 8001; const host = this.config.host ?? '0.0.0.0'; // First heartbeat marks the node as starting; subsequent interval sets ready. @@ -411,6 +444,149 @@ export class Agent { res.json(this.skills.all().map((s) => s.name)); }); + // Local verification middleware for execution endpoints + if (this.localVerifier) { + const verifier = this.localVerifier; + const realtimeFunctions = this.realtimeValidationFunctions; + + // Rate limiter for auth endpoints: max 30 attempts per identity per 60s window. + // Uses X-Caller-DID when present so agents behind shared NAT/gateway don't + // exhaust each other's quota. Falls back to IP when no DID is claimed. + const authRateLimiter = rateLimit({ + windowMs: 60_000, + max: 30, + standardHeaders: true, + legacyHeaders: false, + keyGenerator: (req) => { + const callerDID = req.headers['x-caller-did']; + if (typeof callerDID === 'string' && callerDID.length > 0) { + return callerDID; + } + return req.ip ?? 'unknown'; + }, + message: { error: 'rate_limit_exceeded', message: 'Too many authentication attempts. Try again later.' }, + skip: (req) => { + const path = req.path; + if (!path.startsWith('/reasoners/') && !path.startsWith('/skills/') && + !path.startsWith('/execute') && !path.startsWith('/api/v1/reasoners/') && + !path.startsWith('/api/v1/skills/')) { + return true; + } + const parts = path.replace(/^\/+/, '').split('/'); + const funcName = parts[parts.length - 1] ?? ''; + return realtimeFunctions.has(funcName); + }, + }); + this.app.use(authRateLimiter); + + this.app.use(async (req, res, next) => { + const path = req.path; + + // Only verify execution endpoints + if (!path.startsWith('/reasoners/') && !path.startsWith('/skills/') && + !path.startsWith('/execute') && !path.startsWith('/api/v1/reasoners/') && + !path.startsWith('/api/v1/skills/')) { + return next(); + } + + // Extract function name + const parts = path.replace(/^\/+/, '').split('/'); + const funcName = parts[parts.length - 1] ?? ''; + + // Skip for realtime-validated functions + if (realtimeFunctions.has(funcName)) { + return next(); + } + + // Refresh cache if stale + if (verifier.needsRefresh) { + try { + await verifier.refresh(); + } catch (err) { + console.warn('[LocalVerifier] Cache refresh failed:', err); + } + } + + // Extract DID auth headers + const callerDid = req.headers['x-caller-did'] as string | undefined; + const signature = req.headers['x-did-signature'] as string | undefined; + const timestamp = req.headers['x-did-timestamp'] as string | undefined; + const nonce = req.headers['x-did-nonce'] as string | undefined; + + // C4: Require DID authentication — fail closed when callerDid is missing + if (!callerDid) { + return res.status(401).json({ + error: 'did_auth_required', + message: 'DID authentication required', + }); + } + + // Check revocation + if (verifier.checkRevocation(callerDid)) { + return res.status(403).json({ + error: 'did_revoked', + message: `Caller DID ${callerDid} has been revoked`, + }); + } + + // Check registration — reject DIDs not registered with the control plane + if (!verifier.checkRegistration(callerDid)) { + return res.status(403).json({ + error: 'did_not_registered', + message: `Caller DID ${callerDid} is not registered with the control plane`, + }); + } + + // C5: Require signature when callerDid is present + if (!signature) { + return res.status(401).json({ + error: 'signature_required', + message: 'DID signature required', + }); + } + + // Verify signature + if (timestamp) { + const body = Buffer.isBuffer(req.body) ? req.body : Buffer.from(JSON.stringify(req.body)); + const valid = await verifier.verifySignature(callerDid, signature, timestamp, body, nonce); + if (!valid) { + return res.status(401).json({ + error: 'signature_invalid', + message: 'DID signature verification failed', + }); + } + } else { + // Timestamp is required for signature verification + return res.status(401).json({ + error: 'signature_invalid', + message: 'DID signature verification failed: missing timestamp', + }); + } + + // C6: Evaluate access policy after successful signature verification + // Caller tags cannot be resolved at agent-side middleware level (would require + // a control plane lookup). Pass empty array — policies that require specific + // caller tags will not match, which is correct fail-open behavior for + // agent-side verification. The control plane remains the primary policy + // enforcement point with full caller context. + const agentTags = this.config.tags ?? []; + const allowed = verifier.evaluatePolicy( + [], // caller tags (not resolvable without control plane) + agentTags, // target tags (this agent's own tags) + funcName, + typeof req.body === 'object' && req.body !== null ? req.body : {}, + ); + if (!allowed) { + return res.status(403).json({ + error: 'policy_denied', + message: 'Access denied by policy', + }); + } + + next(); + }); + } + this.app.post('/api/v1/reasoners/*', (req, res) => this.executeReasoner(req, res, (req.params as any)[0])); this.app.post('/reasoners/:name', (req, res) => this.executeReasoner(req, res, req.params.name)); @@ -437,7 +613,11 @@ export class Agent { if (err instanceof TargetNotFoundError) { res.status(404).json({ error: err.message }); } else { - res.status(500).json({ error: err?.message ?? 'Execution failed' }); + const body: Record = { error: err?.message ?? 'Execution failed' }; + if (err?.responseData) body.error_details = err.responseData; + // Propagate upstream HTTP status (e.g. 403 from permission middleware) + const statusCode = (err?.status >= 400) ? err.status : 500; + res.status(statusCode).json(body); } } } @@ -457,7 +637,11 @@ export class Agent { if (err instanceof TargetNotFoundError) { res.status(404).json({ error: err.message }); } else { - res.status(500).json({ error: err?.message ?? 'Execution failed' }); + const body: Record = { error: err?.message ?? 'Execution failed' }; + if (err?.responseData) body.error_details = err.responseData; + // Propagate upstream HTTP status (e.g. 403 from permission middleware) + const statusCode = (err?.status >= 400) ? err.status : 500; + res.status(statusCode).json(body); } } } @@ -497,7 +681,11 @@ export class Agent { if (err instanceof TargetNotFoundError) { res.status(404).json({ error: err.message }); } else { - res.status(500).json({ error: err?.message ?? 'Execution failed' }); + const body: Record = { error: err?.message ?? 'Execution failed' }; + if (err?.responseData) body.error_details = err.responseData; + // Propagate upstream HTTP status (e.g. 403 from permission middleware) + const statusCode = (err?.status >= 400) ? err.status : 500; + res.status(statusCode).json(body); } } } @@ -741,25 +929,33 @@ export class Agent { } private reasonerDefinitions() { - return this.reasoners.all().map((r) => ({ - id: r.name, - input_schema: toJsonSchema(r.options?.inputSchema), - output_schema: toJsonSchema(r.options?.outputSchema), - memory_config: r.options?.memoryConfig ?? { - auto_inject: [] as string[], - memory_retention: '', - cache_results: false - }, - tags: r.options?.tags ?? [] - })); + return this.reasoners.all().map((r) => { + const tags = r.options?.tags ?? []; + return { + id: r.name, + input_schema: toJsonSchema(r.options?.inputSchema), + output_schema: toJsonSchema(r.options?.outputSchema), + memory_config: r.options?.memoryConfig ?? { + auto_inject: [] as string[], + memory_retention: '', + cache_results: false + }, + tags, + proposed_tags: tags + }; + }); } private skillDefinitions() { - return this.skills.all().map((s) => ({ - id: s.name, - input_schema: toJsonSchema(s.options?.inputSchema), - tags: s.options?.tags ?? [] - })); + return this.skills.all().map((s) => { + const tags = s.options?.tags ?? []; + return { + id: s.name, + input_schema: toJsonSchema(s.options?.inputSchema), + tags, + proposed_tags: tags + }; + }); } private discoveryPayload(deploymentType: DeploymentType) { @@ -855,7 +1051,12 @@ export class Agent { return result; } catch (err: any) { if (params.respond && params.res) { - params.res.status(500).json({ error: err?.message ?? 'Execution failed' }); + const body: Record = { error: err?.message ?? 'Execution failed' }; + if (err?.responseData) body.error_details = err.responseData; + const statusCode = (err?.status >= 400) + ? err.status + : ((err?.statusCode >= 400) ? err.statusCode : 500); + params.res.status(statusCode).json(body); return; } throw err; @@ -907,7 +1108,12 @@ export class Agent { return result; } catch (err: any) { if (params.respond && params.res) { - params.res.status(500).json({ error: err?.message ?? 'Execution failed' }); + const body: Record = { error: err?.message ?? 'Execution failed' }; + if (err?.responseData) body.error_details = err.responseData; + const statusCode = (err?.status >= 400) + ? err.status + : ((err?.statusCode >= 400) ? err.statusCode : 500); + params.res.status(statusCode).json(body); return; } throw err; @@ -927,16 +1133,27 @@ export class Agent { const publicUrl = this.config.publicUrl ?? `http://${hostForUrl ?? '127.0.0.1'}:${port}`; - await this.agentFieldClient.register({ + const agentTags = this.config.tags ?? []; + const regResponse = await this.agentFieldClient.register({ id: this.config.nodeId, - version: this.config.version, + version: this.config.version ?? '', base_url: publicUrl, public_url: publicUrl, deployment_type: this.config.deploymentType ?? 'long_running', reasoners, - skills + skills, + proposed_tags: agentTags, + tags: agentTags }); + // Handle pending approval state: poll until approved + if (regResponse?.status === 'pending_approval') { + const pendingTags = regResponse.pending_tags ?? []; + console.log(`[AgentField] Node ${this.config.nodeId} registered but awaiting tag approval (pending tags: ${pendingTags.join(', ')})`); + await this.waitForApproval(); + console.log(`[AgentField] Node ${this.config.nodeId} tag approval granted`); + } + // Register with DID system if enabled if (this.config.didEnabled) { try { @@ -945,6 +1162,12 @@ export class Agent { const summary = this.didManager.getIdentitySummary(); console.log(`[DID] Agent registered with DID: ${summary.agentDid}`); console.log(`[DID] Reasoner DIDs: ${summary.reasonerCount}, Skill DIDs: ${summary.skillCount}`); + + // Wire DID credentials to the HTTP client for request signing + const pkg = this.didManager.getIdentityPackage(); + if (pkg?.agentDid?.did && pkg?.agentDid?.privateKeyJwk) { + this.agentFieldClient.setDIDCredentials(pkg.agentDid.did, pkg.agentDid.privateKeyJwk); + } } } catch (didErr) { if (!this.config.devMode) { @@ -961,6 +1184,30 @@ export class Agent { } } + private async waitForApproval(): Promise { + const pollInterval = 5000; // 5 seconds + const timeoutMs = 5 * 60 * 1000; // 5 minutes + const deadline = Date.now() + timeoutMs; + + while (Date.now() < deadline) { + await new Promise(resolve => setTimeout(resolve, pollInterval)); + try { + const node = await this.agentFieldClient.getNode(this.config.nodeId); + const status = node?.lifecycle_status; + if (status && status !== 'pending_approval') { + return; + } + console.log(`[AgentField] Node ${this.config.nodeId} still pending approval...`); + } catch (err) { + console.warn('[AgentField] Polling for approval status failed:', err); + } + } + + throw new Error( + `[AgentField] Node ${this.config.nodeId} approval timed out after ${timeoutMs / 1000}s` + ); + } + private startHeartbeat() { const interval = this.config.heartbeatIntervalMs ?? 30_000; if (interval <= 0) return; diff --git a/sdk/typescript/src/client/AgentFieldClient.ts b/sdk/typescript/src/client/AgentFieldClient.ts index 90e46dcb..10bad49b 100644 --- a/sdk/typescript/src/client/AgentFieldClient.ts +++ b/sdk/typescript/src/client/AgentFieldClient.ts @@ -9,6 +9,7 @@ import type { HealthStatus } from '../types/agent.js'; import { httpAgent, httpsAgent } from '../utils/httpAgents.js'; +import { DIDAuthenticator } from './DIDAuthenticator.js'; export interface ExecutionStatusUpdate { status?: string; @@ -22,6 +23,7 @@ export class AgentFieldClient { private readonly http: AxiosInstance; private readonly config: AgentConfig; private readonly defaultHeaders: Record; + private didAuthenticator: DIDAuthenticator; constructor(config: AgentConfig) { const baseURL = (config.agentFieldUrl ?? 'http://localhost:8080').replace(/\/$/, ''); @@ -38,21 +40,33 @@ this.http = axios.create({ mergedHeaders['X-API-Key'] = config.apiKey; } this.defaultHeaders = this.sanitizeHeaders(mergedHeaders); + this.didAuthenticator = new DIDAuthenticator(config.did, config.privateKeyJwk); } - async register(payload: any) { - await this.http.post('/api/v1/nodes/register', payload, { headers: this.mergeHeaders() }); + async register(payload: any): Promise { + const bodyStr = JSON.stringify(payload); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); + const res = await this.http.post('/api/v1/nodes/register', bodyStr, { + headers: this.mergeHeaders({ 'Content-Type': 'application/json', ...authHeaders }) + }); + return res.data; + } + + async getNode(nodeId: string): Promise { + const res = await this.http.get(`/api/v1/nodes/${encodeURIComponent(nodeId)}`, { + headers: this.mergeHeaders({}) + }); + return res.data; } async heartbeat(status: 'starting' | 'ready' | 'degraded' | 'offline' = 'ready'): Promise { const nodeId = this.config.nodeId; + const bodyStr = JSON.stringify({ status, version: this.config.version ?? '', timestamp: new Date().toISOString() }); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); const res = await this.http.post( `/api/v1/nodes/${nodeId}/heartbeat`, - { - status, - timestamp: new Date().toISOString() - }, - { headers: this.mergeHeaders() } + bodyStr, + { headers: this.mergeHeaders({ 'Content-Type': 'application/json', ...authHeaders }) } ); return res.data as HealthStatus; } @@ -83,14 +97,28 @@ this.http = axios.create({ if (metadata?.agentNodeDid) headers['X-Agent-Node-DID'] = metadata.agentNodeDid; if (metadata?.agentNodeId) headers['X-Agent-Node-ID'] = metadata.agentNodeId; - const res = await this.http.post( - `/api/v1/execute/${target}`, - { - input - }, - { headers: this.mergeHeaders(headers) } - ); - return (res.data?.result as T) ?? res.data; + const bodyStr = JSON.stringify({ input }); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); + try { + const res = await this.http.post( + `/api/v1/execute/${target}`, + bodyStr, + { headers: this.mergeHeaders({ 'Content-Type': 'application/json', ...headers, ...authHeaders }) } + ); + return (res.data?.result as T) ?? res.data; + } catch (err: any) { + // Extract structured error from control plane response (e.g., 403 permission_denied). + const respData = err?.response?.data; + if (respData) { + const status = err.response.status; + const msg = respData.message || respData.error || JSON.stringify(respData); + const enriched = new Error(`execute ${target} failed (${status}): ${msg}`); + (enriched as any).status = status; + (enriched as any).responseData = respData; + throw enriched; + } + throw err; + } } async publishWorkflowEvent(event: { @@ -123,9 +151,11 @@ this.http = axios.create({ duration_ms: event.durationMs }; + const bodyStr = JSON.stringify(payload); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); const request = this.http - .post('/api/v1/workflow/executions/events', payload, { - headers: this.mergeHeaders(), + .post('/api/v1/workflow/executions/events', bodyStr, { + headers: this.mergeHeaders({ 'Content-Type': 'application/json', ...authHeaders }), timeout: this.config.devMode ? 1000 : undefined }) .catch(() => { @@ -149,7 +179,11 @@ this.http = axios.create({ progress: update.progress !== undefined ? Math.round(update.progress) : undefined }; - await this.http.post(`/api/v1/executions/${executionId}/status`, payload, { headers: this.mergeHeaders() }); + const bodyStr = JSON.stringify(payload); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); + await this.http.post(`/api/v1/executions/${executionId}/status`, bodyStr, { + headers: this.mergeHeaders({ 'Content-Type': 'application/json', ...authHeaders }) + }); } async discoverCapabilities(options: DiscoveryOptions = {}): Promise { @@ -317,6 +351,18 @@ this.http = axios.create({ return headers; } + setDIDCredentials(did: string, privateKeyJwk: string): void { + this.didAuthenticator.setCredentials(did, privateKeyJwk); + } + + get didAuthConfigured(): boolean { + return this.didAuthenticator.isConfigured; + } + + getDID(): string | undefined { + return this.didAuthenticator.did; + } + sendNote(message: string, tags: string[], agentNodeId: string, metadata: { runId?: string; executionId?: string; @@ -336,13 +382,16 @@ this.http = axios.create({ }; const executionHeaders = this.buildExecutionHeaders({ ...metadata, agentNodeId }); + const bodyStr = JSON.stringify(payload); + const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr)); const headers = this.mergeHeaders({ - 'content-type': 'application/json', - ...executionHeaders + 'Content-Type': 'application/json', + ...executionHeaders, + ...authHeaders }); const request = axios - .post(`${uiApiBaseUrl}/executions/note`, payload, { + .post(`${uiApiBaseUrl}/executions/note`, bodyStr, { headers, timeout: devMode ? 5000 : 10000, httpAgent, diff --git a/sdk/typescript/src/client/DIDAuthenticator.ts b/sdk/typescript/src/client/DIDAuthenticator.ts new file mode 100644 index 00000000..d0385704 --- /dev/null +++ b/sdk/typescript/src/client/DIDAuthenticator.ts @@ -0,0 +1,94 @@ +import crypto from 'node:crypto'; + +export const HEADER_CALLER_DID = 'X-Caller-DID'; +export const HEADER_DID_SIGNATURE = 'X-DID-Signature'; +export const HEADER_DID_TIMESTAMP = 'X-DID-Timestamp'; +export const HEADER_DID_NONCE = 'X-DID-Nonce'; + +/** + * Ed25519 PKCS#8 DER prefix for wrapping a 32-byte seed into a valid + * PKCS#8 structure that Node.js `crypto.createPrivateKey` can parse. + */ +const ED25519_PKCS8_PREFIX = Buffer.from([ + 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, + 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20 +]); + +interface EdDSAJWK { + kty: string; + crv: string; + d?: string; + x?: string; +} + +export class DIDAuthenticator { + private _did?: string; + private _privateKey?: crypto.KeyObject; + + constructor(did?: string, privateKeyJwk?: string) { + if (did && privateKeyJwk) { + this.setCredentials(did, privateKeyJwk); + } + } + + get isConfigured(): boolean { + return this._did !== undefined && this._privateKey !== undefined; + } + + get did(): string | undefined { + return this._did; + } + + signRequest(body: Buffer | Uint8Array): Record { + if (!this.isConfigured) { + return {}; + } + + const timestamp = Math.floor(Date.now() / 1000).toString(); + const nonce = crypto.randomBytes(16).toString('hex'); + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + const payload = `${timestamp}:${nonce}:${bodyHash}`; + const signature = crypto.sign(null, Buffer.from(payload), this._privateKey!); + const signatureB64 = signature.toString('base64'); + + return { + [HEADER_CALLER_DID]: this._did!, + [HEADER_DID_SIGNATURE]: signatureB64, + [HEADER_DID_TIMESTAMP]: timestamp, + [HEADER_DID_NONCE]: nonce + }; + } + + setCredentials(did: string, privateKeyJwk: string): void { + this._privateKey = parsePrivateKeyJWK(privateKeyJwk); + this._did = did; + } +} + +function parsePrivateKeyJWK(jwkJSON: string): crypto.KeyObject { + let key: EdDSAJWK; + try { + key = JSON.parse(jwkJSON); + } catch { + throw new Error('Invalid JWK format: failed to parse JSON'); + } + + if (key.kty !== 'OKP' || key.crv !== 'Ed25519') { + throw new Error('Invalid key type: expected Ed25519 OKP key'); + } + + if (!key.d) { + throw new Error("Missing 'd' (private key) in JWK"); + } + + const seedBytes = Buffer.from(key.d, 'base64url'); + if (seedBytes.length !== 32) { + throw new Error(`Invalid private key length: expected 32 bytes, got ${seedBytes.length}`); + } + + return crypto.createPrivateKey({ + key: Buffer.concat([ED25519_PKCS8_PREFIX, seedBytes]), + format: 'der', + type: 'pkcs8' + }); +} diff --git a/sdk/typescript/src/did/DidClient.ts b/sdk/typescript/src/did/DidClient.ts index a0f9dd56..855f7027 100644 --- a/sdk/typescript/src/did/DidClient.ts +++ b/sdk/typescript/src/did/DidClient.ts @@ -8,7 +8,7 @@ import { httpAgent, httpsAgent } from '../utils/httpAgents.js'; export interface DIDIdentity { did: string; - privateKeyJwk: string; + privateKeyJwk?: string; publicKeyJwk: string; derivationPath: string; componentType: string; @@ -158,7 +158,7 @@ export class DidClient { private parseIdentityPackage(pkg: any): DIDIdentityPackage { const parseIdentity = (data: any): DIDIdentity => ({ did: data?.did ?? '', - privateKeyJwk: data?.private_key_jwk ?? '', + privateKeyJwk: data?.private_key_jwk, publicKeyJwk: data?.public_key_jwk ?? '', derivationPath: data?.derivation_path ?? '', componentType: data?.component_type ?? '', diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts index aa9b8ec9..4bca243b 100644 --- a/sdk/typescript/src/index.ts +++ b/sdk/typescript/src/index.ts @@ -9,6 +9,7 @@ export * from './memory/MemoryInterface.js'; export * from './memory/MemoryClient.js'; export * from './memory/MemoryEventClient.js'; export * from './workflow/WorkflowReporter.js'; +export * from './client/DIDAuthenticator.js'; export * from './did/DidClient.js'; export * from './did/DidInterface.js'; export * from './did/DidManager.js'; diff --git a/sdk/typescript/src/types/agent.ts b/sdk/typescript/src/types/agent.ts index a54868be..18b4e73b 100644 --- a/sdk/typescript/src/types/agent.ts +++ b/sdk/typescript/src/types/agent.ts @@ -21,8 +21,16 @@ export interface AgentConfig { heartbeatIntervalMs?: number; defaultHeaders?: Record; apiKey?: string; + did?: string; + privateKeyJwk?: string; mcp?: MCPConfig; deploymentType?: DeploymentType; + /** Enable decentralized local verification of incoming DID signatures. */ + localVerification?: boolean; + /** Cache refresh interval for local verification in seconds (default: 300). */ + verificationRefreshInterval?: number; + /** Agent-level tags for tag-based authorization policies. */ + tags?: string[]; } export interface AIConfig { diff --git a/sdk/typescript/src/types/reasoner.ts b/sdk/typescript/src/types/reasoner.ts index df4c693b..4d278e0f 100644 --- a/sdk/typescript/src/types/reasoner.ts +++ b/sdk/typescript/src/types/reasoner.ts @@ -17,4 +17,6 @@ export interface ReasonerOptions { outputSchema?: any; trackWorkflow?: boolean; memoryConfig?: any; + /** Force control-plane verification instead of local verification for this reasoner. */ + requireRealtimeValidation?: boolean; } diff --git a/sdk/typescript/src/types/skill.ts b/sdk/typescript/src/types/skill.ts index 29745b3c..c83f550a 100644 --- a/sdk/typescript/src/types/skill.ts +++ b/sdk/typescript/src/types/skill.ts @@ -16,4 +16,6 @@ export interface SkillOptions { description?: string; inputSchema?: any; outputSchema?: any; + /** Force control-plane verification instead of local verification for this skill. */ + requireRealtimeValidation?: boolean; } diff --git a/sdk/typescript/src/verification/LocalVerifier.ts b/sdk/typescript/src/verification/LocalVerifier.ts new file mode 100644 index 00000000..8c2bb927 --- /dev/null +++ b/sdk/typescript/src/verification/LocalVerifier.ts @@ -0,0 +1,331 @@ +/** + * Local verification for AgentField SDK (TypeScript). + * + * Provides decentralized verification of incoming requests by caching policies, + * revocation lists, and the admin's Ed25519 public key from the control plane. + */ + +import { createHash } from 'node:crypto'; +import axios, { type AxiosInstance } from 'axios'; + +export interface PolicyEntry { + name: string; + caller_tags: string[]; + target_tags: string[]; + allow_functions: string[]; + deny_functions: string[]; + constraints: Record; + action: string; + priority: number; + enabled?: boolean; +} + +export interface ConstraintEntry { + operator: string; + value: number; +} + +export class LocalVerifier { + private readonly agentFieldUrl: string; + private readonly refreshInterval: number; + private readonly timestampWindow: number; + private readonly apiKey?: string; + + private policies: PolicyEntry[] = []; + private revokedDids: Set = new Set(); + private registeredDids: Set = new Set(); + private adminPublicKeyBytes: Uint8Array | null = null; + private issuerDid: string | null = null; + private lastRefresh = 0; + private initialized = false; + + constructor( + agentFieldUrl: string, + refreshInterval = 300, + timestampWindow = 300, + apiKey?: string, + ) { + this.agentFieldUrl = agentFieldUrl.replace(/\/+$/, ''); + this.refreshInterval = refreshInterval; + this.timestampWindow = timestampWindow; + this.apiKey = apiKey; + } + + get needsRefresh(): boolean { + return Date.now() / 1000 - this.lastRefresh > this.refreshInterval; + } + + async refresh(): Promise { + const headers: Record = {}; + if (this.apiKey) { + headers['X-API-Key'] = this.apiKey; + } + + let success = true; + + // Fetch policies + try { + const resp = await axios.get(`${this.agentFieldUrl}/api/v1/policies`, { + headers, + timeout: 10_000, + }); + if (resp.status !== 200) { + success = false; + } else { + this.policies = resp.data?.policies ?? []; + } + } catch { + success = false; + } + + // Fetch revocations + try { + const resp = await axios.get(`${this.agentFieldUrl}/api/v1/revocations`, { + headers, + timeout: 10_000, + }); + if (resp.status !== 200) { + success = false; + } else { + this.revokedDids = new Set(resp.data?.revoked_dids ?? []); + } + } catch { + success = false; + } + + // Fetch registered DIDs + try { + const resp = await axios.get(`${this.agentFieldUrl}/api/v1/registered-dids`, { + headers, + timeout: 10_000, + }); + if (resp.status !== 200) { + success = false; + } else { + this.registeredDids = new Set(resp.data?.registered_dids ?? []); + } + } catch { + success = false; + } + + // Fetch admin public key + try { + const resp = await axios.get(`${this.agentFieldUrl}/api/v1/admin/public-key`, { + headers, + timeout: 10_000, + }); + if (resp.status !== 200) { + success = false; + } else { + const jwk = resp.data?.public_key_jwk; + this.issuerDid = resp.data?.issuer_did ?? null; + + if (jwk?.x) { + // Decode base64url public key (Node 15.7+ supports 'base64url' natively) + this.adminPublicKeyBytes = new Uint8Array(Buffer.from(jwk.x, 'base64url')); + } + } + } catch { + success = false; + } + + if (success) { + this.lastRefresh = Date.now() / 1000; + this.initialized = true; + } + + return success; + } + + checkRevocation(callerDid: string): boolean { + return this.revokedDids.has(callerDid); + } + + /** + * Check if a caller DID is registered with the control plane. + * Returns true if registered (known), false if unknown. + * When the cache is empty (not yet loaded), returns true to avoid + * blocking requests before the first refresh completes. + */ + checkRegistration(callerDid: string): boolean { + if (this.registeredDids.size === 0) { + return true; // Cache not populated yet — allow + } + return this.registeredDids.has(callerDid); + } + + /** + * Resolve the public key bytes from a DID. + * + * For did:key, the public key is self-contained in the identifier: + * did:key:z + * + * For other DID methods, falls back to the admin public key. + */ + private resolvePublicKey(callerDid: string): Uint8Array | null { + if (callerDid.startsWith('did:key:z')) { + try { + const encoded = callerDid.slice('did:key:z'.length); + const decoded = Buffer.from(encoded, 'base64url'); + // Verify Ed25519 multicodec prefix: 0xed, 0x01 + if (decoded.length >= 34 && decoded[0] === 0xed && decoded[1] === 0x01) { + return new Uint8Array(decoded.subarray(2, 34)); + } + return null; + } catch { + return null; + } + } + + // Fallback: use admin public key for non-did:key methods + return this.adminPublicKeyBytes; + } + + async verifySignature( + callerDid: string, + signatureB64: string, + timestamp: string, + body: Buffer, + nonce?: string, + ): Promise { + // Validate timestamp window + const ts = parseInt(timestamp, 10); + if (isNaN(ts)) return false; + + const now = Math.floor(Date.now() / 1000); + if (Math.abs(now - ts) > this.timestampWindow) return false; + + // Resolve public key from the caller's DID + const publicKeyBytes = this.resolvePublicKey(callerDid); + if (!publicKeyBytes || publicKeyBytes.length !== 32) { + return false; + } + + try { + const { createPublicKey, verify } = await import('node:crypto'); + + // Reconstruct the signed payload: "{timestamp}[:{nonce}]:{sha256(body)}" + // Must match the format used by SDK signing (DIDAuthenticator) + const bodyHash = createHash('sha256').update(body).digest('hex'); + const payloadStr = nonce + ? `${timestamp}:${nonce}:${bodyHash}` + : `${timestamp}:${bodyHash}`; + const payload = Buffer.from(payloadStr, 'utf-8'); + + // Decode the signature + const signatureBytes = Buffer.from(signatureB64, 'base64'); + + // Create Ed25519 public key object + const publicKey = createPublicKey({ + key: Buffer.concat([ + // Ed25519 DER prefix for a 32-byte public key + Buffer.from('302a300506032b6570032100', 'hex'), + Buffer.from(publicKeyBytes), + ]), + format: 'der', + type: 'spki', + }); + + return verify(null, payload, publicKey, signatureBytes); + } catch { + return false; + } + } + + evaluatePolicy( + callerTags: string[], + targetTags: string[], + functionName: string, + inputParams?: Record, + ): boolean { + if (!this.policies || this.policies.length === 0) { + return false; // No policies — fail closed + } + + // Sort by priority descending + const sorted = [...this.policies].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0)); + + for (const policy of sorted) { + if (policy.enabled === false) continue; + + // Check caller tags match + if (policy.caller_tags?.length > 0) { + if (!policy.caller_tags.some((t) => callerTags.includes(t))) continue; + } + + // Check target tags match + if (policy.target_tags?.length > 0) { + if (!policy.target_tags.some((t) => targetTags.includes(t))) continue; + } + + // Check deny functions first + if (policy.deny_functions?.length > 0 && functionMatches(functionName, policy.deny_functions)) { + return false; + } + + // Check allow functions + if (policy.allow_functions?.length > 0 && !functionMatches(functionName, policy.allow_functions)) { + continue; + } + + // Check constraints + if (policy.constraints && inputParams) { + if (!evaluateConstraints(policy.constraints, inputParams)) { + return false; + } + } + + const action = policy.action || 'allow'; + return action === 'allow'; + } + + // No matching policy — allow by default. + // Agent-side verification cannot resolve caller tags, so policies requiring + // specific caller tags will never match here. The DID signature verification + // is the primary security gate. The control plane enforces full tag-based + // policy with caller context. + return true; + } +} + +function functionMatches(name: string, patterns: string[]): boolean { + for (const pattern of patterns) { + if (pattern === '*') return true; + if (pattern.endsWith('*') && name.startsWith(pattern.slice(0, -1))) return true; + if (pattern.startsWith('*') && name.endsWith(pattern.slice(1))) return true; + if (name === pattern) return true; + } + return false; +} + +function evaluateConstraints( + constraints: Record, + inputParams: Record, +): boolean { + for (const [paramName, constraint] of Object.entries(constraints)) { + if (!(paramName in inputParams)) continue; + + const value = Number(inputParams[paramName]); + const threshold = Number(constraint.value); + if (isNaN(value) || isNaN(threshold)) return false; + + switch (constraint.operator) { + case '<=': + if (value > threshold) return false; + break; + case '>=': + if (value < threshold) return false; + break; + case '<': + if (value >= threshold) return false; + break; + case '>': + if (value <= threshold) return false; + break; + case '==': + if (Math.abs(value - threshold) > 1e-9) return false; + break; + } + } + return true; +} diff --git a/sdk/typescript/tests/did_auth.test.ts b/sdk/typescript/tests/did_auth.test.ts new file mode 100644 index 00000000..aa7a45d0 --- /dev/null +++ b/sdk/typescript/tests/did_auth.test.ts @@ -0,0 +1,381 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import crypto from 'node:crypto'; +import { + DIDAuthenticator, + HEADER_CALLER_DID, + HEADER_DID_SIGNATURE, + HEADER_DID_TIMESTAMP, + HEADER_DID_NONCE +} from '../src/client/DIDAuthenticator.js'; + +/** + * Generate a deterministic Ed25519 keypair from a 32-byte seed and return + * the JWK string (with "d" and "x" in base64url) plus the public KeyObject + * for verification. + */ +function generateTestKeypair(seed: Buffer) { + const pkcs8Prefix = Buffer.from([ + 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, + 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20 + ]); + const privateKey = crypto.createPrivateKey({ + key: Buffer.concat([pkcs8Prefix, seed]), + format: 'der', + type: 'pkcs8' + }); + const publicKey = crypto.createPublicKey(privateKey); + + // Export raw public key bytes (32 bytes for Ed25519) + const pubRaw = publicKey.export({ type: 'spki', format: 'der' }); + // SPKI DER for Ed25519: 12-byte prefix + 32-byte key + const pubBytes = pubRaw.subarray(pubRaw.length - 32); + + const jwk = JSON.stringify({ + kty: 'OKP', + crv: 'Ed25519', + d: seed.toString('base64url'), + x: pubBytes.toString('base64url') + }); + + return { jwk, privateKey, publicKey, pubBytes }; +} + +// Deterministic 32-byte seed for all tests +const TEST_SEED = Buffer.alloc(32, 0); +TEST_SEED[0] = 0xde; +TEST_SEED[1] = 0xad; +TEST_SEED[31] = 0x01; + +const TEST_DID = 'did:web:localhost%3A8080:agents:test-agent'; + +describe('DIDAuthenticator', () => { + const { jwk: testJwk, publicKey: testPublicKey } = generateTestKeypair(TEST_SEED); + + describe('constructor and configuration', () => { + it('is not configured when constructed without arguments', () => { + const auth = new DIDAuthenticator(); + expect(auth.isConfigured).toBe(false); + expect(auth.did).toBeUndefined(); + }); + + it('is configured when constructed with valid credentials', () => { + const auth = new DIDAuthenticator(TEST_DID, testJwk); + expect(auth.isConfigured).toBe(true); + expect(auth.did).toBe(TEST_DID); + }); + + it('configures via setCredentials after construction', () => { + const auth = new DIDAuthenticator(); + expect(auth.isConfigured).toBe(false); + + auth.setCredentials(TEST_DID, testJwk); + expect(auth.isConfigured).toBe(true); + expect(auth.did).toBe(TEST_DID); + }); + }); + + describe('signRequest — unconfigured', () => { + it('returns empty object when not configured', () => { + const auth = new DIDAuthenticator(); + const headers = auth.signRequest(Buffer.from('{"test":true}')); + expect(headers).toEqual({}); + }); + }); + + describe('signRequest — signature correctness', () => { + let auth: DIDAuthenticator; + const FIXED_TIMESTAMP = 1738800000; + + beforeEach(() => { + auth = new DIDAuthenticator(TEST_DID, testJwk); + vi.spyOn(Date, 'now').mockReturnValue(FIXED_TIMESTAMP * 1000); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('returns all four required headers', () => { + const body = Buffer.from('{"input":"hello"}'); + const headers = auth.signRequest(body); + + expect(headers).toHaveProperty(HEADER_CALLER_DID); + expect(headers).toHaveProperty(HEADER_DID_SIGNATURE); + expect(headers).toHaveProperty(HEADER_DID_TIMESTAMP); + expect(headers).toHaveProperty(HEADER_DID_NONCE); + expect(Object.keys(headers)).toHaveLength(4); + }); + + it('sets correct header names matching Go SDK constants', () => { + expect(HEADER_CALLER_DID).toBe('X-Caller-DID'); + expect(HEADER_DID_SIGNATURE).toBe('X-DID-Signature'); + expect(HEADER_DID_TIMESTAMP).toBe('X-DID-Timestamp'); + }); + + it('sets X-Caller-DID to the configured DID', () => { + const headers = auth.signRequest(Buffer.from('{}')); + expect(headers[HEADER_CALLER_DID]).toBe(TEST_DID); + }); + + it('sets X-DID-Timestamp to Unix seconds (not milliseconds)', () => { + const headers = auth.signRequest(Buffer.from('{}')); + const ts = Number(headers[HEADER_DID_TIMESTAMP]); + expect(ts).toBe(FIXED_TIMESTAMP); + // Must be seconds, not milliseconds + expect(ts).toBeLessThan(10_000_000_000); + }); + + it('produces a signature verifiable with the corresponding public key', () => { + const body = Buffer.from('{"target":"agent-b.greet","input":{"name":"alice"}}'); + const headers = auth.signRequest(body); + + // Reconstruct the exact payload the server would build + const timestamp = headers[HEADER_DID_TIMESTAMP]; + const nonce = headers[HEADER_DID_NONCE]; + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + const expectedPayload = `${timestamp}:${nonce}:${bodyHash}`; + + // Decode signature from standard base64 + const sigBytes = Buffer.from(headers[HEADER_DID_SIGNATURE], 'base64'); + + // Verify using the public key — this is exactly what the server does + const valid = crypto.verify(null, Buffer.from(expectedPayload), testPublicKey, sigBytes); + expect(valid).toBe(true); + }); + + it('payload format is "{timestamp}:{nonce}:{lowercase_hex_sha256}" matching Go fmt.Sprintf("%s:%s:%x")', () => { + const body = Buffer.from('{"data":"test"}'); + const headers = auth.signRequest(body); + + const timestamp = headers[HEADER_DID_TIMESTAMP]; + const nonce = headers[HEADER_DID_NONCE]; + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + + // Verify the hash is lowercase hex, 64 chars (256 bits) + expect(bodyHash).toMatch(/^[0-9a-f]{64}$/); + + // Verify the nonce is hex-encoded 16 bytes (32 hex chars) + expect(nonce).toMatch(/^[0-9a-f]{32}$/); + + // Verify the full payload matches the Go format + const expectedPayload = `${timestamp}:${nonce}:${bodyHash}`; + + // Decode and verify signature against this exact payload + const sigBytes = Buffer.from(headers[HEADER_DID_SIGNATURE], 'base64'); + const valid = crypto.verify(null, Buffer.from(expectedPayload), testPublicKey, sigBytes); + expect(valid).toBe(true); + }); + + it('signature uses standard base64 encoding (not base64url)', () => { + // Sign many different bodies to increase chance of hitting +, /, = chars + // that distinguish standard base64 from base64url + const bodies = Array.from({ length: 20 }, (_, i) => + Buffer.from(JSON.stringify({ i, padding: 'x'.repeat(i * 7) })) + ); + + for (const body of bodies) { + const headers = auth.signRequest(body); + const sig = headers[HEADER_DID_SIGNATURE]; + + // Standard base64 may contain +, /, = + // base64url would use -, _ instead + // Ed25519 signatures are 64 bytes → 88 base64 chars (with padding) + expect(sig).toMatch(/^[A-Za-z0-9+/]+=*$/); + expect(Buffer.from(sig, 'base64')).toHaveLength(64); + + // Verify it's NOT base64url (would decode differently if it were) + const fromStd = Buffer.from(sig, 'base64'); + const fromUrl = Buffer.from(sig, 'base64url'); + // If they decode to same bytes, the signature didn't contain +/= chars. + // But the encoding itself must be standard base64 (decodable as such). + expect(fromStd).toHaveLength(64); + // And it must verify + const timestamp = headers[HEADER_DID_TIMESTAMP]; + const nonce = headers[HEADER_DID_NONCE]; + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + const payload = `${timestamp}:${nonce}:${bodyHash}`; + expect(crypto.verify(null, Buffer.from(payload), testPublicKey, fromStd)).toBe(true); + } + }); + + it('produces deterministic signatures for same nonce (Ed25519 is deterministic)', () => { + const fixedNonce = Buffer.alloc(16, 0xab); + const randomBytesSpy = vi.spyOn(crypto, 'randomBytes').mockReturnValue(fixedNonce as any); + + const body = Buffer.from('{"deterministic":"test"}'); + const h1 = auth.signRequest(body); + const h2 = auth.signRequest(body); + expect(h1[HEADER_DID_SIGNATURE]).toBe(h2[HEADER_DID_SIGNATURE]); + expect(h1[HEADER_DID_TIMESTAMP]).toBe(h2[HEADER_DID_TIMESTAMP]); + expect(h1[HEADER_DID_NONCE]).toBe(h2[HEADER_DID_NONCE]); + + randomBytesSpy.mockRestore(); + }); + + it('different bodies produce different signatures', () => { + const h1 = auth.signRequest(Buffer.from('{"a":1}')); + const h2 = auth.signRequest(Buffer.from('{"a":2}')); + expect(h1[HEADER_DID_SIGNATURE]).not.toBe(h2[HEADER_DID_SIGNATURE]); + }); + + it('different timestamps produce different signatures', () => { + const body = Buffer.from('{"same":"body"}'); + + vi.spyOn(Date, 'now').mockReturnValue(1000000 * 1000); + const h1 = auth.signRequest(body); + + vi.spyOn(Date, 'now').mockReturnValue(2000000 * 1000); + const h2 = auth.signRequest(body); + + expect(h1[HEADER_DID_SIGNATURE]).not.toBe(h2[HEADER_DID_SIGNATURE]); + expect(h1[HEADER_DID_TIMESTAMP]).not.toBe(h2[HEADER_DID_TIMESTAMP]); + }); + }); + + describe('cross-SDK compatibility', () => { + /** + * This test manually replicates the Go SDK signing algorithm step-by-step: + * timestamp := strconv.FormatInt(time.Now().Unix(), 10) + * nonce := hex.EncodeToString(randomBytes(16)) + * bodyHash := sha256.Sum256(body) + * payload := fmt.Sprintf("%s:%s:%x", timestamp, nonce, bodyHash) + * signature := ed25519.Sign(privateKey, []byte(payload)) + * signatureB64 := base64.StdEncoding.EncodeToString(signature) + * + * Then verifies the TS DIDAuthenticator produces an identical signature. + */ + it('produces byte-identical signatures to Go SDK algorithm for same key, body, timestamp, and nonce', () => { + const FIXED_TS = 1738796400; + vi.spyOn(Date, 'now').mockReturnValue(FIXED_TS * 1000); + + const fixedNonce = Buffer.alloc(16, 0xca); + vi.spyOn(crypto, 'randomBytes').mockReturnValue(fixedNonce as any); + + const auth = new DIDAuthenticator(TEST_DID, testJwk); + const body = Buffer.from('{"target":"other-agent.skill","input":{"data":"test"}}'); + + // --- Replicate Go SDK signing manually --- + const timestamp = String(FIXED_TS); + const nonce = fixedNonce.toString('hex'); + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + const goPayload = `${timestamp}:${nonce}:${bodyHash}`; + // Sign with the same private key + const { privateKey } = generateTestKeypair(TEST_SEED); + const goSignature = crypto.sign(null, Buffer.from(goPayload), privateKey); + const goSignatureB64 = goSignature.toString('base64'); + + // --- Get TS SDK result --- + const headers = auth.signRequest(body); + + // --- Assert byte-identical --- + expect(headers[HEADER_DID_SIGNATURE]).toBe(goSignatureB64); + expect(headers[HEADER_DID_TIMESTAMP]).toBe(timestamp); + expect(headers[HEADER_DID_NONCE]).toBe(nonce); + expect(headers[HEADER_CALLER_DID]).toBe(TEST_DID); + + vi.restoreAllMocks(); + }); + + it('signature verifiable by server-side algorithm (ed25519.Verify on payload bytes)', () => { + const FIXED_TS = 1706123456; + vi.spyOn(Date, 'now').mockReturnValue(FIXED_TS * 1000); + + const auth = new DIDAuthenticator(TEST_DID, testJwk); + const body = Buffer.from('{"input":{"message":"hello world"}}'); + const headers = auth.signRequest(body); + + // Server-side verification steps (from middleware/did_auth.go): + // 1. Read timestamp and nonce from headers + const timestamp = headers[HEADER_DID_TIMESTAMP]; + const nonce = headers[HEADER_DID_NONCE]; + // 2. Hash body bytes + const bodyHash = crypto.createHash('sha256').update(body).digest('hex'); + // 3. Build payload (with nonce when present, matching server logic) + const payload = `${timestamp}:${nonce}:${bodyHash}`; + // 4. Decode signature from base64 (StdEncoding) + const sigBytes = Buffer.from(headers[HEADER_DID_SIGNATURE], 'base64'); + // 5. Verify with public key + const { publicKey } = generateTestKeypair(TEST_SEED); + const valid = crypto.verify(null, Buffer.from(payload), publicKey, sigBytes); + + expect(valid).toBe(true); + + vi.restoreAllMocks(); + }); + }); + + describe('JWK parsing', () => { + it('rejects invalid JSON', () => { + expect(() => new DIDAuthenticator(TEST_DID, 'not-json')).toThrow('Invalid JWK format'); + }); + + it('rejects non-Ed25519 key type', () => { + const jwk = JSON.stringify({ kty: 'RSA', crv: 'Ed25519', d: TEST_SEED.toString('base64url') }); + expect(() => new DIDAuthenticator(TEST_DID, jwk)).toThrow('expected Ed25519 OKP key'); + }); + + it('rejects wrong curve', () => { + const jwk = JSON.stringify({ kty: 'OKP', crv: 'X25519', d: TEST_SEED.toString('base64url') }); + expect(() => new DIDAuthenticator(TEST_DID, jwk)).toThrow('expected Ed25519 OKP key'); + }); + + it('rejects missing d field', () => { + const jwk = JSON.stringify({ kty: 'OKP', crv: 'Ed25519' }); + expect(() => new DIDAuthenticator(TEST_DID, jwk)).toThrow("Missing 'd'"); + }); + + it('rejects wrong-length private key', () => { + const shortSeed = Buffer.alloc(16, 0xab); + const jwk = JSON.stringify({ kty: 'OKP', crv: 'Ed25519', d: shortSeed.toString('base64url') }); + expect(() => new DIDAuthenticator(TEST_DID, jwk)).toThrow('expected 32 bytes'); + }); + + it('accepts base64url-encoded d field (with and without padding)', () => { + // Without padding (standard for JWK per RFC 7517) + const noPad = TEST_SEED.toString('base64url').replace(/=+$/, ''); + const jwkNoPad = JSON.stringify({ kty: 'OKP', crv: 'Ed25519', d: noPad }); + expect(() => new DIDAuthenticator(TEST_DID, jwkNoPad)).not.toThrow(); + + // With padding (some implementations add it) + const withPad = TEST_SEED.toString('base64url'); + const jwkWithPad = JSON.stringify({ kty: 'OKP', crv: 'Ed25519', d: withPad }); + expect(() => new DIDAuthenticator(TEST_DID, jwkWithPad)).not.toThrow(); + }); + }); + + describe('AgentFieldClient integration', () => { + /** + * Verifies that DID auth headers flow through AgentFieldClient.execute(). + * Uses the actual client with a mocked axios to capture outgoing headers. + */ + it('execute() attaches DID auth headers when credentials are configured', async () => { + // Dynamic import to avoid hoisting issues with vi.mock + const { AgentFieldClient } = await import('../src/client/AgentFieldClient.js'); + + // Create client with DID credentials + const client = new AgentFieldClient({ + nodeId: 'test-agent', + agentFieldUrl: 'http://localhost:8080', + did: TEST_DID, + privateKeyJwk: testJwk + }); + + expect(client.didAuthConfigured).toBe(true); + expect(client.getDID()).toBe(TEST_DID); + }); + + it('setDIDCredentials enables auth after construction', async () => { + const { AgentFieldClient } = await import('../src/client/AgentFieldClient.js'); + + const client = new AgentFieldClient({ + nodeId: 'test-agent', + agentFieldUrl: 'http://localhost:8080' + }); + + expect(client.didAuthConfigured).toBe(false); + client.setDIDCredentials(TEST_DID, testJwk); + expect(client.didAuthConfigured).toBe(true); + expect(client.getDID()).toBe(TEST_DID); + }); + }); +}); diff --git a/sdk/typescript/tests/header-forwarding.test.ts b/sdk/typescript/tests/header-forwarding.test.ts index 7f5f00a5..e485ff00 100644 --- a/sdk/typescript/tests/header-forwarding.test.ts +++ b/sdk/typescript/tests/header-forwarding.test.ts @@ -42,12 +42,13 @@ describe('header forwarding', () => { expect(axiosInstance.post).toHaveBeenCalledWith( '/api/v1/execute/test-target', - { input: { foo: 'bar' } }, + JSON.stringify({ input: { foo: 'bar' } }), { - headers: { + headers: expect.objectContaining({ Authorization: 'Bearer tenant-token', + 'Content-Type': 'application/json', 'X-Run-ID': 'run-123' - } + }) } ); }); diff --git a/sdk/typescript/tests/local_verifier.test.ts b/sdk/typescript/tests/local_verifier.test.ts new file mode 100644 index 00000000..4d406a13 --- /dev/null +++ b/sdk/typescript/tests/local_verifier.test.ts @@ -0,0 +1,268 @@ +import { describe, it, expect, beforeEach } from 'vitest'; +import { LocalVerifier, type PolicyEntry } from '../src/verification/LocalVerifier.js'; + +describe('LocalVerifier', () => { + describe('checkRevocation', () => { + it('returns false when DID is not revoked', () => { + const verifier = new LocalVerifier('http://localhost:8080'); + // revokedDids is empty by default + expect(verifier.checkRevocation('did:web:example.com:agents:a')).toBe(false); + }); + + it('returns true when DID is revoked', () => { + const verifier = new LocalVerifier('http://localhost:8080'); + // Access private field for testing via refresh simulation + (verifier as any).revokedDids = new Set(['did:web:example.com:agents:revoked']); + expect(verifier.checkRevocation('did:web:example.com:agents:revoked')).toBe(true); + }); + }); + + describe('checkRegistration', () => { + it('returns true when cache is empty (not yet loaded)', () => { + const verifier = new LocalVerifier('http://localhost:8080'); + expect(verifier.checkRegistration('did:web:example.com:agents:any')).toBe(true); + }); + + it('returns true when DID is in registered set', () => { + const verifier = new LocalVerifier('http://localhost:8080'); + (verifier as any).registeredDids = new Set(['did:web:example.com:agents:a']); + expect(verifier.checkRegistration('did:web:example.com:agents:a')).toBe(true); + }); + + it('returns false when DID is not in registered set', () => { + const verifier = new LocalVerifier('http://localhost:8080'); + (verifier as any).registeredDids = new Set(['did:web:example.com:agents:a']); + expect(verifier.checkRegistration('did:web:example.com:agents:unknown')).toBe(false); + }); + }); + + describe('needsRefresh', () => { + it('returns true when never refreshed', () => { + const verifier = new LocalVerifier('http://localhost:8080', 300); + expect(verifier.needsRefresh).toBe(true); + }); + + it('returns false after recent refresh', () => { + const verifier = new LocalVerifier('http://localhost:8080', 300); + (verifier as any).lastRefresh = Date.now() / 1000; + expect(verifier.needsRefresh).toBe(false); + }); + + it('returns true after refresh interval expires', () => { + const verifier = new LocalVerifier('http://localhost:8080', 300); + (verifier as any).lastRefresh = Date.now() / 1000 - 301; + expect(verifier.needsRefresh).toBe(true); + }); + }); + + describe('evaluatePolicy', () => { + let verifier: LocalVerifier; + + beforeEach(() => { + verifier = new LocalVerifier('http://localhost:8080'); + }); + + it('returns false (fail-closed) when no policies exist', () => { + (verifier as any).policies = []; + expect(verifier.evaluatePolicy([], ['tier:internal'], 'get_data')).toBe(false); + }); + + it('allows when policy matches caller and target tags', () => { + const policy: PolicyEntry = { + name: 'internal-access', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'get_data')).toBe(true); + }); + + it('denies when policy action is deny', () => { + const policy: PolicyEntry = { + name: 'block-external', + caller_tags: ['tier:external'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'deny', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy(['tier:external'], ['tier:internal'], 'get_data')).toBe(false); + }); + + it('denies when function is in deny_functions', () => { + const policy: PolicyEntry = { + name: 'deny-admin', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: ['admin_*'], + constraints: {}, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'admin_delete')).toBe(false); + }); + + it('skips disabled policies', () => { + const policy: PolicyEntry = { + name: 'disabled', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'deny', + priority: 10, + enabled: false, + }; + (verifier as any).policies = [policy]; + + // No active policy matches, so default allow + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'get_data')).toBe(true); + }); + + it('respects priority ordering (higher priority wins)', () => { + const denyPolicy: PolicyEntry = { + name: 'low-priority-deny', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'deny', + priority: 1, + }; + const allowPolicy: PolicyEntry = { + name: 'high-priority-allow', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [denyPolicy, allowPolicy]; + + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'get_data')).toBe(true); + }); + + it('evaluates constraints - passes when within limit', () => { + const policy: PolicyEntry = { + name: 'constrained', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: { limit: { operator: '<=', value: 100 } }, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'query', { limit: 50 })).toBe(true); + }); + + it('evaluates constraints - fails when exceeding limit', () => { + const policy: PolicyEntry = { + name: 'constrained', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: { limit: { operator: '<=', value: 100 } }, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy(['tier:internal'], ['tier:internal'], 'query', { limit: 500 })).toBe(false); + }); + + it('skips policy when caller tags do not match', () => { + const policy: PolicyEntry = { + name: 'internal-only', + caller_tags: ['tier:internal'], + target_tags: ['tier:internal'], + allow_functions: ['*'], + deny_functions: [], + constraints: {}, + action: 'deny', + priority: 10, + }; + (verifier as any).policies = [policy]; + + // Caller has 'tier:external' which doesn't match, so policy is skipped, default allow + expect(verifier.evaluatePolicy(['tier:external'], ['tier:internal'], 'get_data')).toBe(true); + }); + + it('allows when function matches wildcard pattern', () => { + const policy: PolicyEntry = { + name: 'prefix-match', + caller_tags: [], + target_tags: [], + allow_functions: ['read_*'], + deny_functions: [], + constraints: {}, + action: 'allow', + priority: 10, + }; + (verifier as any).policies = [policy]; + + expect(verifier.evaluatePolicy([], [], 'read_users')).toBe(true); + expect(verifier.evaluatePolicy([], [], 'write_users')).toBe(true); // no match -> default allow + }); + }); + + describe('verifySignature', () => { + it('rejects invalid timestamp format', async () => { + const verifier = new LocalVerifier('http://localhost:8080'); + const result = await verifier.verifySignature('did:web:test', 'sig', 'not-a-number', Buffer.from('{}')); + expect(result).toBe(false); + }); + + it('rejects expired timestamp', async () => { + const verifier = new LocalVerifier('http://localhost:8080', 300, 300); + const oldTs = String(Math.floor(Date.now() / 1000) - 600); + const result = await verifier.verifySignature('did:web:test', 'sig', oldTs, Buffer.from('{}')); + expect(result).toBe(false); + }); + + it('rejects when no public key available', async () => { + const verifier = new LocalVerifier('http://localhost:8080'); + const ts = String(Math.floor(Date.now() / 1000)); + const result = await verifier.verifySignature('did:web:unknown', 'sig', ts, Buffer.from('{}')); + expect(result).toBe(false); + }); + }); + + describe('resolvePublicKey (via verifySignature)', () => { + it('returns null for malformed did:key', async () => { + const verifier = new LocalVerifier('http://localhost:8080'); + const ts = String(Math.floor(Date.now() / 1000)); + // did:key:z with invalid base64url content + const result = await verifier.verifySignature('did:key:zINVALID', 'c2ln', ts, Buffer.from('{}')); + expect(result).toBe(false); + }); + + it('falls back to admin public key for non-did:key', async () => { + const verifier = new LocalVerifier('http://localhost:8080'); + // No admin key set, so should fail + const ts = String(Math.floor(Date.now() / 1000)); + const result = await verifier.verifySignature('did:web:example.com', 'c2ln', ts, Buffer.from('{}')); + expect(result).toBe(false); + }); + }); +});