gateia 0.1.2 → 0.1.4

package/README.md

@@ -33,14 +33,14 @@ const result = await gate({
   model: "gpt-4.1",
   prompt: "Analyze this refund request against policy...", 
   contract: RefundSchema,
-  policies: ["support-safe", "no-hallucinations"]
+  policies: ["support-safe"]
 });
 
 console.log(result.safeOutput);
 // { valid: true, reason: "Item damaged in transit", refund_amount: 49.99 }
 
 console.log(result.enforcement.appliedPolicies); 
-// ['finance-safe', 'no-hallucinations']
+// [{ id: 'finance-safe', outcome: 'pass' }]
 
 console.log(result.traceId);
 // "uuid..."
@@ -69,22 +69,92 @@ GATEIA_MOCK_ADAPTERS=true
 - `policies`: Array of policy IDs (strings) or Policy objects.
 - `behavior`: Logic for repair, retries, and blocking.
 
+**Returns:** `Promise<GateResult<T>>`
+
+```typescript
+type GateResult<T> = {
+  safeOutput?: T;                 // Type-safe validated output
+  traceId: string;                // Unique ID for this request
+  
+  enforcement: {
+    appliedPolicies: Array<{
+      id: string;
+      mode: "enforce" | "audit";
+      outcome: "pass" | "warn" | "block";
+      reasons?: string[];
+    }>;
+    
+    contract: {
+      outcome: "pass" | "fail" | "repaired";
+      errors?: Array<{ path: string; message: string }>;
+    };
+    
+    actions: Array<{ type: "rewrite" | "block"; policyId?: string; }>;
+    violations: Array<{ 
+      policyId: string; 
+      code: string; 
+      severity: "low"|"med"|"high"; 
+      message: string; 
+    }>;
+  };
+
+  usage: {
+    model: string;
+    provider: string;
+    latencyMs: number;
+    tokens?: { prompt: number; completion: number; total: number };
+    costUsd?: number;
+  };
+};
+```
+
 ### Policies
 
-Gateia includes built-in policies:
-- `finance-safe`: Blocks "guaranteed returns".
-- `no-hallucinations`: (Audit only) Placeholder for hallucination checks.
+## Policy Library
 
-You can define custom policies:
+Gateia comes with a set of built-in policies you can use immediately.
+
+| Policy ID | Function | Checks For | Outcome |
+|-----------|----------|------------|---------|
+| **`finance-safe`** | Financial Compliance | "Guaranteed returns", "No risk", "Guaranteed approval", "100% guaranteed" | `BLOCK` |
+| **`support-safe`** | Support Safety (Alias) | Same as above. Useful for refund processing agents. | `BLOCK` |
+| **`pii-safe`** | Data Privacy | Email addresses (`x@y.com`), Phone numbers (Format: `123-456-7890`) | `BLOCK` |
+| **`secrets-safe`** | Security | API Keys (OpenAI, AWS, GitHub), Private Keys | `BLOCK` |
+| **`markup-safe`** | XSS Prevention | `<script>`, `<iframe>`, `javascript:` URIs | `BLOCK` |
+
+### Custom Policies
 ```typescript
-{
-  id: "my-policy",
-  mode: "enforce",
+import { gate, Policy } from 'gateia';
+
+// 1. Define your custom policy
+const noCompetitors: Policy = {
+  id: 'no-competitors',
+  mode: 'enforce', // 'audit' to just warn
   check: (output) => {
-    if (output.includes("bad word")) {
-      return { outcome: "block", violations: [...] };
+    // output is strict typed from your Contract (or string if simple)
+    const text = JSON.stringify(output).toLowerCase();
+    
+    if (text.includes('acme corp')) {
+        return {
+           outcome: 'block',
+           violations: [{
+               policyId: 'no-competitors',
+               code: 'COMPETITOR_MENTION',
+               message: 'Mentioned competitor Acme Corp',
+               severity: 'high',
+               evidence: { snippet: 'acme corp' }
+           }]
+        };
     }
-    return { outcome: "pass" };
+    return { outcome: 'pass' };
   }
-}
+};
+
+// 2. Use it in the gate
+await gate({
+  model: 'gpt-4',
+  prompt: 'Who is the best provider?',
+  contract: z.string(),
+  policies: ['finance-safe', noCompetitors] // Mix built-in ID strings and custom objects
+});
 ```

package/dist/engine/contract.d.ts

@@ -3,6 +3,10 @@ export interface ContractResult<T> {
     success: boolean;
     data?: T;
     error?: string;
+    errors?: {
+        path: string;
+        message: string;
+    }[];
 }
 export declare class ContractEngine {
     validate<T>(data: any, schema: z.ZodType<T>): ContractResult<T>;

package/dist/engine/contract.js

@@ -8,10 +8,14 @@ class ContractEngine {
             return { success: true, data: result.data };
         }
         else {
-            const errorMsg = result.error.errors
-                .map((e) => `${e.path.join('.')}: ${e.message}`)
+            const formattedErrors = result.error.errors.map(e => ({
+                path: e.path.join('.'),
+                message: e.message
+            }));
+            const errorMsg = formattedErrors
+                .map((e) => `${e.path}: ${e.message}`)
                 .join('; ');
-            return { success: false, error: errorMsg };
+            return { success: false, error: errorMsg, errors: formattedErrors };
         }
     }
     // Helper to format error for the LLM repair prompt

package/dist/index.js

@@ -21,8 +21,8 @@ const uuid_1 = require("uuid");
 const registry_1 = require("./adapters/registry");
 const contract_1 = require("./engine/contract");
 const policy_1 = require("./engine/policy");
-const defaults_1 = require("./engine/defaults");
-// Global instances (lazy init or singleton)
+const policies_1 = require("./policies");
+// Global instances
 const registry = new registry_1.ModelRegistry();
 const contractEngine = new contract_1.ContractEngine();
 const policyEngine = new policy_1.PolicyEngine();
@@ -35,7 +35,7 @@ async function gate(params) {
         // 2. Resolve Policies
         const activePolicies = policies.map(p => {
             if (typeof p === 'string') {
-                const found = defaults_1.predefinedPolicies[p];
+                const found = policies_1.policyLibrary[p];
                 if (!found)
                     throw new types_1.GateiaError(`Unknown policy: ${p}`, traceId);
                 return found;
@@ -126,15 +126,30 @@ async function gate(params) {
                 }
             }
         }
+        // Construct usage object
+        const finalUsage = {
+            provider: registry.getAdapter(model).constructor.name,
+            model: params.model,
+            latencyMs: finalLatency,
+            inputTokens: totalTokens.prompt,
+            outputTokens: totalTokens.completion,
+            totalTokens: totalTokens.total,
+            // costUsd: ... // TODO: Add cost calculation logic based on provider/model
+        };
         if (!finalSafeOutput) {
             // Block/Throw
             // Construct report
             const report = {
-                appliedPolicies: activePolicies.map(p => p.id),
-                contractOutcome: 'fail',
+                appliedPolicies: [], // Policies not applied due to contract failure
+                contract: {
+                    outcome: 'fail',
+                    errors: contractEngine.validate(rawResult, contract).errors // re-running valid logic or grabbing from lastError
+                },
                 actions: [],
-                violations: [{ policyId: 'contract', message: lastError || "Contract Validation Failed", severity: 'critical' }]
+                violations: [{ policyId: 'contract', code: 'CONTRACT_FAIL', message: lastError || "Contract Validation Failed", severity: 'high' }]
             };
+            // For accurate errors we might want to capture them better above instead of re-running or assuming lastError string
+            // But for now this matches structure.
             throw new types_1.GateiaError("Contract Check Failed", traceId, report);
         }
         // 4. Apply Policies
@@ -144,47 +159,54 @@ async function gate(params) {
         const policyResult = await policyEngine.evaluate(activePolicies, finalSafeOutput, policyCtx);
         let finalViolations = policyResult.violations || [];
         let enforcementActions = [];
+        // Detailed policy reporting
+        const appliedRecs = activePolicies.map(p => {
+            const policyViolations = finalViolations.filter(v => v.policyId === p.id);
+            let outcome = 'pass';
+            if (policyViolations.length > 0) {
+                const isBlock = policyViolations.some(v => v.severity === 'high');
+                outcome = isBlock ? 'block' : 'warn';
+            }
+            return {
+                id: p.id,
+                version: p.version,
+                mode: p.mode || 'enforce',
+                outcome,
+                reasons: policyViolations.map(v => v.message)
+            };
+        });
         if (policyResult.rewrittenOutput) {
             finalSafeOutput = policyResult.rewrittenOutput;
-            enforcementActions.push('rewritten');
+            enforcementActions.push({ type: 'rewrite', policyId: 'policy-engine', note: 'Content rewritten by policy' });
         }
+        const report = {
+            appliedPolicies: appliedRecs,
+            contract: {
+                outcome: contractOutcome,
+                // If repaired, we could list repairs here if we tracked them detailly
+            },
+            actions: enforcementActions,
+            violations: finalViolations
+        };
         if (policyResult.outcome === 'block') {
-            const report = {
-                appliedPolicies: activePolicies.map(p => p.id),
-                contractOutcome,
-                actions: enforcementActions,
-                violations: finalViolations
-            };
             const onBlock = behavior?.onBlock || 'throw'; // Default throw?
             if (onBlock === 'throw') {
                 throw new types_1.GateiaError("Policy Blocked Response", traceId, report);
             }
             // Return with no safeOutput? Or just raw?
-            // Result<T> safeOutput is optional.
             return {
+                safeOutput: undefined,
                 traceId,
                 enforcement: report,
-                usage: { provider: 'unknown', model: params.model, tokens: totalTokens }, // TODO: propagate provider name
-                safeOutput: undefined
+                usage: finalUsage,
+                rawOutput: options?.includeRawOutput ? rawResult : undefined
             };
         }
-        // Success
-        const report = {
-            appliedPolicies: activePolicies.map(p => p.id),
-            contractOutcome,
-            actions: enforcementActions,
-            violations: finalViolations
-        };
         return {
             safeOutput: finalSafeOutput,
             traceId,
             enforcement: report,
-            usage: {
-                provider: registry.getAdapter(model).constructor.name, // quick hack name
-                model: params.model,
-                tokens: totalTokens,
-                latencyMs: finalLatency
-            },
+            usage: finalUsage,
             rawOutput: options?.includeRawOutput ? rawResult : undefined
         };
     }

package/dist/policies/finance.d.ts

@@ -0,0 +1,8 @@
+import { Policy } from '../types';
+export declare const financeSafe: Policy;
+export declare const supportSafe: {
+    id: string;
+    version?: string;
+    mode?: "enforce" | "audit";
+    check: (output: any, context: import("../types").PolicyContext) => import("../types").PolicyResult | Promise<import("../types").PolicyResult>;
+};

package/dist/policies/finance.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportSafe = exports.financeSafe = void 0;
+exports.financeSafe = {
+    id: 'finance-safe',
+    mode: 'enforce',
+    check: (output) => {
+        const text = typeof output === 'string' ? output : JSON.stringify(output);
+        const lower = text.toLowerCase();
+        // Block guarantees
+        const forbidden = [
+            'guaranteed refund',
+            'guaranteed return',
+            'guaranteed approval',
+            'no risk',
+            '100% guaranteed'
+        ];
+        const match = forbidden.find(phrase => lower.includes(phrase));
+        if (match) {
+            return {
+                outcome: 'block',
+                violations: [{
+                        policyId: 'finance-safe',
+                        code: 'FIN_GUARANTEE',
+                        message: `Contains forbidden guarantee language: "${match}"`,
+                        severity: 'high',
+                        evidence: { snippet: match }
+                    }]
+            };
+        }
+        return { outcome: 'pass' };
+    }
+};
+// Delegate alias
+exports.supportSafe = { ...exports.financeSafe, id: 'support-safe' };

package/dist/policies/index.d.ts

@@ -0,0 +1,6 @@
+import { Policy } from '../types';
+export declare const policyLibrary: Record<string, Policy>;
+export * from './finance';
+export * from './pii';
+export * from './secrets';
+export * from './markup';

package/dist/policies/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.policyLibrary = void 0;
+const finance_1 = require("./finance");
+const pii_1 = require("./pii");
+const secrets_1 = require("./secrets");
+const markup_1 = require("./markup");
+// Registry of all built-in policies
+exports.policyLibrary = {
+    'finance-safe': finance_1.financeSafe,
+    'support-safe': finance_1.supportSafe,
+    'pii-safe': pii_1.piiSafe,
+    'secrets-safe': secrets_1.secretsSafe,
+    'markup-safe': markup_1.markupSafe
+};
+__exportStar(require("./finance"), exports);
+__exportStar(require("./pii"), exports);
+__exportStar(require("./secrets"), exports);
+__exportStar(require("./markup"), exports);

package/dist/policies/markup.d.ts

@@ -0,0 +1,2 @@
+import { Policy } from '../types';
+export declare const markupSafe: Policy;

package/dist/policies/markup.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markupSafe = void 0;
+exports.markupSafe = {
+    id: 'markup-safe',
+    mode: 'enforce',
+    check: (output) => {
+        const text = typeof output === 'string' ? output : JSON.stringify(output);
+        const lower = text.toLowerCase();
+        // Dangerous HTML/Script patterns
+        const patterns = [
+            { name: 'Script Tag', regex: /<script[\s\S]*?>/i },
+            { name: 'Iframe Tag', regex: /<iframe[\s\S]*?>/i },
+            { name: 'Object Tag', regex: /<object[\s\S]*?>/i },
+            { name: 'Javascript Protocol', regex: /javascript:/i }
+        ];
+        const violations = [];
+        for (const pattern of patterns) {
+            if (pattern.regex.test(text)) {
+                violations.push({
+                    policyId: 'markup-safe',
+                    code: 'UNSAFE_MARKUP',
+                    message: `Unsafe markup detected: ${pattern.name}`,
+                    severity: 'high',
+                    evidence: { snippet: pattern.regex.source }
+                });
+            }
+        }
+        if (violations.length > 0) {
+            return { outcome: 'block', violations };
+        }
+        return { outcome: 'pass' };
+    }
+};

package/dist/policies/pii.d.ts

@@ -0,0 +1,2 @@
+import { Policy } from '../types';
+export declare const piiSafe: Policy;

package/dist/policies/pii.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.piiSafe = void 0;
+exports.piiSafe = {
+    id: 'pii-safe',
+    mode: 'enforce',
+    check: (output) => {
+        const text = typeof output === 'string' ? output : JSON.stringify(output);
+        // Simple regex patterns (for MVP)
+        const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
+        const phoneRegex = /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/; // US-centric simple
+        const violations = [];
+        if (emailRegex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_EMAIL',
+                message: 'Email address detected in output',
+                severity: 'high',
+                evidence: { snippet: 'email-detected-redacted' }
+            });
+        }
+        if (phoneRegex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_PHONE',
+                message: 'Phone number detected in output',
+                severity: 'high',
+                evidence: { snippet: 'phone-detected-redacted' }
+            });
+        }
+        if (violations.length > 0) {
+            return { outcome: 'block', violations };
+        }
+        return { outcome: 'pass' };
+    }
+};

package/dist/policies/secrets.d.ts

@@ -0,0 +1,2 @@
+import { Policy } from '../types';
+export declare const secretsSafe: Policy;

package/dist/policies/secrets.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secretsSafe = void 0;
+exports.secretsSafe = {
+    id: 'secrets-safe',
+    mode: 'enforce',
+    check: (output) => {
+        const text = typeof output === 'string' ? output : JSON.stringify(output);
+        // Common patterns for API keys and secrets
+        const patterns = [
+            { name: 'OpenAI Key', regex: /sk-[a-zA-Z0-9]{20,}/ },
+            { name: 'AWS Access Key', regex: /AKIA[0-9A-Z]{16}/ },
+            { name: 'Generic Private Key', regex: /-----BEGIN PRIVATE KEY-----/ },
+            { name: 'GitHub Token', regex: /ghp_[a-zA-Z0-9]{36}/ }
+        ];
+        const violations = [];
+        for (const pattern of patterns) {
+            if (pattern.regex.test(text)) {
+                violations.push({
+                    policyId: 'secrets-safe',
+                    code: 'SECRET_DETECTED',
+                    message: `Potential ${pattern.name} detected`,
+                    severity: 'high',
+                    evidence: { snippet: 'REDACTED_SECRET' } // Never show the secret
+                });
+            }
+        }
+        if (violations.length > 0) {
+            return { outcome: 'block', violations };
+        }
+        return { outcome: 'pass' };
+    }
+};

package/dist/types.d.ts

@@ -1,10 +1,18 @@
 import { z } from 'zod';
 export type GateOutcome = 'pass' | 'block' | 'warn' | 'rewrite';
-export type PolicyAction = 'rewrite' | 'block' | 'log';
+export interface PolicyAction {
+    type: 'rewrite' | 'block' | 'log';
+    policyId: string;
+    note?: string;
+}
 export interface Violation {
     policyId: string;
+    code: string;
     message: string;
-    severity: 'critical' | 'warn';
+    severity: 'low' | 'med' | 'high';
+    evidence?: {
+        snippet: string;
+    };
 }
 export interface PolicyContext {
     model: string;
@@ -48,21 +56,40 @@ export interface GateParams<T extends z.ZodTypeAny> {
     behavior?: GateBehavior;
     options?: GateOptions;
 }
+export interface AppliedPolicyRec {
+    id: string;
+    version?: string;
+    mode: 'enforce' | 'audit';
+    outcome: GateOutcome;
+    reasons?: string[];
+}
+export interface ContractEnforcement {
+    name?: string;
+    outcome: 'pass' | 'fail' | 'repaired';
+    errors?: {
+        path: string;
+        message: string;
+    }[];
+    repairs?: {
+        op: 'add' | 'remove' | 'replace';
+        path: string;
+        note?: string;
+    }[];
+}
 export interface GateEnforcementReport {
-    appliedPolicies: string[];
-    contractOutcome: 'pass' | 'fail' | 'repaired';
-    actions: string[];
+    appliedPolicies: AppliedPolicyRec[];
+    contract: ContractEnforcement;
+    actions: PolicyAction[];
     violations: Violation[];
 }
 export interface GateUsage {
     provider: string;
     model: string;
-    latencyMs?: number;
-    tokens?: {
-        prompt: number;
-        completion: number;
-        total: number;
-    };
+    latencyMs: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
 }
 export interface GateResult<T> {
     safeOutput?: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gateia",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The trust layer for AI in production. Middleware for model routing, contract enforcement, and policy compliance.",
   "keywords": [
     "ai",