Janady13/missionmatch / internal/modules/ai/egress.go

1package ai 2 3import ( 4 "context" 5 "encoding/json" 6 "fmt" 7 8 "github.com/google/uuid" 9 10 "github.com/missionworkforce/missionmatch/internal/platform/audit" 11 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 12 "github.com/missionworkforce/missionmatch/internal/platform/scrub" 13) 14 15// ActionExternalInference is the audit action recorded for every call that leaves the local plane for an 16// external inference backend. It sits in the same aedt namespace as aedt.ai.answered. 17const ActionExternalInference = "aedt.inference.external" 18 19// AllowExternal is the single gate the orchestrator calls before any payload leaves for an external 20// inference backend such as OpenAI. It refuses a payload that may not egress (an unknown class or a 21// private data marker) and, when the payload is permitted, returns the audit metadata that must be 22// recorded for the call. Binding the gate and the audit in one call means a caller cannot send without 23// both. The metadata records the backend, the payload class, the byte count, and the content hash, and 24// never the content, matching how the orchestrator already audits with a map of abstract fields. 25func AllowExternal(backend string, provs []scrub.Provenance, class scrub.EgressClass, payload []byte) (map[string]any, error) { 26 if err := scrub.AllowEgress(provs, class, payload); err != nil { 27 return nil, err 28 } 29 return map[string]any{ 30 "backend": backend, 31 "provenance": provenanceStrings(provs), 32 "payload_class": string(class), 33 "byte_count": len(payload), 34 "content_sha256": scrub.ContentHash(payload), 35 }, nil 36} 37 38// AllowExternalAudited is AllowExternal plus the PERSISTED audit row, and it is what every caller must use. 39// 40// AllowExternal returns audit metadata and trusts its caller to record it. That trust was misplaced. The 41// comment above claims that binding the gate and the audit in one call means a caller cannot send without 42// both, and the binding was never real: the only caller wrote the metadata to a LOG LINE and persisted 43// nothing. ActionExternalInference was declared, documented, and covered by a unit test that asserted the 44// shape of a map. No row was ever written for it. So the single class of call that physically leaves this 45// machine was the only class with no audit trail, discovered 29 July 2026 while closing finding three. 46// 47// IT FAILS CLOSED. An external call whose audit row cannot be written does not happen. That is the posture 48// the auth module already takes for security events, for the same reason: an unrecorded egress is worse 49// than a refused one, because a refusal is visible and an unrecorded call is not. 50// 51// The row is written BEFORE the payload leaves, which is the only ordering that can be trusted. A row 52// written afterwards is missing exactly when the process dies mid call, which is the case an auditor cares 53// about most. 54func AllowExternalAudited(ctx context.Context, db dbgen.DBTX, org *uuid.UUID, backend string, provs []scrub.Provenance, class scrub.EgressClass, payload []byte) (map[string]any, error) { 55 meta, err := AllowExternal(backend, provs, class, payload) 56 if err != nil { 57 return nil, err 58 } 59 blob, merr := json.Marshal(meta) 60 if merr != nil { 61 return nil, fmt.Errorf("ai: external egress refused, its audit metadata would not marshal: %w", merr) 62 } 63 hash, _ := meta["content_sha256"].(string) 64 if aerr := audit.OnPool(ctx, db, org, audit.Event{ 65 Action: ActionExternalInference, 66 EntityType: "external_inference", 67 EntityID: hash, 68 NewValues: blob, 69 }); aerr != nil { 70 return nil, fmt.Errorf("ai: external egress REFUSED because its audit row could not be written: %w", aerr) 71 } 72 return meta, nil 73} 74 75// RecordExternalOutcome records WHICH backend actually served a permitted call, keyed to the same content 76// hash as the row AllowExternalAudited wrote. 77// 78// It exists because the gateway FALLS BACK to the local runtime when the selected backend fails, which is 79// correct for availability and invisible in the audit trail without this row. Without it the ledger cannot 80// answer the only question that matters about an external lane: did this payload actually leave, or did a 81// failure quietly turn it into a local call that looked identical from here. The gateway tags its response 82// model with the backend that produced it, so the answer is recorded rather than assumed. 83// 84// This row is written AFTER the call, so unlike the egress row it is genuinely best effort: the call has 85// already happened and refusing anything at this point would be theatre. The error is returned so a caller 86// can report it, never to gate the work. 87func RecordExternalOutcome(ctx context.Context, db dbgen.DBTX, org *uuid.UUID, contentHash, servedModel string, tokens int) error { 88 blob, err := json.Marshal(map[string]any{ 89 "content_sha256": contentHash, 90 "served_model": servedModel, 91 "tokens": tokens, 92 }) 93 if err != nil { 94 return err 95 } 96 return audit.OnPool(ctx, db, org, audit.Event{ 97 Action: ActionExternalInference, 98 EntityType: "external_inference_result", 99 EntityID: contentHash, 100 NewValues: blob, 101 }) 102} 103 104// provenanceStrings renders the element provenance set for the audit row. The SET is recorded, not a single 105// value, because a payload composed from several rows has several origins and an audit that flattened them 106// could not answer which one authorised the call. 107func provenanceStrings(provs []scrub.Provenance) []string { 108 out := make([]string, 0, len(provs)) 109 for _, p := range provs { 110 out = append(out, string(p)) 111 } 112 return out 113} 114