@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/conformance/test-runner.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+/**
+ * Simple test script to verify the conformance runner works
+ * This is a fallback for when TypeScript compilation isn't available
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Mock implementations for testing
+class MockValidator {
+  async validatePassport(passport) {
+    return { valid: true, errors: [] };
+  }
+
+  async validateDecision(decision) {
+    return { valid: true, errors: [] };
+  }
+
+  async validateContext(packId, context) {
+    return { valid: true, errors: [] };
+  }
+}
+
+class MockJCS {
+  canonicalize(obj) {
+    return JSON.stringify(obj, Object.keys(obj).sort());
+  }
+
+  async computePassportDigest(passport) {
+    return "sha256:test_digest";
+  }
+}
+
+class MockEd25519 {
+  async verify(message, signature, publicKey) {
+    return true;
+  }
+
+  async verifyDecisionSignature(decision, signature, publicKey) {
+    return true;
+  }
+
+  async verifyPassportDigest(passport, digest) {
+    return true;
+  }
+}
+
+// Simple test runner
+class SimpleTestRunner {
+  constructor() {
+    this.validator = new MockValidator();
+    this.jcs = new MockJCS();
+    this.ed25519 = new MockEd25519();
+  }
+
+  async run() {
+    console.log("🔍 OAP Conformance Test Runner v1.0.0 (Simple Mode)\n");
+
+    try {
+      // Load test cases
+      const testCases = await this.loadTestCases();
+      console.log(`✅ Loaded ${testCases.length} test cases`);
+
+      // Run tests
+      const results = await this.runTests(testCases);
+
+      // Display results
+      this.displayResults(results);
+    } catch (error) {
+      console.error("❌ Test execution failed:", error.message);
+      process.exit(1);
+    }
+  }
+
+  async loadTestCases() {
+    const casesDir = path.join(__dirname, "cases");
+    const testCases = [];
+
+    if (!fs.existsSync(casesDir)) {
+      console.warn("⚠️  No test cases directory found");
+      return testCases;
+    }
+
+    const packDirs = fs
+      .readdirSync(casesDir, { withFileTypes: true })
+      .filter((dirent) => dirent.isDirectory())
+      .map((dirent) => path.join(casesDir, dirent.name));
+
+    for (const packDir of packDirs) {
+      const packId = path.basename(packDir);
+      const packCases = await this.loadPackTestCases(packDir, packId);
+      testCases.push(...packCases);
+    }
+
+    return testCases;
+  }
+
+  async loadPackTestCases(packDir, packId) {
+    const testCases = [];
+
+    try {
+      const passportsDir = path.join(packDir, "passports");
+      const contextsDir = path.join(packDir, "contexts");
+      const expectedDir = path.join(packDir, "expected");
+
+      if (
+        !fs.existsSync(passportsDir) ||
+        !fs.existsSync(contextsDir) ||
+        !fs.existsSync(expectedDir)
+      ) {
+        console.warn(`⚠️  Skipping ${packId}: missing required directories`);
+        return testCases;
+      }
+
+      const passportFiles = fs
+        .readdirSync(passportsDir)
+        .filter((f) => f.endsWith(".json"));
+      const contextFiles = fs
+        .readdirSync(contextsDir)
+        .filter((f) => f.endsWith(".json"));
+      const expectedFiles = fs
+        .readdirSync(expectedDir)
+        .filter((f) => f.endsWith(".json"));
+
+      for (const contextFile of contextFiles) {
+        const contextName = contextFile.replace(".json", "");
+        const expectedFile = expectedFiles.find((f) => f.includes(contextName));
+
+        if (!expectedFile) {
+          console.warn(`⚠️  No expected result for context: ${contextName}`);
+          continue;
+        }
+
+        const testCase = {
+          id: `${packId}:${contextName}`,
+          packId,
+          contextName,
+          passport: JSON.parse(
+            fs.readFileSync(path.join(passportsDir, passportFiles[0]), "utf-8")
+          ),
+          context: JSON.parse(
+            fs.readFileSync(path.join(contextsDir, contextFile), "utf-8")
+          ),
+          expected: JSON.parse(
+            fs.readFileSync(path.join(expectedDir, expectedFile), "utf-8")
+          ),
+        };
+
+        testCases.push(testCase);
+      }
+    } catch (error) {
+      console.warn(`⚠️  Error loading ${packId}: ${error.message}`);
+    }
+
+    return testCases;
+  }
+
+  async runTests(testCases) {
+    const results = [];
+
+    for (const testCase of testCases) {
+      console.log(`Running ${testCase.id}...`);
+
+      try {
+        const result = await this.runTestCase(testCase);
+        results.push(result);
+
+        if (result.passed) {
+          console.log(`  ✅ PASS`);
+        } else {
+          console.log(`  ❌ FAIL: ${result.errors.join(", ")}`);
+        }
+      } catch (error) {
+        console.log(`  ❌ ERROR: ${error.message}`);
+        results.push({
+          testCase,
+          passed: false,
+          errors: [error.message],
+          warnings: [],
+        });
+      }
+    }
+
+    return results;
+  }
+
+  async runTestCase(testCase) {
+    const errors = [];
+
+    // 1. Validate passport
+    const passportValidation = await this.validator.validatePassport(
+      testCase.passport
+    );
+    if (!passportValidation.valid) {
+      errors.push(
+        `Passport validation failed: ${passportValidation.errors.join(", ")}`
+      );
+    }
+
+    // 2. Validate context
+    const contextValidation = await this.validator.validateContext(
+      testCase.packId,
+      testCase.context
+    );
+    if (!contextValidation.valid) {
+      errors.push(
+        `Context validation failed: ${contextValidation.errors.join(", ")}`
+      );
+    }
+
+    // 3. Validate expected decision
+    const decisionValidation = await this.validator.validateDecision(
+      testCase.expected
+    );
+    if (!decisionValidation.valid) {
+      errors.push(
+        `Expected decision validation failed: ${decisionValidation.errors.join(
+          ", "
+        )}`
+      );
+    }
+
+    // 4. Basic policy evaluation (simplified)
+    const policyResult = await this.evaluatePolicy(testCase);
+    if (!policyResult.valid) {
+      errors.push(
+        `Policy evaluation failed: ${policyResult.errors.join(", ")}`
+      );
+    }
+
+    return {
+      testCase,
+      passed: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  }
+
+  async evaluatePolicy(testCase) {
+    // Simplified policy evaluation for testing
+    const { packId, passport, context } = testCase;
+
+    if (packId === "finance.payment.refund.v1") {
+      const amount = context.amount || 0;
+      const currency = context.currency || "USD";
+
+      const limits =
+        passport.limits?.["finance.payment.refund"]?.currency_limits?.[
+          currency
+        ];
+      if (limits && amount > limits.max_per_tx) {
+        return {
+          valid: false,
+          errors: [
+            `Amount ${amount} exceeds max per transaction ${limits.max_per_tx}`,
+          ],
+        };
+      }
+    }
+
+    if (packId === "data.export.create.v1") {
+      const includePii = context.include_pii || false;
+      const allowPii = passport.limits?.["data.export"]?.allow_pii || false;
+
+      if (includePii && !allowPii) {
+        return {
+          valid: false,
+          errors: ["PII export not allowed"],
+        };
+      }
+    }
+
+    return { valid: true, errors: [] };
+  }
+
+  displayResults(results) {
+    console.log("\n📊 Test Results\n");
+
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.filter((r) => !r.passed).length;
+    const total = results.length;
+
+    console.log(`✅ Passed: ${passed}`);
+    console.log(`❌ Failed: ${failed}`);
+    console.log(
+      `📈 Success Rate: ${total > 0 ? ((passed / total) * 100).toFixed(1) : 0}%`
+    );
+
+    if (failed > 0) {
+      console.log("\n❌ Failed Tests:");
+      results
+        .filter((r) => !r.passed)
+        .forEach((result) => {
+          console.log(`  • ${result.testCase.id}`);
+          result.errors.forEach((error) => {
+            console.log(`    - ${error}`);
+          });
+        });
+    }
+
+    console.log("\n🎯 Conformance testing complete!\n");
+  }
+}
+
+// Run the test
+const runner = new SimpleTestRunner();
+runner.run().catch(console.error);
+
+export { SimpleTestRunner };

package/external/aport-spec/conformance/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "reports"]
+}

package/external/aport-spec/error-schema.json

@@ -0,0 +1,192 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OAP Error Response Schema",
+  "description": "Standardized error response format for Open Agent Passport API",
+  "type": "object",
+  "required": ["error", "timestamp"],
+  "properties": {
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Machine-readable error code",
+          "enum": [
+            "validation_failed",
+            "unauthorized",
+            "forbidden",
+            "not_found",
+            "conflict",
+            "rate_limit_exceeded",
+            "internal_server_error",
+            "service_unavailable",
+            "invalid_passport",
+            "invalid_signature",
+            "timestamp_expired",
+            "nonce_reused",
+            "policy_denied",
+            "capability_insufficient",
+            "assurance_insufficient",
+            "limit_exceeded",
+            "region_restricted",
+            "passport_suspended",
+            "passport_revoked",
+            "idempotency_conflict",
+            "invalid_policy",
+            "passport_not_found",
+            "decision_expired",
+            "signature_verification_failed",
+            "transport_error"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable error message"
+        },
+        "details": {
+          "type": "object",
+          "description": "Additional error details",
+          "additionalProperties": true
+        },
+        "field": {
+          "type": "string",
+          "description": "Field that caused the validation error"
+        },
+        "value": {
+          "description": "Value that caused the validation error"
+        },
+        "suggestion": {
+          "type": "string",
+          "description": "Suggested fix for the error"
+        }
+      }
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the error occurred"
+    },
+    "request_id": {
+      "type": "string",
+      "description": "Unique identifier for the request that caused the error"
+    },
+    "path": {
+      "type": "string",
+      "description": "API path that caused the error"
+    },
+    "method": {
+      "type": "string",
+      "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+      "description": "HTTP method that caused the error"
+    },
+    "status_code": {
+      "type": "integer",
+      "minimum": 400,
+      "maximum": 599,
+      "description": "HTTP status code"
+    },
+    "retry_after": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Seconds to wait before retrying (for rate limit errors)"
+    },
+    "rate_limit_info": {
+      "type": "object",
+      "description": "Rate limiting information (for rate limit errors)",
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "description": "Rate limit threshold"
+        },
+        "remaining": {
+          "type": "integer",
+          "description": "Remaining requests in current window"
+        },
+        "reset": {
+          "type": "integer",
+          "description": "Unix timestamp when rate limit resets"
+        },
+        "window": {
+          "type": "integer",
+          "description": "Rate limit window duration in seconds"
+        }
+      }
+    },
+    "documentation_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to relevant documentation"
+    },
+    "support_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to support or help"
+    }
+  },
+  "examples": [
+    {
+      "error": {
+        "code": "validation_failed",
+        "message": "Name is required and must be between 1-100 characters",
+        "field": "name",
+        "value": "",
+        "suggestion": "Provide a valid agent name between 1 and 100 characters"
+      },
+      "timestamp": "2025-01-16T10:30:00Z",
+      "request_id": "req_123456789",
+      "path": "/api/passports",
+      "method": "POST",
+      "status_code": 400
+    },
+    {
+      "error": {
+        "code": "rate_limit_exceeded",
+        "message": "Too many requests, please try again later"
+      },
+      "timestamp": "2025-01-16T10:30:00Z",
+      "request_id": "req_123456790",
+      "path": "/api/verify/ap_a2d10232c6534523812423eec8a1425c",
+      "method": "GET",
+      "status_code": 429,
+      "retry_after": 3600,
+      "rate_limit_info": {
+        "limit": 1000,
+        "remaining": 0,
+        "reset": 1640998800,
+        "window": 3600
+      }
+    },
+    {
+      "error": {
+        "code": "passport_not_found",
+        "message": "Passport with ID ap_a2d10232c6534523812423eec8a1425c not found",
+        "details": {
+          "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
+          "suggestion": "Verify the passport ID is correct and the passport exists"
+        }
+      },
+      "timestamp": "2025-01-16T10:30:00Z",
+      "request_id": "req_123456791",
+      "path": "/api/verify/ap_a2d10232c6534523812423eec8a1425c",
+      "method": "GET",
+      "status_code": 404
+    },
+    {
+      "error": {
+        "code": "policy_denied",
+        "message": "Agent lacks required capabilities for this policy",
+        "details": {
+          "policy_id": "finance.payment.refund.v1",
+          "required_capabilities": ["finance.payment.refund"],
+          "agent_capabilities": ["data.export"]
+        }
+      },
+      "timestamp": "2025-01-16T10:30:00Z",
+      "request_id": "req_123456792",
+      "path": "/api/verify/policy/finance.payment.refund.v1",
+      "method": "POST",
+      "status_code": 403
+    }
+  ]
+}

package/external/aport-spec/index.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.1.0",
+  "published_at": "2025-09-24T23:03:21Z",
+  "source_commit": "07d00d6d3e6a94367b40192a7841a27074c7bf6f",
+  "specifications": [
+    {"name": "passport-schema", "path": "passport-schema.json", "description": "APort passport schema definition"},
+    {"name": "error-schema", "path": "error-schema.json", "description": "APort error schema definition"},
+    {"name": "rate-limiting", "path": "rate-limiting.md", "description": "Rate limiting specification"},
+    {"name": "transport-profile", "path": "transport-profile.md", "description": "Transport profile specification"},
+    {"name": "webhook-spec", "path": "webhook-spec.md", "description": "Webhook specification"}
+  ]
+}

package/external/aport-spec/integrations/clawmoat/README.md

@@ -0,0 +1,12 @@
+# ClawMoat Integration (Placeholder)
+
+_Last updated: 2026-02-17_
+
+ClawMoat is an open-source detection layer for AI agents (prompt injection, data exfiltration, secret leakage). In the layered model from OpenClaw issue #12385, ClawMoat supplies detections while OAP/APort performs authorization.
+
+**Open Agent Passport (OAP) v1.0** ([spec](../../oap/oap-spec.md)) provides the runtime authorization layer SHIELD v1 envisions:
+- Passports (W3C VC/DID-aligned) describe agent capabilities and limits.
+- Policy packs define evaluation rules; **limits** (e.g. allowlists, blocked patterns, threat data) live in the **passport** under `limits.{capability}`.
+- APort guardrails evaluate policy packs against passport + context and enforce deterministically (e.g. `before_tool_call` in OpenClaw).
+
+This folder will hold the detector schema + adapter notes once we formalize the shared findings format. For now, the priority is shipping the SHIELD→OAP mapping; ClawMoat integration will follow the same `{threat_id, module, severity, confidence}` structure when we’re ready to onboard additional feeds.