usertrust 1.0.0 → 1.1.0

package/dist/govern.js

@@ -36,8 +36,10 @@ import { detectClientKind } from "./detect.js";
 import { TrustTBClient, XFER_SPEND } from "./ledger/client.js";
 import { estimateCost, estimateInputTokens } from "./ledger/pricing.js";
 import { recordPattern } from "./memory/patterns.js";
+import { DEFAULT_RULES } from "./policy/default-rules.js";
 import { evaluatePolicy, loadPolicies } from "./policy/gate.js";
-import { detectPII } from "./policy/pii.js";
+import { detectInjection } from "./policy/injection.js";
+import { detectPII, redactPII } from "./policy/pii.js";
 import { connectProxy } from "./proxy.js";
 import { CircuitBreakerRegistry } from "./resilience/circuit.js";
 import { DEFAULT_BUDGET, VAULT_DIR } from "./shared/constants.js";
@@ -122,6 +124,7 @@ export async function trust(client, opts) {
             budget: opts?.budget ?? DEFAULT_BUDGET,
         });
     }
+    const customRates = config.pricing === "custom" ? config.customRates : undefined;
     const isDryRun = opts?.dryRun ?? process.env.USERTRUST_DRY_RUN === "true";
     // AUD-470: Only accept injected _engine/_audit in test environments.
     // In production, silently ignore them to prevent governance bypass.
@@ -130,7 +133,8 @@ export async function trust(client, opts) {
     const vaultPath = vaultBase;
     const audit = (isTestEnv ? opts?._audit : undefined) ?? createAuditWriter(vaultPath);
     const policiesPath = join(vaultPath, VAULT_DIR, config.policies);
-    const policyRules = existsSync(policiesPath) ? loadPolicies(policiesPath) : [];
+    const loadedRules = existsSync(policiesPath) ? loadPolicies(policiesPath) : [];
+    const policyRules = loadedRules.length > 0 ? loadedRules : DEFAULT_RULES;
     const breaker = new CircuitBreakerRegistry({
         failureThreshold: config.circuitBreaker.failureThreshold,
         resetTimeoutMs: config.circuitBreaker.resetTimeout,
@@ -186,7 +190,7 @@ export async function trust(client, opts) {
             const transferId = trustId("tx");
             const estimatedInputTokens = estimateInputTokens(messages);
             const maxOutputTokens = params.max_tokens ?? 4096;
-            const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens);
+            const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens, customRates);
             // AUD-453: Acquire mutex to serialise budget-check + PENDING hold.
             // This prevents concurrent calls from both passing the budget check
             // and overshooting the budget.
@@ -214,7 +218,28 @@ export async function trust(client, opts) {
                     }
                     // "warn" and "redact" modes: continue (redact is not implemented at SDK level)
                 }
-                // d2. Failure mode 15.4: TigerBeetle / engine unreachable — PENDING hold
+                // d2. Injection detection
+                if (config.injection !== "off") {
+                    const injectionResult = detectInjection(messages);
+                    if (injectionResult.detected) {
+                        if (config.injection === "block") {
+                            throw new PolicyDeniedError(`Prompt injection detected: ${injectionResult.patterns.join(", ")}`);
+                        }
+                        // warn: log to audit trail (non-fatal)
+                        await audit
+                            .appendEvent({
+                            kind: "injection_detected",
+                            actor: "local",
+                            data: {
+                                patterns: injectionResult.patterns,
+                                score: injectionResult.score,
+                                model,
+                            },
+                        })
+                            .catch(() => { });
+                    }
+                }
+                // e. Failure mode 15.4: TigerBeetle / engine unreachable — PENDING hold
                 if (proxyConn != null && !isDryRun) {
                     try {
                         // AUD-460: Capture the proxy's returned transferId
@@ -263,16 +288,20 @@ export async function trust(client, opts) {
                         let streamCost;
                         let usageSource;
                         if (completion.usageReported) {
-                            streamCost = estimateCost(model, completion.usage.inputTokens, completion.usage.outputTokens);
+                            streamCost = estimateCost(model, completion.usage.inputTokens, completion.usage.outputTokens, customRates);
                             usageSource = "provider";
                         }
                         else {
                             streamCost = estimatedCost;
                             usageSource = "estimated";
                         }
-                        // Release in-flight hold
-                        inFlightHoldTotal -= estimatedCost;
-                        budgetSpent += streamCost;
+                        // Release in-flight hold and commit budget under mutex
+                        {
+                            const releaseLock = await budgetMutex.acquire();
+                            inFlightHoldTotal -= estimatedCost;
+                            budgetSpent += streamCost;
+                            releaseLock();
+                        }
                         // AUD-457: Persist cumulative spend to disk
                         await persistSpendLedger(vaultBase, budgetSpent);
                         cb.recordSuccess();
@@ -328,17 +357,25 @@ export async function trust(client, opts) {
                         const syntheticHash = createHash("sha256").update(transferId).digest("hex");
                         let auditHash = syntheticHash;
                         try {
+                            const auditEventData = {
+                                model,
+                                cost: streamCost,
+                                settled,
+                                transferId,
+                                usageSource,
+                                chunksDelivered: completion.chunksDelivered,
+                            };
+                            if (config.pii === "warn" || config.pii === "redact") {
+                                const piiResult = redactPII(messages);
+                                if (piiResult.detection.found) {
+                                    auditEventData.piiDetected = piiResult.detection.types;
+                                    auditEventData.piiPaths = piiResult.detection.paths;
+                                }
+                            }
                             const auditEvent = await audit.appendEvent({
                                 kind: "llm_call",
                                 actor: "local",
-                                data: {
-                                    model,
-                                    cost: streamCost,
-                                    settled,
-                                    transferId,
-                                    usageSource,
-                                    chunksDelivered: completion.chunksDelivered,
-                                },
+                                data: auditEventData,
                             });
                             auditHash = auditEvent.hash;
                         }
@@ -349,7 +386,7 @@ export async function trust(client, opts) {
                             transferId,
                             cost: streamCost,
                             budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
-                            auditHash,
+                            auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : auditHash,
                             chainPath: join(VAULT_DIR, "audit"),
                             receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
                             settled,
@@ -364,9 +401,13 @@ export async function trust(client, opts) {
                         };
                         inFlightStreamCount--;
                         return streamReceipt;
-                    }, (error, partial) => {
-                        // Release in-flight hold
-                        inFlightHoldTotal -= estimatedCost;
+                    }, async (error, partial) => {
+                        // Release in-flight hold under mutex
+                        {
+                            const releaseLock = await budgetMutex.acquire();
+                            inFlightHoldTotal -= estimatedCost;
+                            releaseLock();
+                        }
                         cb.recordFailure();
                         // Best-effort audit of partial delivery
                         audit
@@ -380,9 +421,12 @@ export async function trust(client, opts) {
                                 partialInputTokens: partial.usage.inputTokens,
                                 partialOutputTokens: partial.usage.outputTokens,
                                 usageReported: partial.usageReported,
-                                error: error instanceof Error
-                                    ? error.message.slice(0, 200)
-                                    : String(error).slice(0, 200),
+                                error: (() => {
+                                    const raw = error instanceof Error ? error.message : String(error);
+                                    return config.pii === "warn" || config.pii === "redact"
+                                        ? redactPII(raw).data.slice(0, 200)
+                                        : raw.slice(0, 200);
+                                })(),
                             },
                         })
                             .catch(() => { });
@@ -398,12 +442,12 @@ export async function trust(client, opts) {
                     // AUD-454: For streaming responses, settlement has NOT happened yet.
                     // Set settled: false — the real settlement status will be on
                     // governedStream.receipt after the stream is fully consumed.
-                    const auditHash = createHash("sha256").update(transferId).digest("hex");
+                    const streamEstimateHash = createHash("sha256").update(transferId).digest("hex");
                     const estimatedReceipt = {
                         transferId,
                         cost: estimatedCost,
                         budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
-                        auditHash,
+                        auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : streamEstimateHash,
                         chainPath: join(VAULT_DIR, "audit"),
                         receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
                         settled: false, // AUD-454: not settled yet — stream hasn't been consumed
@@ -428,13 +472,16 @@ export async function trust(client, opts) {
                         const outputTokens = usage.output_tokens ??
                             usage.completion_tokens ??
                             0;
-                        actualCost = estimateCost(model, inputTokens, outputTokens);
+                        actualCost = estimateCost(model, inputTokens, outputTokens, customRates);
                     }
                 }
-                // Release in-flight hold (non-streaming success)
-                inFlightHoldTotal -= estimatedCost;
-                // Track budget (cumulative)
-                budgetSpent += actualCost;
+                // Release in-flight hold and commit budget under mutex
+                {
+                    const releaseLock = await budgetMutex.acquire();
+                    inFlightHoldTotal -= estimatedCost;
+                    budgetSpent += actualCost;
+                    releaseLock();
+                }
                 // AUD-457: Persist cumulative spend to disk
                 await persistSpendLedger(vaultBase, budgetSpent);
                 // g. Circuit breaker: record success
@@ -470,23 +517,47 @@ export async function trust(client, opts) {
                         // AUD-460: Use the proxy's transferId for settlement
                         await proxyConn.settle(proxyTransferId ?? transferId, actualCost);
                     }
-                    catch {
+                    catch (postErr) {
                         settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor: "local",
+                            data: {
+                                model,
+                                cost: actualCost,
+                                transferId,
+                                error: postErr instanceof Error
+                                    ? postErr.message.slice(0, 200)
+                                    : String(postErr).slice(0, 200),
+                            },
+                        })
+                            .catch(() => {
+                            callAuditDegraded = true;
+                        });
                     }
                 }
                 // h. Audit event — failure mode 15.3: audit write failure
                 const syntheticHash = createHash("sha256").update(transferId).digest("hex");
                 let auditHash = syntheticHash;
                 try {
+                    const auditData = {
+                        model,
+                        cost: actualCost,
+                        settled,
+                        transferId,
+                    };
+                    if (config.pii === "warn" || config.pii === "redact") {
+                        const piiResult = redactPII(messages);
+                        if (piiResult.detection.found) {
+                            auditData.piiDetected = piiResult.detection.types;
+                            auditData.piiPaths = piiResult.detection.paths;
+                        }
+                    }
                     const auditEvent = await audit.appendEvent({
                         kind: "llm_call",
                         actor: "local",
-                        data: {
-                            model,
-                            cost: actualCost,
-                            settled,
-                            transferId,
-                        },
+                        data: auditData,
                     });
                     auditHash = auditEvent.hash;
                 }
@@ -519,7 +590,7 @@ export async function trust(client, opts) {
                     transferId,
                     cost: actualCost,
                     budgetRemaining,
-                    auditHash,
+                    auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : auditHash,
                     chainPath: join(VAULT_DIR, "audit"),
                     receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
                     settled,
@@ -533,8 +604,12 @@ export async function trust(client, opts) {
                 return { response, receipt };
             }
             catch (err) {
-                // Release in-flight hold (non-streaming failure)
-                inFlightHoldTotal -= estimatedCost;
+                // Release in-flight hold under mutex (non-streaming failure)
+                {
+                    const releaseLock = await budgetMutex.acquire();
+                    inFlightHoldTotal -= estimatedCost;
+                    releaseLock();
+                }
                 // j. Circuit breaker: record failure
                 cb.recordFailure();
                 // j2. Failure mode 15.2: LLM fails — VOID the pending hold
@@ -561,7 +636,13 @@ export async function trust(client, opts) {
                     .appendEvent({
                     kind: "llm_call_failed",
                     actor: "local",
-                    data: { model, error: String(err), transferId },
+                    data: {
+                        model,
+                        error: config.pii === "warn" || config.pii === "redact"
+                            ? redactPII(String(err)).data.slice(0, 200)
+                            : String(err),
+                        transferId,
+                    },
                 })
                     .catch(() => {
                     callAuditDegraded = true;
@@ -584,6 +665,287 @@ export async function trust(client, opts) {
             inFlightCount--;
         }
     }
+    // 7b. Action governance — simplified pipeline for non-LLM actions
+    async function governActionImpl(action, execute) {
+        if (destroyed) {
+            throw new Error("TrustedClient has been destroyed");
+        }
+        // AUD-466: Validate cost to prevent budget inflation via negative values
+        if (!Number.isFinite(action.cost) || action.cost < 0) {
+            throw new Error(`action.cost must be a non-negative finite number, got ${String(action.cost)}`);
+        }
+        inFlightCount++;
+        let callAuditDegraded = false;
+        try {
+            const actor = action.actor ?? "local";
+            const transferId = trustId("tx");
+            // a. Circuit breaker check (keyed by action kind)
+            const cb = breaker.get(action.kind);
+            cb.allowRequest();
+            // b. Acquire mutex for budget atomicity
+            const releaseBudgetLock = await budgetMutex.acquire();
+            let proxyTransferId;
+            try {
+                // c. Policy gate — action fields available in context
+                // AUD-467: Caller params spread FIRST so governance fields cannot be shadowed
+                const policyResult = evaluatePolicy(policyRules, {
+                    ...(action.params ?? {}),
+                    action_kind: action.kind,
+                    action_name: action.name,
+                    estimated_cost: action.cost,
+                    budget_remaining: config.budget - budgetSpent - inFlightHoldTotal,
+                    tier: config.tier,
+                });
+                if (policyResult.decision === "deny") {
+                    const reason = policyResult.reasons.length > 0 ? policyResult.reasons.join("; ") : "Policy denied";
+                    throw new PolicyDeniedError(reason);
+                }
+                // d. PII check on action params
+                if (config.pii !== "off" && action.params != null) {
+                    const piiResult = detectPII(action.params);
+                    if (piiResult.found && config.pii === "block") {
+                        throw new PolicyDeniedError(`PII detected in action params: ${piiResult.types.join(", ")}`);
+                    }
+                }
+                // d2. Injection detection on action params
+                if (config.injection !== "off" && action.params != null) {
+                    const injectionResult = detectInjection(action.params);
+                    if (injectionResult.detected) {
+                        if (config.injection === "block") {
+                            throw new PolicyDeniedError(`Injection detected in action params: ${injectionResult.patterns.join(", ")}`);
+                        }
+                        // warn: log to audit trail (non-fatal)
+                        await audit
+                            .appendEvent({
+                            kind: "injection_detected",
+                            actor: action.actor ?? "local",
+                            data: {
+                                patterns: injectionResult.patterns,
+                                score: injectionResult.score,
+                                actionName: action.name,
+                                actionKind: action.kind,
+                            },
+                        })
+                            .catch(() => { });
+                    }
+                }
+                // e. PENDING hold
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        const proxyResult = await proxyConn.spend({
+                            model: action.name,
+                            estimatedCost: action.cost,
+                            actor,
+                        });
+                        proxyTransferId = proxyResult.transferId;
+                    }
+                    catch (holdErr) {
+                        throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
+                    }
+                }
+                else if (engine != null && !isDryRun) {
+                    try {
+                        await engine.spendPending({
+                            transferId,
+                            amount: action.cost,
+                        });
+                    }
+                    catch (holdErr) {
+                        throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
+                    }
+                }
+                inFlightHoldTotal += action.cost;
+            }
+            finally {
+                releaseBudgetLock();
+            }
+            // f. Execute the action
+            // Guard against double-decrement of inFlightHoldTotal (AUD-465)
+            let holdReleased = false;
+            async function releaseHoldAndCommit(cost) {
+                if (!holdReleased) {
+                    holdReleased = true;
+                    const releaseLock = await budgetMutex.acquire();
+                    inFlightHoldTotal -= action.cost;
+                    if (cost !== undefined) {
+                        budgetSpent += cost;
+                    }
+                    releaseLock();
+                }
+            }
+            try {
+                const result = await execute();
+                // Release in-flight hold and commit budget under mutex
+                await releaseHoldAndCommit(action.cost);
+                await persistSpendLedger(vaultBase, budgetSpent);
+                // g. Circuit breaker: record success
+                cb.recordSuccess();
+                // h. POST settlement
+                let settled = true;
+                if (engine != null && !isDryRun) {
+                    try {
+                        await engine.postPendingSpend(transferId);
+                    }
+                    catch (postErr) {
+                        settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor,
+                            data: {
+                                actionKind: action.kind,
+                                actionName: action.name,
+                                cost: action.cost,
+                                transferId,
+                                error: postErr instanceof Error
+                                    ? postErr.message.slice(0, 200)
+                                    : String(postErr).slice(0, 200),
+                            },
+                        })
+                            .catch(() => {
+                            callAuditDegraded = true;
+                        });
+                    }
+                }
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        await proxyConn.settle(proxyTransferId ?? transferId, action.cost);
+                    }
+                    catch (postErr) {
+                        settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor,
+                            data: {
+                                actionKind: action.kind,
+                                actionName: action.name,
+                                cost: action.cost,
+                                transferId,
+                                error: postErr instanceof Error
+                                    ? postErr.message.slice(0, 200)
+                                    : String(postErr).slice(0, 200),
+                            },
+                        })
+                            .catch(() => {
+                            callAuditDegraded = true;
+                        });
+                    }
+                }
+                // i. Prepare params for audit — redact PII if configured
+                let auditParams;
+                if (action.params != null) {
+                    if (config.pii === "warn" || config.pii === "redact") {
+                        const redacted = redactPII(action.params);
+                        auditParams = redacted.data;
+                    }
+                    else {
+                        auditParams = action.params;
+                    }
+                }
+                // i2. Audit event
+                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                let auditHash = syntheticHash;
+                try {
+                    const auditEvent = await audit.appendEvent({
+                        kind: action.kind,
+                        actor,
+                        data: {
+                            actionName: action.name,
+                            cost: action.cost,
+                            settled,
+                            transferId,
+                            ...(auditParams != null ? { params: auditParams } : {}),
+                        },
+                    });
+                    auditHash = auditEvent.hash;
+                }
+                catch {
+                    // Failure mode 15.3: Audit degraded — do not fail the response
+                    callAuditDegraded = true;
+                    process.stderr.write(`[usertrust] audit degraded: failed to write ${action.kind} event for ${transferId}\n`);
+                }
+                // j. Daily-rotated receipt
+                if (config.audit.rotation !== "none") {
+                    writeReceipt(vaultPath, {
+                        kind: action.kind,
+                        subsystem: "trust",
+                        actor,
+                        data: {
+                            actionName: action.name,
+                            cost: action.cost,
+                            settled,
+                            transferId,
+                            ...(auditParams != null ? { params: auditParams } : {}),
+                        },
+                    }, config.audit.indexLimit);
+                }
+                const budgetRemaining = config.budget - budgetSpent - inFlightHoldTotal;
+                const receipt = {
+                    transferId,
+                    cost: action.cost,
+                    budgetRemaining,
+                    auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : auditHash,
+                    chainPath: join(VAULT_DIR, "audit"),
+                    receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                    settled,
+                    model: action.name,
+                    provider: action.kind,
+                    timestamp: new Date().toISOString(),
+                    actionKind: action.kind,
+                    ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                    ...(proxyConn != null ? { proxyStub: true } : {}),
+                };
+                return { result, receipt };
+            }
+            catch (err) {
+                // Release in-flight hold (AUD-465: guard prevents double-decrement)
+                await releaseHoldAndCommit();
+                // Circuit breaker: record failure
+                cb.recordFailure();
+                // VOID the pending hold
+                if (engine != null && !isDryRun) {
+                    try {
+                        await engine.voidPendingSpend(transferId);
+                    }
+                    catch {
+                        // Best-effort void
+                    }
+                }
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        await proxyConn.void(proxyTransferId ?? transferId);
+                    }
+                    catch {
+                        // Best-effort void
+                    }
+                }
+                // Audit the failure
+                await audit
+                    .appendEvent({
+                    kind: `${action.kind}_failed`,
+                    actor,
+                    data: {
+                        actionName: action.name,
+                        error: (() => {
+                            const raw = err instanceof Error ? err.message : String(err);
+                            return config.pii === "warn" || config.pii === "redact"
+                                ? redactPII(raw).data.slice(0, 200)
+                                : raw.slice(0, 200);
+                        })(),
+                        transferId,
+                    },
+                })
+                    .catch(() => {
+                    callAuditDegraded = true;
+                });
+                throw err;
+            }
+        }
+        finally {
+            inFlightCount--;
+        }
+    }
     // 8. Safety net: clean up on process exit if destroy() was never called
     let beforeExitHandler = null;
     // 9. Build Proxy based on client kind
@@ -623,13 +985,13 @@ export async function trust(client, opts) {
             }
         };
         if (kind === "anthropic") {
-            return buildAnthropicProxy(client, interceptCall, destroyFn);
+            return buildAnthropicProxy(client, interceptCall, destroyFn, governActionImpl);
         }
         if (kind === "openai") {
-            return buildOpenAIProxy(client, interceptCall, destroyFn);
+            return buildOpenAIProxy(client, interceptCall, destroyFn, governActionImpl);
         }
         // google
-        return buildGoogleProxy(client, interceptCall, destroyFn);
+        return buildGoogleProxy(client, interceptCall, destroyFn, governActionImpl);
     }
     const governedClient = createClientProxy();
     beforeExitHandler = () => {
@@ -707,7 +1069,7 @@ async function createTBEngine(config) {
         },
     };
 }
-function buildAnthropicProxy(client, intercept, destroy) {
+function buildAnthropicProxy(client, intercept, destroy, governAction) {
     const original = client;
     const messages = original.messages;
     const originalCreate = messages.create;
@@ -727,12 +1089,14 @@ function buildAnthropicProxy(client, intercept, destroy) {
                 return messagesProxy;
             if (prop === "destroy")
                 return destroy;
+            if (prop === "governAction")
+                return governAction;
             return Reflect.get(target, prop, receiver);
         },
     });
     return clientProxy;
 }
-function buildOpenAIProxy(client, intercept, destroy) {
+function buildOpenAIProxy(client, intercept, destroy, governAction) {
     const original = client;
     const chat = original.chat;
     const completions = chat.completions;
@@ -758,12 +1122,14 @@ function buildOpenAIProxy(client, intercept, destroy) {
                 return chatProxy;
             if (prop === "destroy")
                 return destroy;
+            if (prop === "governAction")
+                return governAction;
             return Reflect.get(target, prop, receiver);
         },
     });
     return clientProxy;
 }
-function buildGoogleProxy(client, intercept, destroy) {
+function buildGoogleProxy(client, intercept, destroy, governAction) {
     const original = client;
     const models = original.models;
     const originalGenerate = models.generateContent;
@@ -781,6 +1147,8 @@ function buildGoogleProxy(client, intercept, destroy) {
                 return modelsProxy;
             if (prop === "destroy")
                 return destroy;
+            if (prop === "governAction")
+                return governAction;
             return Reflect.get(target, prop, receiver);
         },
     });