feat: harden send file idempotency audit
This commit is contained in:
zhaoyilun
@@ -1,22 +1,27 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"context"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||||
)
|
||||
|
||||
const (
|
||||
ToolNameSendFile = "isphere_send_file"
|
||||
EnvSendFileAllowedDir = "ISPHERE_SEND_FILE_ALLOWED_DIR"
|
||||
ToolNameSendFile = "isphere_send_file"
|
||||
EnvSendFileAllowedDir = "ISPHERE_SEND_FILE_ALLOWED_DIR"
|
||||
EnvSendFileAuditPath = "ISPHERE_SEND_FILE_AUDIT_PATH"
|
||||
EnvSendFileIdempotencyPath = "ISPHERE_SEND_FILE_IDEMPOTENCY_PATH"
|
||||
|
||||
sendFileConnector = "implatform-file-transfer"
|
||||
sendFileConnectorMode = "preview-only"
|
||||
@@ -46,27 +51,226 @@ type normalizedSendFileArgs struct {
|
||||
ExecutionMode string
|
||||
}
|
||||
|
||||
type SendFileAuditSink interface {
|
||||
AppendSendFileAudit(ctx context.Context, event SendFileAuditEvent) error
|
||||
}
|
||||
|
||||
type SendFileIdempotencyStore interface {
|
||||
ReserveSendFileIdempotency(ctx context.Context, record SendFileIdempotencyRecord) (SendFileIdempotencyDecision, error)
|
||||
}
|
||||
|
||||
type SendFileAuditEvent struct {
|
||||
Tool string `json:"tool"`
|
||||
TargetType string `json:"target_type"`
|
||||
TargetID string `json:"target_id"`
|
||||
TargetRef string `json:"target_ref"`
|
||||
ExecutionMode string `json:"execution_mode"`
|
||||
Connector string `json:"connector"`
|
||||
ConnectorMode string `json:"connector_mode"`
|
||||
ConnectorStage string `json:"connector_stage"`
|
||||
FileSHA256 string `json:"file_sha256"`
|
||||
FileSizeBytes int64 `json:"file_size_bytes"`
|
||||
IdempotencyKeySHA256 string `json:"idempotency_key_sha256"`
|
||||
SendStatus string `json:"send_status"`
|
||||
Result string `json:"result"`
|
||||
BlockedReason string `json:"blocked_reason,omitempty"`
|
||||
AuditRef string `json:"audit_ref"`
|
||||
StartedAt string `json:"started_at"`
|
||||
FinishedAt string `json:"finished_at"`
|
||||
RealSendAttempted bool `json:"real_send_attempted"`
|
||||
SideEffects map[string]any `json:"side_effects"`
|
||||
FilePath string `json:"-"`
|
||||
IdempotencyKey string `json:"-"`
|
||||
}
|
||||
|
||||
type SendFileIdempotencyRecord struct {
|
||||
Tool string `json:"tool"`
|
||||
TargetRef string `json:"target_ref"`
|
||||
ExecutionMode string `json:"execution_mode"`
|
||||
Connector string `json:"connector"`
|
||||
ConnectorStage string `json:"connector_stage"`
|
||||
FileSHA256 string `json:"file_sha256"`
|
||||
IdempotencyKeySHA256 string `json:"idempotency_key_sha256"`
|
||||
AuditRef string `json:"audit_ref"`
|
||||
StartedAt string `json:"started_at"`
|
||||
}
|
||||
|
||||
type SendFileIdempotencyDecision struct {
|
||||
Duplicate bool
|
||||
Conflict bool
|
||||
FirstAuditRef string
|
||||
FirstStartedAt string
|
||||
}
|
||||
|
||||
type fileSendFileAuditSink struct {
|
||||
path string
|
||||
}
|
||||
|
||||
type fileSendFileIdempotencyStore struct {
|
||||
path string
|
||||
}
|
||||
|
||||
var sendFileIdempotencyFileMu sync.Mutex
|
||||
|
||||
func RegisterISphereSendFileTool(server *mcp.Server) {
|
||||
RegisterISphereSendFileToolWithState(server, nil, nil)
|
||||
}
|
||||
|
||||
func RegisterISphereSendFileToolWithState(server *mcp.Server, auditSink SendFileAuditSink, idempotencyStore SendFileIdempotencyStore) {
|
||||
if auditSink == nil {
|
||||
auditSink = defaultSendFileAuditSink()
|
||||
}
|
||||
if idempotencyStore == nil {
|
||||
idempotencyStore = defaultSendFileIdempotencyStore()
|
||||
}
|
||||
|
||||
mcp.AddTool[SendFileArgs, map[string]any](server, &mcp.Tool{
|
||||
Name: ToolNameSendFile,
|
||||
Description: "Preview iSphere file sends with target/file hash/idempotency metadata; production file upload is blocked until sandbox evidence passes.",
|
||||
}, func(ctx context.Context, _ *mcp.CallToolRequest, input SendFileArgs) (*mcp.CallToolResult, map[string]any, error) {
|
||||
_ = ctx
|
||||
started := time.Now().UTC()
|
||||
normalized, blockedReason, err := normalizeSendFileArgs(input)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
|
||||
var response map[string]any
|
||||
var event SendFileAuditEvent
|
||||
if blockedReason != "" {
|
||||
return nil, sendFileResponse(normalized, started, time.Now().UTC(), false, blockedReason), nil
|
||||
response, event = sendFileResponse(normalized, started, time.Now().UTC(), false, blockedReason)
|
||||
} else if normalized.ExecutionMode == sendFileProductionMode {
|
||||
response, event = sendFileResponse(normalized, started, time.Now().UTC(), false, "production file upload is blocked until send-file sandbox evidence passes")
|
||||
} else {
|
||||
response, event = sendFileResponse(normalized, started, time.Now().UTC(), true, "")
|
||||
}
|
||||
if normalized.ExecutionMode == sendFileProductionMode {
|
||||
return nil, sendFileResponse(normalized, started, time.Now().UTC(), false, "production file upload is blocked until send-file sandbox evidence passes"), nil
|
||||
|
||||
if normalized.FileSHA256 != "" {
|
||||
decision, err := idempotencyStore.ReserveSendFileIdempotency(ctx, sendFileIdempotencyRecordFromAuditEvent(event))
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("%s idempotency reserve failed: %w", ToolNameSendFile, err)
|
||||
}
|
||||
applySendFileIdempotencyDecision(response, &event, decision)
|
||||
}
|
||||
return nil, sendFileResponse(normalized, started, time.Now().UTC(), true, ""), nil
|
||||
if err := auditSink.AppendSendFileAudit(ctx, event); err != nil {
|
||||
return nil, nil, fmt.Errorf("%s audit append failed: %w", ToolNameSendFile, err)
|
||||
}
|
||||
return nil, response, nil
|
||||
})
|
||||
}
|
||||
|
||||
func defaultSendFileAuditSink() SendFileAuditSink {
|
||||
if path := strings.TrimSpace(os.Getenv(EnvSendFileAuditPath)); path != "" {
|
||||
return fileSendFileAuditSink{path: path}
|
||||
}
|
||||
return fileSendFileAuditSink{path: filepath.Join("runs", "send-audit", "send-file-preview.jsonl")}
|
||||
}
|
||||
|
||||
func defaultSendFileIdempotencyStore() SendFileIdempotencyStore {
|
||||
if path := strings.TrimSpace(os.Getenv(EnvSendFileIdempotencyPath)); path != "" {
|
||||
return fileSendFileIdempotencyStore{path: path}
|
||||
}
|
||||
return fileSendFileIdempotencyStore{path: filepath.Join("runs", "send-audit", "send-file-idempotency.jsonl")}
|
||||
}
|
||||
|
||||
func (s fileSendFileAuditSink) AppendSendFileAudit(_ context.Context, event SendFileAuditEvent) error {
|
||||
if strings.TrimSpace(s.path) == "" {
|
||||
return nil
|
||||
}
|
||||
if err := os.MkdirAll(filepath.Dir(s.path), 0o755); err != nil {
|
||||
return err
|
||||
}
|
||||
payload, err := json.Marshal(event)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := os.OpenFile(s.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer file.Close()
|
||||
if _, err := file.Write(append(payload, '\n')); err != nil {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (s fileSendFileIdempotencyStore) ReserveSendFileIdempotency(_ context.Context, record SendFileIdempotencyRecord) (SendFileIdempotencyDecision, error) {
|
||||
if strings.TrimSpace(s.path) == "" {
|
||||
return SendFileIdempotencyDecision{}, nil
|
||||
}
|
||||
if record.IdempotencyKeySHA256 == "" {
|
||||
return SendFileIdempotencyDecision{}, fmt.Errorf("idempotency_key_sha256 is required")
|
||||
}
|
||||
sendFileIdempotencyFileMu.Lock()
|
||||
defer sendFileIdempotencyFileMu.Unlock()
|
||||
|
||||
if err := os.MkdirAll(filepath.Dir(s.path), 0o755); err != nil {
|
||||
return SendFileIdempotencyDecision{}, err
|
||||
}
|
||||
existing, err := readSendFileIdempotencyRecords(s.path)
|
||||
if err != nil {
|
||||
return SendFileIdempotencyDecision{}, err
|
||||
}
|
||||
for _, candidate := range existing {
|
||||
if candidate.IdempotencyKeySHA256 != record.IdempotencyKeySHA256 {
|
||||
continue
|
||||
}
|
||||
decision := SendFileIdempotencyDecision{
|
||||
FirstAuditRef: candidate.AuditRef,
|
||||
FirstStartedAt: candidate.StartedAt,
|
||||
}
|
||||
if candidate.TargetRef == record.TargetRef && candidate.FileSHA256 == record.FileSHA256 {
|
||||
decision.Duplicate = true
|
||||
return decision, nil
|
||||
}
|
||||
decision.Conflict = true
|
||||
return decision, nil
|
||||
}
|
||||
|
||||
payload, err := json.Marshal(record)
|
||||
if err != nil {
|
||||
return SendFileIdempotencyDecision{}, err
|
||||
}
|
||||
file, err := os.OpenFile(s.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
|
||||
if err != nil {
|
||||
return SendFileIdempotencyDecision{}, err
|
||||
}
|
||||
defer file.Close()
|
||||
if _, err := file.Write(append(payload, '\n')); err != nil {
|
||||
return SendFileIdempotencyDecision{}, err
|
||||
}
|
||||
return SendFileIdempotencyDecision{}, nil
|
||||
}
|
||||
|
||||
func readSendFileIdempotencyRecords(path string) ([]SendFileIdempotencyRecord, error) {
|
||||
file, err := os.Open(path)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return nil, nil
|
||||
}
|
||||
return nil, err
|
||||
}
|
||||
defer file.Close()
|
||||
|
||||
var records []SendFileIdempotencyRecord
|
||||
scanner := bufio.NewScanner(file)
|
||||
for scanner.Scan() {
|
||||
line := strings.TrimSpace(scanner.Text())
|
||||
if line == "" {
|
||||
continue
|
||||
}
|
||||
var record SendFileIdempotencyRecord
|
||||
if err := json.Unmarshal([]byte(line), &record); err != nil {
|
||||
return nil, fmt.Errorf("decode send-file idempotency record: %w", err)
|
||||
}
|
||||
records = append(records, record)
|
||||
}
|
||||
if err := scanner.Err(); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return records, nil
|
||||
}
|
||||
|
||||
func normalizeSendFileArgs(input SendFileArgs) (normalizedSendFileArgs, string, error) {
|
||||
targetType, targetRefPrefix, err := normalizeSendFileTargetType(input.TargetType)
|
||||
if err != nil {
|
||||
@@ -194,7 +398,7 @@ func sha256FileHex(path string) (string, error) {
|
||||
return hex.EncodeToString(hash.Sum(nil)), nil
|
||||
}
|
||||
|
||||
func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished time.Time, planned bool, blockedReason string) map[string]any {
|
||||
func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished time.Time, planned bool, blockedReason string) (map[string]any, SendFileAuditEvent) {
|
||||
sideEffects := sendMessageNoSideEffects()
|
||||
status := "planned"
|
||||
stage := sendFilePreviewStage
|
||||
@@ -207,7 +411,30 @@ func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished
|
||||
blocked = blockedReason
|
||||
}
|
||||
auditRef := "send-file:" + shortHash(input.FileSHA256) + ":" + shortHash(input.IdempotencyKeySHA256)
|
||||
return map[string]any{
|
||||
event := SendFileAuditEvent{
|
||||
Tool: ToolNameSendFile,
|
||||
TargetType: input.TargetType,
|
||||
TargetID: input.TargetID,
|
||||
TargetRef: input.TargetRef,
|
||||
ExecutionMode: input.ExecutionMode,
|
||||
Connector: sendFileConnector,
|
||||
ConnectorMode: sendFileConnectorMode,
|
||||
ConnectorStage: stage,
|
||||
FileSHA256: input.FileSHA256,
|
||||
FileSizeBytes: input.FileSizeBytes,
|
||||
IdempotencyKeySHA256: input.IdempotencyKeySHA256,
|
||||
SendStatus: status,
|
||||
Result: status,
|
||||
AuditRef: auditRef,
|
||||
StartedAt: started.Format(time.RFC3339Nano),
|
||||
FinishedAt: finished.Format(time.RFC3339Nano),
|
||||
RealSendAttempted: false,
|
||||
SideEffects: sideEffects,
|
||||
}
|
||||
if blockedReason != "" {
|
||||
event.BlockedReason = blockedReason
|
||||
}
|
||||
response := map[string]any{
|
||||
"ok": ok,
|
||||
"send_status": status,
|
||||
"blocked_reason": blocked,
|
||||
@@ -234,6 +461,10 @@ func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished
|
||||
},
|
||||
"idempotency": map[string]any{
|
||||
"idempotency_key_sha256": input.IdempotencyKeySHA256,
|
||||
"duplicate_detected": false,
|
||||
"conflict_detected": false,
|
||||
"first_audit_ref": nil,
|
||||
"first_started_at": nil,
|
||||
},
|
||||
"side_effect_flags": sideEffects,
|
||||
"side_effects": sideEffects,
|
||||
@@ -254,4 +485,58 @@ func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished
|
||||
"real_send_attempted": false,
|
||||
},
|
||||
}
|
||||
return response, event
|
||||
}
|
||||
|
||||
func sendFileIdempotencyRecordFromAuditEvent(event SendFileAuditEvent) SendFileIdempotencyRecord {
|
||||
return SendFileIdempotencyRecord{
|
||||
Tool: event.Tool,
|
||||
TargetRef: event.TargetRef,
|
||||
ExecutionMode: event.ExecutionMode,
|
||||
Connector: event.Connector,
|
||||
ConnectorStage: event.ConnectorStage,
|
||||
FileSHA256: event.FileSHA256,
|
||||
IdempotencyKeySHA256: event.IdempotencyKeySHA256,
|
||||
AuditRef: event.AuditRef,
|
||||
StartedAt: event.StartedAt,
|
||||
}
|
||||
}
|
||||
|
||||
func applySendFileIdempotencyDecision(response map[string]any, event *SendFileAuditEvent, decision SendFileIdempotencyDecision) {
|
||||
idempotency, _ := response["idempotency"].(map[string]any)
|
||||
if idempotency == nil {
|
||||
idempotency = map[string]any{}
|
||||
response["idempotency"] = idempotency
|
||||
}
|
||||
idempotency["duplicate_detected"] = decision.Duplicate
|
||||
idempotency["conflict_detected"] = decision.Conflict
|
||||
if decision.FirstAuditRef != "" {
|
||||
idempotency["first_audit_ref"] = decision.FirstAuditRef
|
||||
}
|
||||
if decision.FirstStartedAt != "" {
|
||||
idempotency["first_started_at"] = decision.FirstStartedAt
|
||||
}
|
||||
if !decision.Conflict {
|
||||
return
|
||||
}
|
||||
|
||||
blockedReason := "idempotency key was already used for a different target or file"
|
||||
response["ok"] = false
|
||||
response["send_status"] = "blocked"
|
||||
response["blocked_reason"] = blockedReason
|
||||
response["connector_stage"] = sendFileBlockedStage
|
||||
|
||||
audit, _ := response["audit"].(map[string]any)
|
||||
if audit != nil {
|
||||
audit["result"] = "blocked"
|
||||
audit["connector_stage"] = sendFileBlockedStage
|
||||
audit["blocked_reason"] = blockedReason
|
||||
}
|
||||
|
||||
if event != nil {
|
||||
event.ConnectorStage = sendFileBlockedStage
|
||||
event.SendStatus = "blocked"
|
||||
event.Result = "blocked"
|
||||
event.BlockedReason = blockedReason
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user