@gethelio/proxy 0.5.0 → 0.7.0

package/dist/cli.js

@@ -5303,13 +5303,22 @@ var installScanBody = z4.object({
   }),
   metadata: metadataSchema
 });
+var evidenceEntrySchema = z4.object({
+  evidence_key: z4.string().min(1),
+  evidence_data: z4.unknown().refine((v) => v !== void 0, { message: "Required" }),
+  ttl_seconds: z4.number().int().positive().optional()
+});
 var auditBody = z4.object({
   evaluation_id: z4.string().min(1),
   status: z4.enum(["success", "error", "not_executed"]),
   error: z4.string().optional(),
   duration_ms: z4.number().optional(),
   result: z4.unknown().optional(),
-  actual_amount: z4.number().optional()
+  actual_amount: z4.number().optional(),
+  // No `.max()` / size refinement here on purpose (issue #11): caps are
+  // enforced per-entry in GovernanceService.populateEvidence as soft-drops, so
+  // an over-cap entry never 400s away the audit row for a call that already ran.
+  evidence: z4.array(evidenceEntrySchema).optional()
 });
 var resolveBody = z4.object({
   resolution: z4.enum(["approved", "denied", "timeout", "cancelled"]),
@@ -5411,10 +5420,19 @@ function auditPayloadHash(data) {
     error: data.error ?? null,
     duration_ms: data.duration_ms ?? null,
     result: data.result ?? null,
-    actual_amount: data.actual_amount ?? null
+    actual_amount: data.actual_amount ?? null,
+    evidence: canonicalEvidence(data.evidence)
   };
   return createHash2("sha256").update(canonicalize(semantic)).digest("hex");
 }
+function canonicalEvidence(evidence) {
+  if (!evidence || evidence.length === 0) return null;
+  return evidence.map((e) => ({
+    evidence_key: e.evidence_key,
+    evidence_data: e.evidence_data ?? null,
+    ttl_seconds: e.ttl_seconds ?? null
+  })).map((norm) => ({ sortKey: canonicalize(norm), norm })).sort((a, b) => a.sortKey < b.sortKey ? -1 : a.sortKey > b.sortKey ? 1 : 0).map((x) => x.norm);
+}
 function asStatus(status) {
   return status;
 }
@@ -5547,6 +5565,8 @@ var MAX_TOOL_INPUT_BYTES = 64 * 1024;
 var MAX_PENDING_COUNT = 1e4;
 var MAX_PENDING_BYTES = 64 * 1024 * 1024;
 var MAX_SENDER_KEYS = 5e4;
+var MAX_EVIDENCE_ENTRIES = 16;
+var MAX_EVIDENCE_BYTES = 64 * 1024;
 var SWEEP_INTERVAL_MS2 = 3e4;
 var GovernanceService = class {
   policy;
@@ -5837,6 +5857,7 @@ var GovernanceService = class {
     if (callHappened && this.evidenceStore && entry.sessionId) {
       this.evidenceStore.recordToolCall(entry.sessionId, entry.toolName, req.status === "success");
     }
+    const evidenceOutcomes = this.populateEvidence(req, entry);
     const auditId = this.writeAudit({
       timestampIso: entry.timestampIso,
       origin: entry.origin,
@@ -5866,7 +5887,62 @@ var GovernanceService = class {
       finalizedBy: "audit",
       expiresAtMs: this.now() + this.ttlMs
     });
-    return { status: 201, body: { ok: true, audit_record_id: auditId } };
+    const body = { ok: true, audit_record_id: auditId };
+    if (evidenceOutcomes) body["evidence"] = evidenceOutcomes;
+    return { status: 201, body };
+  }
+  /**
+   * Write the optional `/audit` evidence entries for a successful call
+   * (issue #11), returning a per-entry outcome list — or `undefined`
+   * when there is nothing to report (non-success status, or no evidence
+   * supplied). Caps are enforced here, NOT in route validation, so an over-cap
+   * entry soft-drops without discarding the audit row: entries past
+   * `MAX_EVIDENCE_ENTRIES` → `too_many`; oversized `evidence_data` →
+   * `too_large`; no evidence store on the service → `evidence_unavailable`;
+   * a sessionless evaluation → `no_session`; the store's own rejections
+   * (`key_not_in_policy_allowlist`, `closed`) pass through as the per-entry
+   * reason. None of these fail the audit.
+   */
+  populateEvidence(req, entry) {
+    if (req.status !== "success" || !req.evidence || req.evidence.length === 0) {
+      return void 0;
+    }
+    const outcomes = [];
+    for (let i = 0; i < req.evidence.length; i++) {
+      const e = req.evidence[i];
+      if (!e) continue;
+      if (i >= MAX_EVIDENCE_ENTRIES) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "too_many" });
+        continue;
+      }
+      const bytes = Buffer.byteLength(canonicalize(e.evidence_data ?? null), "utf8");
+      if (bytes > MAX_EVIDENCE_BYTES) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "too_large" });
+        continue;
+      }
+      if (!this.evidenceStore) {
+        outcomes.push({
+          evidence_key: e.evidence_key,
+          stored: false,
+          reason: "evidence_unavailable"
+        });
+        continue;
+      }
+      if (!entry.sessionId) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "no_session" });
+        continue;
+      }
+      const result = this.evidenceStore.putEvidence(entry.sessionId, {
+        evidence_key: e.evidence_key,
+        data: e.evidence_data,
+        tool_name: entry.toolName,
+        ttl_seconds: e.ttl_seconds
+      });
+      outcomes.push(
+        result.stored ? { evidence_key: e.evidence_key, stored: true } : { evidence_key: e.evidence_key, stored: false, reason: result.reason }
+      );
+    }
+    return outcomes;
   }
   // -------------------------------------------------------------------------
   // POST /install-scan — evaluates install-time policy (issue #13)
@@ -7969,6 +8045,13 @@ function warnIfDashboardOpenMode(config, log = console.error) {
   );
   return true;
 }
+function warnIfNoEnforcement(policy, log = console.error) {
+  if (policy.rules.length > 0 || policy.defaultAction !== "allow" || policy.dryRun) return false;
+  log(
+    '[helio] No policy rules are loaded and the default action is "allow" - Helio is recording an audit trail but NOT blocking anything. Add rules under `policies:` in helio.yaml to start enforcing (see docs/policies.md).'
+  );
+  return true;
+}
 
 // src/crash-drain.ts
 var hooks = [];
@@ -8041,18 +8124,6 @@ upstream:
 #   headers:
 #     Authorization: "Bearer \${UPSTREAM_TOKEN}"
 
-# Operator dashboard + approval REST API. Bound to 127.0.0.1 by default \u2014 do
-# not change to 0.0.0.0 without putting an authenticating reverse proxy in
-# front. dashboard.api_secret is the manual dashboard login secret and also
-# supports machine Bearer auth for sideband API clients. Store it safely; it
-# stays valid until you rotate it. Rotate by editing this file and restarting
-# (or hot-reloading) the proxy. Rotation invalidates active dashboard sessions.
-dashboard:
-  enabled: true
-  port: 3100
-  host: 127.0.0.1
-  api_secret: "${apiSecret}"
-
 # listen:
 #   port: 3000
 #   host: 127.0.0.1
@@ -8073,6 +8144,18 @@ dashboard:
 #   retention: 90d
 #   include_responses: true
 
+# Operator dashboard + approval REST API. Bound to 127.0.0.1 by default \u2014 do
+# not change to 0.0.0.0 without putting an authenticating reverse proxy in
+# front. dashboard.api_secret is the manual dashboard login secret and also
+# supports machine Bearer auth for sideband API clients. Store it safely; it
+# stays valid until you rotate it. Rotate by editing this file and restarting
+# (or hot-reloading) the proxy. Rotation invalidates active dashboard sessions.
+dashboard:
+  enabled: true
+  port: 3100
+  host: 127.0.0.1
+  api_secret: "${apiSecret}"
+
 # sdk:
 #   enabled: false
 #   port: 3200
@@ -8368,6 +8451,7 @@ async function startCommand(configPath, options) {
   console.error(
     `Policies: ${String(ruleCount)} rule${ruleCount !== 1 ? "s" : ""} loaded (default: ${policy.defaultAction})`
   );
+  warnIfNoEnforcement(policy);
   if (config.upstream.transport === "stdio") {
     console.error(`Upstream: ${config.upstream.command ?? ""} (stdio)`);
   } else {

package/dist/index.d.ts

@@ -1932,6 +1932,11 @@ interface InstallScanInput {
     };
     readonly metadata: Record<string, unknown> | null;
 }
+interface AuditEvidenceInput {
+    readonly evidence_key: string;
+    readonly evidence_data: unknown;
+    readonly ttl_seconds?: number;
+}
 interface AuditInput {
     readonly evaluation_id: string;
     readonly status: 'success' | 'error' | 'not_executed';
@@ -1939,6 +1944,12 @@ interface AuditInput {
     readonly duration_ms?: number;
     readonly result?: unknown;
     readonly actual_amount?: number;
+    /**
+     * Optional evidence to populate on a successfully-audited call (issue #11). Adapter-scoped, single-token evidence write: bound to the pending
+     * evaluation's session/tool, success-only, first-finalize-only. Every
+     * per-entry failure is soft (reported, never request-fatal) — see audit().
+     */
+    readonly evidence?: ReadonlyArray<AuditEvidenceInput>;
 }
 interface ResolveApprovalInput {
     readonly resolution: 'approved' | 'denied' | 'timeout' | 'cancelled';
@@ -2004,6 +2015,19 @@ declare class GovernanceService {
     updatePolicy(policy: CompiledPolicy): void;
     evaluate(req: EvaluateInput): ServiceResult;
     audit(req: AuditInput, payloadHash: string): ServiceResult;
+    /**
+     * Write the optional `/audit` evidence entries for a successful call
+     * (issue #11), returning a per-entry outcome list — or `undefined`
+     * when there is nothing to report (non-success status, or no evidence
+     * supplied). Caps are enforced here, NOT in route validation, so an over-cap
+     * entry soft-drops without discarding the audit row: entries past
+     * `MAX_EVIDENCE_ENTRIES` → `too_many`; oversized `evidence_data` →
+     * `too_large`; no evidence store on the service → `evidence_unavailable`;
+     * a sessionless evaluation → `no_session`; the store's own rejections
+     * (`key_not_in_policy_allowlist`, `closed`) pass through as the per-entry
+     * reason. None of these fail the audit.
+     */
+    private populateEvidence;
     installScan(req: InstallScanInput): ServiceResult;
     /** First-match-wins evaluation of the compiled install policy (issue #13). */
     private evaluateInstall;

package/dist/index.js

@@ -4584,13 +4584,22 @@ var installScanBody = z4.object({
   }),
   metadata: metadataSchema
 });
+var evidenceEntrySchema = z4.object({
+  evidence_key: z4.string().min(1),
+  evidence_data: z4.unknown().refine((v) => v !== void 0, { message: "Required" }),
+  ttl_seconds: z4.number().int().positive().optional()
+});
 var auditBody = z4.object({
   evaluation_id: z4.string().min(1),
   status: z4.enum(["success", "error", "not_executed"]),
   error: z4.string().optional(),
   duration_ms: z4.number().optional(),
   result: z4.unknown().optional(),
-  actual_amount: z4.number().optional()
+  actual_amount: z4.number().optional(),
+  // No `.max()` / size refinement here on purpose (issue #11): caps are
+  // enforced per-entry in GovernanceService.populateEvidence as soft-drops, so
+  // an over-cap entry never 400s away the audit row for a call that already ran.
+  evidence: z4.array(evidenceEntrySchema).optional()
 });
 var resolveBody = z4.object({
   resolution: z4.enum(["approved", "denied", "timeout", "cancelled"]),
@@ -4692,10 +4701,19 @@ function auditPayloadHash(data) {
     error: data.error ?? null,
     duration_ms: data.duration_ms ?? null,
     result: data.result ?? null,
-    actual_amount: data.actual_amount ?? null
+    actual_amount: data.actual_amount ?? null,
+    evidence: canonicalEvidence(data.evidence)
   };
   return createHash2("sha256").update(canonicalize(semantic)).digest("hex");
 }
+function canonicalEvidence(evidence) {
+  if (!evidence || evidence.length === 0) return null;
+  return evidence.map((e) => ({
+    evidence_key: e.evidence_key,
+    evidence_data: e.evidence_data ?? null,
+    ttl_seconds: e.ttl_seconds ?? null
+  })).map((norm) => ({ sortKey: canonicalize(norm), norm })).sort((a, b) => a.sortKey < b.sortKey ? -1 : a.sortKey > b.sortKey ? 1 : 0).map((x) => x.norm);
+}
 function asStatus(status) {
   return status;
 }
@@ -4828,6 +4846,8 @@ var MAX_TOOL_INPUT_BYTES = 64 * 1024;
 var MAX_PENDING_COUNT = 1e4;
 var MAX_PENDING_BYTES = 64 * 1024 * 1024;
 var MAX_SENDER_KEYS = 5e4;
+var MAX_EVIDENCE_ENTRIES = 16;
+var MAX_EVIDENCE_BYTES = 64 * 1024;
 var SWEEP_INTERVAL_MS2 = 3e4;
 var GovernanceService = class {
   policy;
@@ -5118,6 +5138,7 @@ var GovernanceService = class {
     if (callHappened && this.evidenceStore && entry.sessionId) {
       this.evidenceStore.recordToolCall(entry.sessionId, entry.toolName, req.status === "success");
     }
+    const evidenceOutcomes = this.populateEvidence(req, entry);
     const auditId = this.writeAudit({
       timestampIso: entry.timestampIso,
       origin: entry.origin,
@@ -5147,7 +5168,62 @@ var GovernanceService = class {
       finalizedBy: "audit",
       expiresAtMs: this.now() + this.ttlMs
     });
-    return { status: 201, body: { ok: true, audit_record_id: auditId } };
+    const body = { ok: true, audit_record_id: auditId };
+    if (evidenceOutcomes) body["evidence"] = evidenceOutcomes;
+    return { status: 201, body };
+  }
+  /**
+   * Write the optional `/audit` evidence entries for a successful call
+   * (issue #11), returning a per-entry outcome list — or `undefined`
+   * when there is nothing to report (non-success status, or no evidence
+   * supplied). Caps are enforced here, NOT in route validation, so an over-cap
+   * entry soft-drops without discarding the audit row: entries past
+   * `MAX_EVIDENCE_ENTRIES` → `too_many`; oversized `evidence_data` →
+   * `too_large`; no evidence store on the service → `evidence_unavailable`;
+   * a sessionless evaluation → `no_session`; the store's own rejections
+   * (`key_not_in_policy_allowlist`, `closed`) pass through as the per-entry
+   * reason. None of these fail the audit.
+   */
+  populateEvidence(req, entry) {
+    if (req.status !== "success" || !req.evidence || req.evidence.length === 0) {
+      return void 0;
+    }
+    const outcomes = [];
+    for (let i = 0; i < req.evidence.length; i++) {
+      const e = req.evidence[i];
+      if (!e) continue;
+      if (i >= MAX_EVIDENCE_ENTRIES) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "too_many" });
+        continue;
+      }
+      const bytes = Buffer.byteLength(canonicalize(e.evidence_data ?? null), "utf8");
+      if (bytes > MAX_EVIDENCE_BYTES) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "too_large" });
+        continue;
+      }
+      if (!this.evidenceStore) {
+        outcomes.push({
+          evidence_key: e.evidence_key,
+          stored: false,
+          reason: "evidence_unavailable"
+        });
+        continue;
+      }
+      if (!entry.sessionId) {
+        outcomes.push({ evidence_key: e.evidence_key, stored: false, reason: "no_session" });
+        continue;
+      }
+      const result = this.evidenceStore.putEvidence(entry.sessionId, {
+        evidence_key: e.evidence_key,
+        data: e.evidence_data,
+        tool_name: entry.toolName,
+        ttl_seconds: e.ttl_seconds
+      });
+      outcomes.push(
+        result.stored ? { evidence_key: e.evidence_key, stored: true } : { evidence_key: e.evidence_key, stored: false, reason: result.reason }
+      );
+    }
+    return outcomes;
   }
   // -------------------------------------------------------------------------
   // POST /install-scan — evaluates install-time policy (issue #13)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethelio/proxy",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Open-source MCP governance proxy for AI agents",
   "license": "Apache-2.0",
@@ -61,7 +61,7 @@
     "better-sqlite3": "12.8.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
-    "hono": "4.12.14",
+    "hono": "4.12.26",
     "js-yaml": "4.1.1",
     "picomatch": "4.0.4",
     "safe-regex2": "5.0.0",