gateia 0.2.1 → 0.2.2

package/README.md

@@ -14,18 +14,18 @@
 
 ---
 
-**Gateia** is the standard for implementing **Deterministic Guardrails** in AI applications. It acts as a final, immutable security layer between your AI models and your customers.
+**Gateia** is a deterministic verification layer for AI applications. It acts as a final, immutable security gate between your models and your customers.
 
-Unlike "AI-judging-AI" solutions, Gateia enables you to enforce **strict, code-based contracts**, ensuring that your application never halluncinates, leaks PII, or violates business rules—regardless of the underlying model (OpenAI, Anthropic, or Llama).
+Unlike "AI-judging-AI" solutions, Gateia enforces **strict, code-based contracts** and deterministic policies that block known unsafe patterns—regardless of the underlying model (OpenAI, Anthropic, or Llama).
 
 ## 🚀 Why Gateia?
 
 In production, **probability is a liability.** Gateia restores deterministic control.
 
-*   **🛡️ Zero Hallucination Policy**: Gateia does not use LLMs to verify. It uses deterministic logic and regex engines. It is impossible for the verifier to hallucinate.
+*   **🛡️ Deterministic Verification**: Gateia does not use LLMs to verify. It uses deterministic logic and regex engines to validate outputs.
 *   **🏗️ Contract-First Architecture**: Define your data requirements with Zod schemas. If the output doesn't match, it doesn't ship.
 *   **📋 Audit-Ready Logging**: Every decision is traced, logged, and categorized by severity, making compliance (SOC2, HIPAA) audits straightforward.
-*   **🔒 Fail-Closed Security**: If a policy returns a block signal (even with malformed data), Gateia defaults to blocking. Security is never compromised by runtime errors.
+*   **🔒 Fail-Closed Security**: If a policy returns a block signal (even with malformed data), Gateia defaults to blocking.
 
 ---
 
@@ -39,45 +39,21 @@ npm install gateia zod
 
 ## ⚡️ Quick Start
 
-**Scenario:** You have an AI Customer Support Agent. You need to ensure it **never** promises refunds it can't deliver, and **never** leaks customer PII.
+**Scenario:** You have an AI Customer Support Agent. You need to block refund guarantees and PII.
 
 ```typescript
-import { verify } from 'gateia';
-import { z } from 'zod';
-
-// 1. Define the "Safe Reply" Contract
-// The AI must generate a Draft Reply that fits this structure.
-const CustomerSupportContract = z.object({
-  sentiment: z.enum(['happy', 'neutral', 'angry']),
-  reply_text: z.string(),
-  ticket_status: z.enum(['open', 'resolved', 'escalated']),
-  requires_human_review: z.boolean()
-});
+import { verify } from "gateia";
+import { z } from "zod";
 
-// 2. The Verification Step
-// Call this *after* obtaining the LLM response, but *before* sending it to the user.
-const result = await verify({
-  output: llmResponse, 
-  contract: CustomerSupportContract,
-  policies: [
-      'finance-safe', // Block any unauthorized refund promises
-      'pii-safe',     // Redact any leaked phone numbers/emails
-  ],
-  mode: 'enforce'
+const Reply = z.object({ reply: z.string() });
+
+const res = await verify({
+  output: { reply: "Refund guaranteed. Email me at test@example.com" }, // pretend this came from an LLM
+  contract: Reply,
+  policies: ["finance-safe", "pii-safe"]
 });
 
-// 3. Deterministic Decision
-if (!result.allowed) {
-  // 🛑 BLOCKED: The AI tried to say something unsafe.
-  // Action: Fallback to a canned response or route to human agent.
-  console.warn("Safety Violation:", result.enforcement.violations);
-  sendToUser("I'm having trouble retrieving that info. A human will be with you shortly.");
-} else {
-  // ✅ SAFE: The output adheres to your contract and policies.
-  // Action: Send the validated reply to the customer.
-  console.log("Verified Reply:", result.safeOutput.reply_text);
-  sendToUser(result.safeOutput.reply_text);
-}
+console.log(res.allowed ? "ALLOWED" : "BLOCKED");
 ```
 
 
@@ -90,7 +66,7 @@ Gateia ships with battle-tested policies for common enterprise risks.
 | Policy ID | Risk Category | Description | Severity |
 |-----------|---------------|-------------|----------|
 | `finance-safe` | **Compliance** | Blocks non-compliant guarantee language (e.g., "100% no risk", "guaranteed return"). | High |
-| `pii-safe` | **Privacy** | Redacts or blocks Personally Identifiable Information (Emails, Phone Numbers). | High |
+| `pii-safe` | **Privacy** | Blocks personally identifiable information (emails, phone numbers, etc.). | High |
 | `secrets-safe` | **Security** | Detects leaked API keys (AWS, Stripe, OpenAI, Slack) and private keys. | High |
 | `markup-safe` | **Security** | Prevents XSS by blocking `<script>`, `iframe`, and other HTML injection vectors. | High |
 
@@ -138,9 +114,12 @@ const result = await verify({
 
 Every call to `verify()` returns a comprehensive `EnforcementReport`. Use this for your internal dashboards and compliance logs.
 
+**Note:** `safeOutput` is always included on the response, but it will be `undefined` when `allowed === false` (contract failure or policy block).
+
 ```json
 {
   "allowed": false,
+  "safeOutput": null,
   "traceId": "123e4567-e89b-12d3-a456-426614174000",
   "enforcement": {
     "contract": { "outcome": "pass" },

package/dist/policies/finance.js

@@ -7,24 +7,46 @@ exports.financeSafe = {
     check: (output) => {
         const text = typeof output === 'string' ? output : JSON.stringify(output);
         const lower = text.toLowerCase();
-        // Block guarantees
-        const forbidden = [
+        // Block guarantees and absolute assurances (expanded patterns)
+        const forbiddenPhrases = [
             'guaranteed refund',
             'guaranteed return',
             'guaranteed approval',
+            'guaranteed payout',
+            'guaranteed profit',
+            'guaranteed results',
+            'risk free',
+            'risk-free',
             'no risk',
-            '100% guaranteed'
+            'zero risk',
+            '100% guaranteed',
+            'one hundred percent guaranteed',
+            'we will always refund',
+            'we always refund',
+            'instant refund',
+            'automatic refund',
+            'refund assured',
+            'money back guaranteed',
+            'guaranteed money back'
         ];
-        const match = forbidden.find(phrase => lower.includes(phrase));
-        if (match) {
+        const forbiddenRegexes = [
+            /\bguarantee(?:d|s|ing)?\b.{0,24}\b(refund|return|approval|payout|profit|results)\b/i,
+            /\b(refund|return|approval|payout|profit|results)\b.{0,24}\bguarantee(?:d|s|ing)?\b/i,
+            /\b100\s*%|\b100\s*percent|\b100\s*per\s*cent/i,
+            /\bno\s+risk\b|\bzero\s+risk\b|\brisk[-\s]?free\b/i,
+            /\b(always|never)\b.{0,24}\brefund\b/i
+        ];
+        const phraseMatch = forbiddenPhrases.find(phrase => lower.includes(phrase));
+        const regexMatch = forbiddenRegexes.find(regex => regex.test(text));
+        if (phraseMatch || regexMatch) {
             return {
                 outcome: 'block',
                 violations: [{
                         policyId: 'finance-safe',
                         code: 'FIN_GUARANTEE',
-                        message: `Contains forbidden guarantee language: "${match}"`,
+                        message: `Contains forbidden guarantee language: "${phraseMatch ?? 'regex-match'}"`,
                         severity: 'high',
-                        evidence: { snippet: match }
+                        evidence: { snippet: phraseMatch ?? 'regex-match' }
                     }]
             };
         }

package/dist/policies/markup.js

@@ -12,7 +12,12 @@ exports.markupSafe = {
             { 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 }
+            { name: 'Javascript Protocol', regex: /javascript:/i },
+            { name: 'Data URL', regex: /data:text\/html/i },
+            { name: 'Event Handler', regex: /\son\w+\s*=/i },
+            { name: 'SVG Tag', regex: /<svg[\s\S]*?>/i },
+            { name: 'Meta Refresh', regex: /<meta[\s\S]*?http-equiv=["']?refresh["']?/i },
+            { name: 'Base Tag', regex: /<base[\s\S]*?>/i }
         ];
         const violations = [];
         for (const pattern of patterns) {

package/dist/policies/pii.js

@@ -6,9 +6,15 @@ exports.piiSafe = {
     mode: 'enforce',
     check: (output) => {
         const text = typeof output === 'string' ? output : JSON.stringify(output);
-        // Simple regex patterns (for MVP)
+        // Expanded regex patterns (still heuristic)
         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 phoneRegexUS = /\b(?:\+?1[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}\b/;
+        const phoneRegexIntl = /\b\+?\d{1,3}[\s.-]?(?:\d{1,4}[\s.-]?){2,4}\d\b/;
+        const ssnRegex = /\b(?!000|666|9\d\d)\d{3}[- ]?(?!00)\d{2}[- ]?(?!0000)\d{4}\b/;
+        const creditCardRegex = /\b(?:\d[ -]*?){13,19}\b/;
+        const ipV4Regex = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/;
+        const ipV6Regex = /\b(?:[a-fA-F0-9]{1,4}:){7}[a-fA-F0-9]{1,4}\b/;
+        const dobRegex = /\b(?:19|20)\d{2}[-\/](?:0?[1-9]|1[0-2])[-\/](?:0?[1-9]|[12]\d|3[01])\b/; // YYYY-MM-DD or YYYY/MM/DD
         const violations = [];
         if (emailRegex.test(text)) {
             violations.push({
@@ -19,7 +25,7 @@ exports.piiSafe = {
                 evidence: { snippet: 'email-detected-redacted' }
             });
         }
-        if (phoneRegex.test(text)) {
+        if (phoneRegexUS.test(text) || phoneRegexIntl.test(text)) {
             violations.push({
                 policyId: 'pii-safe',
                 code: 'PII_PHONE',
@@ -28,6 +34,42 @@ exports.piiSafe = {
                 evidence: { snippet: 'phone-detected-redacted' }
             });
         }
+        if (ssnRegex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_SSN',
+                message: 'SSN detected in output',
+                severity: 'high',
+                evidence: { snippet: 'ssn-detected-redacted' }
+            });
+        }
+        if (creditCardRegex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_CREDIT_CARD',
+                message: 'Credit card number detected in output',
+                severity: 'high',
+                evidence: { snippet: 'cc-detected-redacted' }
+            });
+        }
+        if (ipV4Regex.test(text) || ipV6Regex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_IP',
+                message: 'IP address detected in output',
+                severity: 'med',
+                evidence: { snippet: 'ip-detected-redacted' }
+            });
+        }
+        if (dobRegex.test(text)) {
+            violations.push({
+                policyId: 'pii-safe',
+                code: 'PII_DOB',
+                message: 'Date of birth detected in output',
+                severity: 'high',
+                evidence: { snippet: 'dob-detected-redacted' }
+            });
+        }
         if (violations.length > 0) {
             return { outcome: 'block', violations };
         }

package/dist/policies/secrets.js

@@ -8,10 +8,19 @@ exports.secretsSafe = {
         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}/ }
+            { name: 'OpenAI Key', regex: /\bsk-[a-zA-Z0-9]{20,}\b/ },
+            { name: 'AWS Access Key', regex: /\bAKIA[0-9A-Z]{16}\b/ },
+            { name: 'AWS Secret Key', regex: /\b(?:aws|amazon)?[_-]?secret[_-]?access[_-]?key\b.{0,20}[A-Za-z0-9\/+=]{40}\b/i },
+            { name: 'Generic Private Key', regex: /-----BEGIN (?:RSA|EC|DSA|PGP)? ?PRIVATE KEY-----/ },
+            { name: 'GitHub Token', regex: /\bghp_[a-zA-Z0-9]{36}\b/ },
+            { name: 'GitHub Fine-grained Token', regex: /\bgithub_pat_[a-zA-Z0-9_]{82}\b/ },
+            { name: 'Slack Token', regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+            { name: 'Stripe Secret Key', regex: /\bsk_live_[A-Za-z0-9]{24}\b/ },
+            { name: 'Stripe Restricted Key', regex: /\brk_live_[A-Za-z0-9]{24}\b/ },
+            { name: 'Twilio API Key', regex: /\bSK[0-9a-fA-F]{32}\b/ },
+            { name: 'Mailgun API Key', regex: /\bkey-[0-9a-fA-F]{32}\b/ },
+            { name: 'Google API Key', regex: /\bAIza[0-9A-Za-z\-_]{35}\b/ },
+            { name: 'JWT', regex: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/ }
         ];
         const violations = [];
         for (const pattern of patterns) {

package/dist/types.d.ts

@@ -60,7 +60,7 @@ export interface EnforcementReport {
 }
 export interface VerifyResult<T> {
     allowed: boolean;
-    safeOutput?: T;
+    safeOutput: T | undefined;
     traceId: string;
     enforcement: EnforcementReport;
     rawOutput?: any;

package/dist/verify.js

@@ -12,6 +12,7 @@ const policyEngine = new policy_1.PolicyEngine();
 async function verify(params) {
     const traceId = (0, uuid_1.v4)();
     const { output, contract, policies = [], mode = 'enforce' } = params;
+    const includeRawOutput = params.options?.includeRawOutput ?? true;
     try {
         // --- 1. Contract Validation ---
         // (If output is string and contract is Object, we might want to try parsing it? 
@@ -118,7 +119,7 @@ async function verify(params) {
             safeOutput: allowed ? safeOutput : undefined,
             traceId,
             enforcement: report,
-            rawOutput: params.options?.includeRawOutput ? output : undefined
+            rawOutput: includeRawOutput ? output : undefined
         };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gateia",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "The Deterministic Verification Layer for Enterprise AI.",
   "keywords": [
     "ai",