@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/oap/vc/tools/test-simple.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+/**
+ * Simple test of OAP VC conversion tools
+ */
+
+// Mock the conversion functions for demonstration
+function exportPassportToVC(passport, registryKey) {
+  return {
+    "@context": [
+      "https://www.w3.org/2018/credentials/v1",
+      "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld",
+    ],
+    type: ["VerifiableCredential", "OAPPassportCredential"],
+    credentialSubject: passport,
+    issuer: registryKey.issuer,
+    issuanceDate: passport.created_at,
+    expirationDate: new Date(
+      new Date(passport.created_at).getTime() + 365 * 24 * 60 * 60 * 1000
+    ).toISOString(),
+    proof: {
+      type: "Ed25519Signature2020",
+      created: passport.created_at,
+      verificationMethod: `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      proofPurpose: "assertionMethod",
+      jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+    },
+  };
+}
+
+function exportDecisionToVC(decision, registryKey) {
+  return {
+    "@context": [
+      "https://www.w3.org/2018/credentials/v1",
+      "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld",
+    ],
+    type: ["VerifiableCredential", "OAPDecisionReceipt"],
+    credentialSubject: decision,
+    issuer: registryKey.issuer,
+    issuanceDate: decision.created_at,
+    expirationDate: new Date(
+      new Date(decision.created_at).getTime() + decision.expires_in * 1000
+    ).toISOString(),
+    proof: {
+      type: "Ed25519Signature2020",
+      created: decision.created_at,
+      verificationMethod: `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      proofPurpose: "assertionMethod",
+      jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+    },
+  };
+}
+
+function importVCToPassport(vc) {
+  return vc.credentialSubject;
+}
+
+function importVCToDecision(vc) {
+  return vc.credentialSubject;
+}
+
+// Test data
+const samplePassport = {
+  agent_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",
+      params: { currency_limits: { USD: { max_per_tx: 5000 } } },
+    },
+  ],
+  limits: {
+    "finance.payment.refund": {
+      currency_limits: { USD: { max_per_tx: 5000, daily_cap: 50000 } },
+      reason_codes: ["customer_request"],
+      idempotency_required: true,
+    },
+  },
+  regions: ["US", "CA"],
+  metadata: { name: "Customer Support AI" },
+  created_at: "2024-01-01T00:00:00Z",
+  updated_at: "2024-01-15T10:30:00Z",
+  version: "1.0.0",
+};
+
+const sampleDecision = {
+  decision_id: "550e8400-e29b-41d4-a716-446655440002",
+  policy_id: "finance.payment.refund.v1",
+  agent_id: "550e8400-e29b-41d4-a716-446655440000",
+  owner_id: "org_12345678",
+  assurance_level: "L2",
+  allow: true,
+  reasons: [{ code: "oap.allowed", message: "Transaction within limits" }],
+  created_at: "2024-01-15T10:30:00Z",
+  expires_in: 3600,
+  passport_digest:
+    "sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef",
+  signature: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+  kid: "oap:registry:key-2025-01",
+};
+
+const registryKey = {
+  issuer: "https://aport.io",
+  kid: "key-2025-01",
+};
+
+// Run tests
+console.log("🧪 Testing OAP VC Conversion Tools\n");
+
+try {
+  // Test 1: Passport → VC
+  console.log("1. Converting Passport → VC...");
+  const passportVC = exportPassportToVC(samplePassport, registryKey);
+  console.log("   ✅ Success");
+  console.log(`   📄 Type: ${passportVC.type.join(", ")}`);
+  console.log(`   🏢 Issuer: ${passportVC.issuer}`);
+  console.log(`   📅 Issuance: ${passportVC.issuanceDate}`);
+  console.log(`   ⏰ Expiration: ${passportVC.expirationDate}`);
+  console.log("   📄 Sample VC Data:");
+  console.log(
+    "   " +
+      JSON.stringify(passportVC, null, 2)
+        .split("\n")
+        .slice(0, 10)
+        .join("\n   ") +
+      "\n   ...\n"
+  );
+
+  // Test 2: Decision → VC
+  console.log("2. Converting Decision → VC...");
+  const decisionVC = exportDecisionToVC(sampleDecision, registryKey);
+  console.log("   ✅ Success");
+  console.log(`   📄 Type: ${decisionVC.type.join(", ")}`);
+  console.log(`   🏢 Issuer: ${decisionVC.issuer}`);
+  console.log(`   📅 Issuance: ${decisionVC.issuanceDate}`);
+  console.log(`   ⏰ Expiration: ${decisionVC.expirationDate}`);
+  console.log("   📄 Sample VC Data:");
+  console.log(
+    "   " +
+      JSON.stringify(decisionVC, null, 2)
+        .split("\n")
+        .slice(0, 10)
+        .join("\n   ") +
+      "\n   ...\n"
+  );
+
+  // Test 3: VC → Passport
+  console.log("3. Converting VC → Passport...");
+  const importedPassport = importVCToPassport(passportVC);
+  console.log("   ✅ Success");
+  console.log(`   🆔 Agent ID: ${importedPassport.agent_id}`);
+  console.log(`   📋 Kind: ${importedPassport.kind}`);
+  console.log(`   🔐 Assurance: ${importedPassport.assurance_level}`);
+  console.log("   📄 Sample Passport Data:");
+  console.log(
+    "   " +
+      JSON.stringify(importedPassport, null, 2)
+        .split("\n")
+        .slice(0, 8)
+        .join("\n   ") +
+      "\n   ...\n"
+  );
+
+  // Test 4: VC → Decision
+  console.log("4. Converting VC → Decision...");
+  const importedDecision = importVCToDecision(decisionVC);
+  console.log("   ✅ Success");
+  console.log(`   🆔 Decision ID: ${importedDecision.decision_id}`);
+  console.log(`   📋 Policy ID: ${importedDecision.policy_id}`);
+  console.log(`   ✅ Allow: ${importedDecision.allow}`);
+  console.log("   📄 Sample Decision Data:");
+  console.log(
+    "   " +
+      JSON.stringify(importedDecision, null, 2)
+        .split("\n")
+        .slice(0, 8)
+        .join("\n   ") +
+      "\n   ...\n"
+  );
+
+  // Test 5: Round-trip
+  console.log("5. Testing round-trip conversion...");
+  const roundTripPassport = importVCToPassport(
+    exportPassportToVC(samplePassport, registryKey)
+  );
+  const isEqual =
+    JSON.stringify(samplePassport) === JSON.stringify(roundTripPassport);
+  console.log(
+    `   ${isEqual ? "✅" : "❌"} Round-trip ${
+      isEqual ? "preserved" : "modified"
+    } data\n`
+  );
+
+  console.log(
+    "🎉 All tests passed! OAP VC conversion tools are working correctly."
+  );
+  console.log("\n📚 Next steps:");
+  console.log("   • Install dependencies: npm install");
+  console.log("   • Build TypeScript: npm run build");
+  console.log(
+    "   • Use CLI: npx oap-vc export --type passport --input passport.json --output passport.vc.json --key registry-key.json"
+  );
+  console.log(
+    '   • Use SDK: import { exportPassportToVC } from "@oap/vc-tools"'
+  );
+} catch (error) {
+  console.error("❌ Test failed:", error.message);
+  process.exit(1);
+}

package/external/aport-spec/oap/vc/tools/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/external/aport-spec/oap/vc/vc-mapping.md

@@ -0,0 +1,443 @@
+# Open Agent Passport Verifiable Credential Mapping
+
+## Overview
+
+This document defines how Open Agent Passport (OAP) objects can be exported and imported as W3C Verifiable Credentials (VCs) for interoperability with existing VC ecosystems.
+
+## Design Principles
+
+- **Optional VC Support**: VCs are optional for OAP v1 - native OAP JSON remains the source of truth
+- **Deterministic Mapping**: Export/import mappings are deterministic and reversible
+- **Minimal VC Dependencies**: Avoid forcing VC adoption in OAP v1 implementations
+- **Future Compatibility**: Design for future VC integration without breaking changes
+
+## Passport to VC Mapping
+
+### OAP Passport Credential
+
+An OAP passport can be exported as a Verifiable Credential with the following structure:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld"
+  ],
+  "type": ["VerifiableCredential", "OAPPassportCredential"],
+  "credentialSubject": {
+    "agent_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": ["finance.payment.refund", "data.export"],
+    "limits": {
+      "finance.payment.refund": {
+        "currency_limits": {
+          "USD": {
+            "max_per_tx": 5000,
+            "daily_cap": 50000
+          }
+        },
+        "reason_codes": ["customer_request", "defective_product"],
+        "idempotency_required": true
+      }
+    },
+    "regions": ["US", "CA"],
+    "metadata": {
+      "name": "Customer Support AI",
+      "description": "AI agent for customer support operations"
+    },
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-15T10:30:00Z",
+    "version": "1.0.0"
+  },
+  "issuer": "https://aport.io",
+  "issuanceDate": "2024-01-01T00:00:00Z",
+  "expirationDate": "2025-01-01T00:00:00Z",
+  "proof": {
+    "type": "Ed25519Signature2020",
+    "created": "2024-01-01T00:00:00Z",
+    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#key-2025-01",
+    "proofPurpose": "assertionMethod",
+    "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+### Mapping Rules
+
+1. **Context**: Include OAP context and W3C VC context
+2. **Type**: Use `["VerifiableCredential", "OAPPassportCredential"]`
+3. **Credential Subject**: Map all OAP passport fields directly
+4. **Issuer**: Use registry URL or owner domain
+5. **Dates**: Map `created_at` to `issuanceDate`, set `expirationDate` based on policy
+6. **Proof**: Use Ed25519Signature2020 over JCS-canonicalized credential subject
+
+## Decision to VC Mapping
+
+### OAP Decision Receipt
+
+An OAP decision can be exported as a Verifiable Credential receipt:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld"
+  ],
+  "type": ["VerifiableCredential", "OAPDecisionReceipt"],
+  "credentialSubject": {
+    "decision_id": "550e8400-e29b-41d4-a716-446655440002",
+    "policy_id": "finance.payment.refund.v1",
+    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
+    "owner_id": "org_12345678",
+    "assurance_level": "L2",
+    "allow": true,
+    "reasons": [
+      {
+        "code": "oap.allowed",
+        "message": "Transaction within limits"
+      }
+    ],
+    "created_at": "2024-01-15T10:30:00Z",
+    "expires_in": 3600,
+    "passport_digest": "sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef"
+  },
+  "issuer": "https://aport.io",
+  "issuanceDate": "2024-01-15T10:30:00Z",
+  "expirationDate": "2024-01-15T11:30:00Z",
+  "proof": {
+    "type": "Ed25519Signature2020",
+    "created": "2024-01-15T10:30:00Z",
+    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#key-2025-01",
+    "proofPurpose": "assertionMethod",
+    "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+### Decision Mapping Rules
+
+1. **Context**: Include OAP context and W3C VC context
+2. **Type**: Use `["VerifiableCredential", "OAPDecisionReceipt"]`
+3. **Credential Subject**: Map all OAP decision fields directly
+4. **Issuer**: Use registry URL
+5. **Dates**: Map `created_at` to `issuanceDate`, compute `expirationDate` from `expires_in`
+6. **Proof**: Use Ed25519Signature2020 over JCS-canonicalized credential subject
+
+## Import/Export Rules
+
+### Export Rules
+
+#### Requirements
+
+1. **Deterministic**: Same OAP object always produces same VC
+2. **Complete**: All OAP fields are included in VC
+3. **Valid**: Generated VCs are valid according to VC specification
+4. **Signed**: VCs include proper Ed25519 signatures
+5. **Context**: Include proper JSON-LD context
+
+### Import Rules
+
+#### Import Requirements
+
+1. **Advisory Only**: VC import is advisory, not authoritative
+2. **Validation**: Validate VC structure and signatures
+3. **Mapping**: Map VC fields back to OAP format
+4. **Source of Truth**: Native OAP JSON remains authoritative
+5. **Error Handling**: Handle invalid or malformed VCs gracefully
+
+### Implementation Example
+
+#### Code
+
+```javascript
+// Export OAP passport to VC
+function exportPassportToVC(passport, registryKey) {
+  const vc = {
+    "@context": [
+      "https://www.w3.org/2018/credentials/v1",
+      "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld"
+    ],
+    "type": ["VerifiableCredential", "OAPPassportCredential"],
+    "credentialSubject": passport,
+    "issuer": "https://aport.io",
+    "issuanceDate": passport.created_at,
+    "expirationDate": computeExpirationDate(passport),
+    "proof": {
+      "type": "Ed25519Signature2020",
+      "created": passport.created_at,
+      "verificationMethod": `${registryKey.issuer}#${registryKey.kid}`,
+      "proofPurpose": "assertionMethod",
+      "jws": signCredential(passport, registryKey)
+    }
+  };
+  return vc;
+}
+
+// Import VC to OAP passport
+function importVCToPassport(vc) {
+  // Validate VC structure
+  if (!isValidVC(vc)) {
+    throw new Error("Invalid VC structure");
+  }
+  
+  // Verify signature
+  if (!verifyCredentialSignature(vc)) {
+    throw new Error("Invalid VC signature");
+  }
+  
+  // Extract passport from credential subject
+  const passport = vc.credentialSubject;
+  
+  // Validate OAP passport structure
+  if (!isValidOAPPassport(passport)) {
+    throw new Error("Invalid OAP passport structure");
+  }
+  
+  return passport;
+}
+```
+
+## Interoperability Considerations
+
+### VC Ecosystem Integration
+
+- **Wallet Support**: OAP VCs can be stored in standard VC wallets
+- **Presentation**: OAP VCs can be presented using standard VC presentation protocols
+- **Verification**: OAP VCs can be verified using standard VC verification libraries
+- **Storage**: OAP VCs can be stored in standard VC repositories
+
+### OAP Ecosystem Integration
+
+- **Native Support**: OAP implementations work with native JSON format
+- **VC Optional**: VC support is optional for OAP compliance
+- **Performance**: Native OAP format is optimized for performance
+- **Simplicity**: Native OAP format is simpler for basic use cases
+
+## Future Considerations
+
+### VC v2.0 Support
+
+Future versions may include:
+
+- **BBS+ Signatures**: Support for selective disclosure
+- **ZKP Integration**: Zero-knowledge proof support
+- **Multi-Signature**: Support for multiple signers
+- **Revocation**: Standard VC revocation mechanisms
+
+### OAP v2.0 Integration
+
+Future OAP versions may:
+
+- **Native VC Support**: Make VCs a first-class citizen
+- **DID Integration**: Support for Decentralized Identifiers
+- **Credential Exchange**: Standard credential exchange protocols
+- **Privacy Enhancements**: Enhanced privacy and selective disclosure
+
+## Implementation Guide
+
+### Export OAP Passport to VC
+
+```javascript
+function exportPassportToVC(passport, registryKey) {
+  // Validate passport structure
+  if (!isValidOAPPassport(passport)) {
+    throw new Error("Invalid OAP passport structure");
+  }
+
+  // Create VC structure
+  const vc = {
+    "@context": [
+      "https://www.w3.org/2018/credentials/v1",
+      "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld"
+    ],
+    "type": ["VerifiableCredential", "OAPPassportCredential"],
+    "credentialSubject": {
+      // Map all OAP passport fields
+      "agent_id": passport.agent_id,
+      "kind": passport.kind,
+      "spec_version": passport.spec_version,
+      "parent_agent_id": passport.parent_agent_id,
+      "owner_id": passport.owner_id,
+      "owner_type": passport.owner_type,
+      "assurance_level": passport.assurance_level,
+      "status": passport.status,
+      "capabilities": passport.capabilities,
+      "limits": passport.limits,
+      "regions": passport.regions,
+      "metadata": passport.metadata,
+      "created_at": passport.created_at,
+      "updated_at": passport.updated_at,
+      "version": passport.version
+    },
+    "issuer": registryKey.issuer,
+    "issuanceDate": passport.created_at,
+    "expirationDate": computeExpirationDate(passport),
+    "proof": {
+      "type": "Ed25519Signature2020",
+      "created": passport.created_at,
+      "verificationMethod": `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      "proofPurpose": "assertionMethod",
+      "jws": signCredential(passport, registryKey)
+    }
+  };
+
+  return vc;
+}
+```
+
+### Export OAP Decision to VC
+
+```javascript
+function exportDecisionToVC(decision, registryKey) {
+  // Validate decision structure
+  if (!isValidOAPDecision(decision)) {
+    throw new Error("Invalid OAP decision structure");
+  }
+
+  // Create VC structure
+  const vc = {
+    "@context": [
+      "https://www.w3.org/2018/credentials/v1",
+      "https://raw.githubusercontent.com/aporthq/aport-spec/refs/heads/main/oap/vc/context-oap-v1.jsonld"
+    ],
+    "type": ["VerifiableCredential", "OAPDecisionReceipt"],
+    "credentialSubject": {
+      // Map all OAP decision fields
+      "decision_id": decision.decision_id,
+      "policy_id": decision.policy_id,
+      "agent_id": decision.agent_id,
+      "owner_id": decision.owner_id,
+      "assurance_level": decision.assurance_level,
+      "allow": decision.allow,
+      "reasons": decision.reasons,
+      "created_at": decision.created_at,
+      "expires_in": decision.expires_in,
+      "passport_digest": decision.passport_digest,
+      "signature": decision.signature,
+      "kid": decision.kid,
+      "decision_token": decision.decision_token,
+      "remaining_daily_cap": decision.remaining_daily_cap
+    },
+    "issuer": registryKey.issuer,
+    "issuanceDate": decision.created_at,
+    "expirationDate": new Date(new Date(decision.created_at).getTime() + decision.expires_in * 1000).toISOString(),
+    "proof": {
+      "type": "Ed25519Signature2020",
+      "created": decision.created_at,
+      "verificationMethod": `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      "proofPurpose": "assertionMethod",
+      "jws": signCredential(decision, registryKey)
+    }
+  };
+
+  return vc;
+}
+```
+
+### Import VC to OAP Objects
+
+```javascript
+function importVCToPassport(vc) {
+  // Validate VC structure
+  if (!isValidVC(vc)) {
+    throw new Error("Invalid VC structure");
+  }
+
+  // Verify signature
+  if (!verifyCredentialSignature(vc)) {
+    throw new Error("Invalid VC signature");
+  }
+
+  // Extract passport from credential subject
+  const passport = vc.credentialSubject;
+
+  // Validate OAP passport structure
+  if (!isValidOAPPassport(passport)) {
+    throw new Error("Invalid OAP passport structure");
+  }
+
+  return passport;
+}
+
+function importVCToDecision(vc) {
+  // Validate VC structure
+  if (!isValidVC(vc)) {
+    throw new Error("Invalid VC structure");
+  }
+
+  // Verify signature
+  if (!verifyCredentialSignature(vc)) {
+    throw new Error("Invalid VC signature");
+  }
+
+  // Extract decision from credential subject
+  const decision = vc.credentialSubject;
+
+  // Validate OAP decision structure
+  if (!isValidOAPDecision(decision)) {
+    throw new Error("Invalid OAP decision structure");
+  }
+
+  return decision;
+}
+```
+
+### Validation Functions
+
+```javascript
+function isValidVC(vc) {
+  return vc &&
+    vc["@context"] &&
+    vc.type &&
+    vc.credentialSubject &&
+    vc.issuer &&
+    vc.issuanceDate &&
+    vc.proof;
+}
+
+function isValidOAPPassport(passport) {
+  return passport &&
+    passport.agent_id &&
+    passport.kind &&
+    passport.spec_version &&
+    passport.owner_id &&
+    passport.owner_type &&
+    passport.assurance_level &&
+    passport.status &&
+    passport.capabilities &&
+    passport.limits &&
+    passport.regions &&
+    passport.created_at &&
+    passport.updated_at &&
+    passport.version;
+}
+
+function isValidOAPDecision(decision) {
+  return decision &&
+    decision.decision_id &&
+    decision.policy_id &&
+    decision.agent_id &&
+    decision.owner_id &&
+    decision.assurance_level &&
+    typeof decision.allow === 'boolean' &&
+    decision.reasons &&
+    decision.created_at &&
+    decision.expires_in &&
+    decision.passport_digest &&
+    decision.signature &&
+    decision.kid;
+}
+```
+
+## References
+
+- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)
+- [W3C Verifiable Credentials Implementation Guidelines](https://www.w3.org/TR/vc-imp-guide/)
+- [Ed25519Signature2020](https://w3c-ccg.github.io/lds-ed25519-2020/)
+- [JSON-LD](https://www.w3.org/TR/json-ld11/)
+- [OAP Specification](../oap-spec.md)