@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/conformance/src/cases.ts

@@ -0,0 +1,371 @@
+/**
+ * Test case definitions and types for OAP conformance testing
+ */
+
+export interface TestCase {
+  id: string;
+  packId: string;
+  contextName: string;
+  passport: any;
+  context: any;
+  expected: any;
+  receipt?: any;
+}
+
+export interface TestResult {
+  testCase: TestCase;
+  passed: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface ConformanceReport {
+  timestamp: string;
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+  };
+  details: Array<{
+    testCase: string;
+    passed: boolean;
+    errors: string[];
+    warnings: string[];
+  }>;
+}
+
+export interface PolicyPackTestCase {
+  packId: string;
+  name: string;
+  description: string;
+  passports: any[];
+  contexts: any[];
+  expected: any[];
+  receipts?: any[];
+}
+
+export interface SignatureVerificationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface PolicyEvaluationResult {
+  valid: boolean;
+  decision: any;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Standard test cases for OAP conformance
+ */
+export const STANDARD_TEST_CASES: PolicyPackTestCase[] = [
+  {
+    packId: "finance.payment.refund.v1",
+    name: "Refunds Policy Pack",
+    description: "Tests for finance.payment.refund.v1 policy pack",
+    passports: [],
+    contexts: [],
+    expected: [],
+    receipts: [],
+  },
+  {
+    packId: "data.export.create.v1",
+    name: "Data Export Policy Pack",
+    description: "Tests for data.export.create.v1 policy pack",
+    passports: [],
+    contexts: [],
+    expected: [],
+    receipts: [],
+  },
+  {
+    packId: "repo.release.publish.v1",
+    name: "Repository Release Policy Pack",
+    description: "Tests for repo.release.publish.v1 policy pack",
+    passports: [],
+    contexts: [],
+    expected: [],
+    receipts: [],
+  },
+];
+
+/**
+ * Error codes for OAP conformance testing
+ */
+export const OAP_ERROR_CODES = {
+  INVALID_CONTEXT: "oap.invalid_context",
+  UNKNOWN_CAPABILITY: "oap.unknown_capability",
+  LIMIT_EXCEEDED: "oap.limit_exceeded",
+  CURRENCY_UNSUPPORTED: "oap.currency_unsupported",
+  REGION_BLOCKED: "oap.region_blocked",
+  ASSURANCE_INSUFFICIENT: "oap.assurance_insufficient",
+  PASSPORT_SUSPENDED: "oap.passport_suspended",
+  IDEMPOTENCY_CONFLICT: "oap.idempotency_conflict",
+  POLICY_ERROR: "oap.policy_error",
+  PII_BLOCKED: "oap.pii_blocked",
+  COLLECTION_FORBIDDEN: "oap.collection_forbidden",
+  BRANCH_FORBIDDEN: "oap.branch_forbidden",
+  REPO_FORBIDDEN: "oap.repo_forbidden",
+  UNSIGNED_ARTIFACT: "oap.unsigned_artifact",
+} as const;
+
+/**
+ * Assurance levels for OAP conformance testing
+ */
+export const ASSURANCE_LEVELS = {
+  L0: "L0",
+  L1: "L1",
+  L2: "L2",
+  L3: "L3",
+  L4KYC: "L4KYC",
+  L4FIN: "L4FIN",
+} as const;
+
+/**
+ * Policy pack requirements for conformance testing
+ */
+export const POLICY_PACK_REQUIREMENTS = {
+  "finance.payment.refund.v1": {
+    requiredCapabilities: ["finance.payment.refund"],
+    minAssurance: "L2",
+    requiredContextFields: ["amount", "currency", "order_id"],
+    optionalContextFields: [
+      "customer_id",
+      "reason_code",
+      "region",
+      "idempotency_key",
+    ],
+  },
+  "data.export.create.v1": {
+    requiredCapabilities: ["data.export"],
+    minAssurance: "L1",
+    requiredContextFields: ["collection"],
+    optionalContextFields: ["estimated_rows", "include_pii", "region"],
+  },
+  "repo.release.publish.v1": {
+    requiredCapabilities: ["repo.release.publish"],
+    minAssurance: "L2",
+    requiredContextFields: ["repo", "branch", "tag"],
+    optionalContextFields: ["artifact_sha", "signer"],
+  },
+} as const;
+
+/**
+ * Test case validation utilities
+ */
+export class TestCaseValidator {
+  /**
+   * Validate a test case structure
+   */
+  static validateTestCase(testCase: TestCase): {
+    valid: boolean;
+    errors: string[];
+  } {
+    const errors: string[] = [];
+
+    if (!testCase.id) {
+      errors.push("Test case ID is required");
+    }
+
+    if (!testCase.packId) {
+      errors.push("Policy pack ID is required");
+    }
+
+    if (!testCase.passport) {
+      errors.push("Passport is required");
+    }
+
+    if (!testCase.context) {
+      errors.push("Context is required");
+    }
+
+    if (!testCase.expected) {
+      errors.push("Expected result is required");
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Validate a policy pack test case
+   */
+  static validatePolicyPackTestCase(testCase: PolicyPackTestCase): {
+    valid: boolean;
+    errors: string[];
+  } {
+    const errors: string[] = [];
+
+    if (!testCase.packId) {
+      errors.push("Policy pack ID is required");
+    }
+
+    if (!testCase.name) {
+      errors.push("Test case name is required");
+    }
+
+    if (!Array.isArray(testCase.passports)) {
+      errors.push("Passports must be an array");
+    }
+
+    if (!Array.isArray(testCase.contexts)) {
+      errors.push("Contexts must be an array");
+    }
+
+    if (!Array.isArray(testCase.expected)) {
+      errors.push("Expected results must be an array");
+    }
+
+    if (testCase.passports.length !== testCase.contexts.length) {
+      errors.push("Number of passports must match number of contexts");
+    }
+
+    if (testCase.contexts.length !== testCase.expected.length) {
+      errors.push("Number of contexts must match number of expected results");
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}
+
+/**
+ * Test case generators for common scenarios
+ */
+export class TestCaseGenerator {
+  /**
+   * Generate a basic refund test case
+   */
+  static generateRefundTestCase(
+    amount: number,
+    currency: string,
+    shouldPass: boolean
+  ): TestCase {
+    return {
+      id: `finance.payment.refund.v1:${amount}${currency}_${
+        shouldPass ? "allow" : "deny"
+      }`,
+      packId: "finance.payment.refund.v1",
+      contextName: `${amount}${currency}_${shouldPass ? "allow" : "deny"}`,
+      passport: {
+        passport_id: "550e8400-e29b-41d4-a716-446655440000",
+        kind: "template",
+        spec_version: "oap/1.0",
+        owner_id: "org_12345678",
+        owner_type: "org",
+        assurance_level: "L2",
+        status: "active",
+        capabilities: [{ id: "finance.payment.refund" }],
+        limits: {
+          "finance.payment.refund": {
+            currency_limits: {
+              [currency]: {
+                max_per_tx: shouldPass ? amount * 2 : amount / 2,
+                daily_cap: amount * 10,
+              },
+            },
+          },
+        },
+        regions: ["US"],
+        created_at: "2024-01-01T00:00:00Z",
+        updated_at: "2024-01-15T10:30:00Z",
+        version: "1.0.0",
+      },
+      context: {
+        amount,
+        currency,
+        order_id: `order_${Date.now()}`,
+        customer_id: "cust_123",
+        reason_code: "customer_request",
+        region: "US",
+      },
+      expected: {
+        decision_id: "test_decision_id",
+        policy_id: "finance.payment.refund.v1",
+        agent_id: "550e8400-e29b-41d4-a716-446655440000",
+        owner_id: "org_12345678",
+        assurance_level: "L2",
+        allow: shouldPass,
+        reasons: shouldPass
+          ? [{ code: "oap.allowed", message: "Transaction within limits" }]
+          : [{ code: "oap.limit_exceeded", message: "Amount exceeds limit" }],
+        created_at: "2024-01-15T10:30:00Z",
+        expires_in: 3600,
+        passport_digest: "sha256:test_digest",
+        signature: "ed25519:test_signature",
+        kid: "oap:registry:test-key",
+      },
+    };
+  }
+
+  /**
+   * Generate a data export test case
+   */
+  static generateDataExportTestCase(
+    collection: string,
+    estimatedRows: number,
+    includePii: boolean,
+    shouldPass: boolean
+  ): TestCase {
+    return {
+      id: `data.export.create.v1:${collection}_${estimatedRows}_${
+        includePii ? "pii" : "no_pii"
+      }_${shouldPass ? "allow" : "deny"}`,
+      packId: "data.export.create.v1",
+      contextName: `${collection}_${estimatedRows}_${
+        includePii ? "pii" : "no_pii"
+      }_${shouldPass ? "allow" : "deny"}`,
+      passport: {
+        passport_id: "550e8400-e29b-41d4-a716-446655440001",
+        kind: "template",
+        spec_version: "oap/1.0",
+        owner_id: "org_12345678",
+        owner_type: "org",
+        assurance_level: "L1",
+        status: "active",
+        capabilities: [{ id: "data.export" }],
+        limits: {
+          "data.export": {
+            max_rows: shouldPass ? estimatedRows * 2 : estimatedRows / 2,
+            allow_pii: includePii,
+            allowed_collections: shouldPass
+              ? [collection]
+              : ["other_collection"],
+          },
+        },
+        regions: ["US"],
+        created_at: "2024-01-01T00:00:00Z",
+        updated_at: "2024-01-15T10:30:00Z",
+        version: "1.0.0",
+      },
+      context: {
+        collection,
+        estimated_rows: estimatedRows,
+        include_pii: includePii,
+        region: "US",
+      },
+      expected: {
+        decision_id: "test_decision_id",
+        policy_id: "data.export.create.v1",
+        agent_id: "550e8400-e29b-41d4-a716-446655440001",
+        owner_id: "org_12345678",
+        assurance_level: "L1",
+        allow: shouldPass,
+        reasons: shouldPass
+          ? [{ code: "oap.allowed", message: "Export within limits" }]
+          : [{ code: "oap.limit_exceeded", message: "Row limit exceeded" }],
+        created_at: "2024-01-15T10:30:00Z",
+        expires_in: 3600,
+        passport_digest: "sha256:test_digest",
+        signature: "ed25519:test_signature",
+        kid: "oap:registry:test-key",
+      },
+    };
+  }
+}

package/external/aport-spec/conformance/src/ed25519.ts

@@ -0,0 +1,167 @@
+/**
+ * Ed25519 signature verification for OAP conformance testing
+ *
+ * Note: This is a simplified implementation for conformance testing.
+ * In production, use a proper Ed25519 library like @noble/ed25519
+ */
+
+export class Ed25519 {
+  /**
+   * Verify an Ed25519 signature
+   *
+   * @param message - The message that was signed
+   * @param signature - The signature in base64 format
+   * @param publicKey - The public key in base64 format
+   * @returns Promise<boolean> - True if signature is valid
+   */
+  async verify(
+    message: Uint8Array,
+    signature: string,
+    publicKey: string
+  ): Promise<boolean> {
+    try {
+      // For conformance testing, we'll implement a simplified verification
+      // In production, this would use a proper Ed25519 library
+
+      // Remove the 'ed25519:' prefix if present
+      const cleanSignature = signature.replace(/^ed25519:/, "");
+      const cleanPublicKey = publicKey.replace(/^ed25519:/, "");
+
+      // Basic format validation
+      if (
+        !this.isValidBase64(cleanSignature) ||
+        !this.isValidBase64(cleanPublicKey)
+      ) {
+        return false;
+      }
+
+      // For conformance testing, we'll accept any properly formatted signature
+      // In production, this would perform actual cryptographic verification
+      return cleanSignature.length === 88 && cleanPublicKey.length === 44; // Expected lengths for base64 encoded Ed25519
+    } catch (error) {
+      console.warn("Ed25519 verification failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Verify a decision signature
+   *
+   * @param decision - The decision object
+   * @param signature - The signature string
+   * @param publicKey - The public key
+   * @returns Promise<boolean> - True if signature is valid
+   */
+  async verifyDecisionSignature(
+    decision: any,
+    signature: string,
+    publicKey: string
+  ): Promise<boolean> {
+    try {
+      // Create the message that was signed (JCS canonicalized decision)
+      const jcs = new (await import("./jcs.js")).JCS();
+      const canonical = jcs.canonicalize(decision);
+      const message = new TextEncoder().encode(canonical);
+
+      return await this.verify(message, signature, publicKey);
+    } catch (error) {
+      console.warn("Decision signature verification failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Verify a passport digest signature
+   *
+   * @param passport - The passport object
+   * @param digest - The passport digest
+   * @returns Promise<boolean> - True if digest is valid
+   */
+  async verifyPassportDigest(passport: any, digest: string): Promise<boolean> {
+    try {
+      const jcs = new (await import("./jcs.js")).JCS();
+      const computedDigest = await jcs.computePassportDigest(passport);
+      return computedDigest === digest;
+    } catch (error) {
+      console.warn("Passport digest verification failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Generate a test key pair for conformance testing
+   *
+   * @returns Promise<{publicKey: string, privateKey: string}>
+   */
+  async generateTestKeyPair(): Promise<{
+    publicKey: string;
+    privateKey: string;
+  }> {
+    // For conformance testing, generate deterministic test keys
+    // In production, use proper key generation
+    const publicKey = "ed25519:" + "A".repeat(44); // 44 chars for base64 encoded 32-byte key
+    const privateKey = "ed25519:" + "B".repeat(44);
+
+    return { publicKey, privateKey };
+  }
+
+  /**
+   * Sign a message with a private key (for testing)
+   *
+   * @param message - The message to sign
+   * @param privateKey - The private key
+   * @returns Promise<string> - The signature
+   */
+  async sign(message: Uint8Array, privateKey: string): Promise<string> {
+    // For conformance testing, generate a deterministic signature
+    // In production, use proper Ed25519 signing
+    const messageStr = new TextDecoder().decode(message);
+    const hash = await crypto.subtle.digest("SHA-256", new Uint8Array(message));
+    const hashArray = Array.from(new Uint8Array(hash));
+    const hashHex = hashArray
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+    return "ed25519:" + hashHex.substring(0, 88); // 88 chars for base64 encoded 64-byte signature
+  }
+
+  /**
+   * Check if a string is valid base64
+   */
+  private isValidBase64(str: string): boolean {
+    try {
+      return btoa(atob(str)) === str;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Resolve a key ID to a public key
+   *
+   * @param kid - The key identifier
+   * @returns Promise<string | null> - The public key or null if not found
+   */
+  async resolveKey(kid: string): Promise<string | null> {
+    try {
+      // For conformance testing, we'll use test keys
+      // In production, this would resolve keys from /.well-known/oap/keys.json
+
+      if (kid.startsWith("oap:registry:test-key")) {
+        const { publicKey } = await this.generateTestKeyPair();
+        return publicKey;
+      }
+
+      if (kid.startsWith("oap:owner:")) {
+        // For owner keys, we'd fetch from the owner's domain
+        // For conformance testing, return a test key
+        const { publicKey } = await this.generateTestKeyPair();
+        return publicKey;
+      }
+
+      return null;
+    } catch (error) {
+      console.warn("Key resolution failed:", error);
+      return null;
+    }
+  }
+}

package/external/aport-spec/conformance/src/jcs.ts

@@ -0,0 +1,85 @@
+/**
+ * JSON Canonicalization Scheme (JCS) implementation
+ *
+ * Implements RFC 8785 for deterministic JSON serialization
+ */
+
+export class JCS {
+  /**
+   * Canonicalize a JSON object according to RFC 8785
+   */
+  canonicalize(obj: any): string {
+    return this.canonicalizeValue(obj);
+  }
+
+  private canonicalizeValue(value: any): string {
+    if (value === null) {
+      return "null";
+    }
+
+    if (typeof value === "boolean") {
+      return value ? "true" : "false";
+    }
+
+    if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        return value.toString();
+      }
+      return value.toString();
+    }
+
+    if (typeof value === "string") {
+      return JSON.stringify(value);
+    }
+
+    if (Array.isArray(value)) {
+      return this.canonicalizeArray(value);
+    }
+
+    if (typeof value === "object") {
+      return this.canonicalizeObject(value);
+    }
+
+    throw new Error(`Unsupported value type: ${typeof value}`);
+  }
+
+  private canonicalizeArray(arr: any[]): string {
+    const elements = arr.map((item) => this.canonicalizeValue(item));
+    return "[" + elements.join(",") + "]";
+  }
+
+  private canonicalizeObject(obj: any): string {
+    // Get all keys and sort them
+    const keys = Object.keys(obj).sort();
+
+    const pairs = keys.map((key) => {
+      const value = this.canonicalizeValue(obj[key]);
+      return JSON.stringify(key) + ":" + value;
+    });
+
+    return "{" + pairs.join(",") + "}";
+  }
+
+  /**
+   * Compute SHA-256 hash of canonicalized JSON
+   */
+  async computeHash(obj: any): Promise<string> {
+    const canonical = this.canonicalize(obj);
+    const encoder = new TextEncoder();
+    const data = encoder.encode(canonical);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+    return hashHex;
+  }
+
+  /**
+   * Compute passport digest as specified in OAP
+   */
+  async computePassportDigest(passport: any): Promise<string> {
+    const hash = await this.computeHash(passport);
+    return `sha256:${hash}`;
+  }
+}