Verify Capability

Overview

Cryptographically verify that a human or agent possesses a specific capability before routing tasks, granting access, or delegating authority. Verification is instant, unforgeable, and backed by immutable provenance.

Why Verify Capabilities?

• Trust but Verify: Don't rely on self-reported skills—verify them cryptographically
• Safe Routing: Ensure tasks are matched to qualified humans/agents
• Compliance: Meet regulatory requirements for qualified personnel
• Quality Assurance: Prevent unqualified actors from performing critical tasks
• Zero Knowledge: Verify capabilities without exposing sensitive evidence
• Offline-Ready: Verification works even without network connectivity

Think of it like: Checking a doctor's medical license before surgery—you verify credentials, not just trust claims.

How Capability Verification Works

HUMΛN uses a cryptographic capability model with three layers of verification:

1. Signature Verification: Prove the capability was granted by a trusted authority
2. Evidence Validation: Confirm the evidence backing the capability is authentic
3. Freshness Check: Ensure the capability hasn't expired or been revoked
4. Chain of Trust: Validate the grantor's authority to issue the capability

┌─────────────────────────────────────────────────────────────┐
│  Capability Grant (Cryptographically Signed)                │
│  ───────────────────────────────────────────────────────    │
│  Recipient: did:human:alice                                 │
│  Capability: "ai_safety_evaluation"                         │
│  Weight: 0.85 (85% confidence)                              │
│  Granted By: did:human:org:human-academy                    │
│  Evidence: Course completion + 15 verified tasks            │
│  Signature: 0x7a3f9b2c...                                   │
│  Ledger Proof: 0x4e8d1a9f...                                │
│  Valid Until: 2027-01-10                                    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
            ┌──────────────────────────┐
            │  Verification Process    │
            │  ✓ Signature valid?      │
            │  ✓ Grantor authorized?   │
            │  ✓ Not expired?          │
            │  ✓ Not revoked?          │
            │  ✓ Evidence authentic?   │
            └──────────────────────────┘
                           │
                           ▼
                    ✅ Verified!

SDK Examples

typescript:TypeScript
```typescript
import { HumanOS } from '@human/sdk';

async function verifyCapability(
  passportDid: string,
  requiredCapability: string,
  minimumWeight: number = 0.7
) {
  try {
    const verification = await HumanOS.CapabilityGraph.verifyCapability({
      passportDid: passportDid,
      capability: requiredCapability,
      minimumWeight: minimumWeight,
      checkRevocation: true, // Check if capability was revoked
      checkExpiry: true, // Check if capability expired
    });
    
    if (!verification.verified) {
      console.warn(`Capability verification failed: ${verification.reason}`);
      return false;
    }
    
    console.log(`✅ Capability verified!`);
    console.log(`  Capability: ${verification.capability.name}`);
    console.log(`  Weight: ${verification.capability.weight}`);
    console.log(`  Granted by: ${verification.capability.grantedBy}`);
    console.log(`  Evidence: ${verification.capability.evidence.type}`);
    console.log(`  Valid until: ${verification.capability.validUntil}`);
    
    return true;
  } catch (error) {
    console.error("Capability verification error:", error);
    throw error;
  }
}

// Example: Verify before routing a task
async function routeTaskSafely(task: Task) {
  const candidates = await findCandidates(task);
  
  for (const candidate of candidates) {
    const isQualified = await verifyCapability(
      candidate.passportDid,
      task.requiredCapability,
      0.8 // Require 80% confidence
    );
    
    if (isQualified) {
      await assignTask(task, candidate);
      return;
    }
  }
  
  console.warn("No qualified candidates found");
}
```

python:Python
```python
from human_sdk import HumanOS
from typing import Optional

async def verify_capability(
    passport_did: str,
    required_capability: str,
    minimum_weight: float = 0.7
) -> bool:
    try:
        verification = await HumanOS.CapabilityGraph.verify_capability(
            passport_did=passport_did,
            capability=required_capability,
            minimum_weight=minimum_weight,
            check_revocation=True,  # Check if capability was revoked
            check_expiry=True,  # Check if capability expired
        )
        
        if not verification.verified:
            print(f"⚠️  Capability verification failed: {verification.reason}")
            return False
        
        print(f"✅ Capability verified!")
        print(f"  Capability: {verification.capability.name}")
        print(f"  Weight: {verification.capability.weight}")
        print(f"  Granted by: {verification.capability.granted_by}")
        print(f"  Evidence: {verification.capability.evidence.type}")
        print(f"  Valid until: {verification.capability.valid_until}")
        
        return True
    except Exception as e:
        print(f"Capability verification error: {e}")
        raise

# Example: Verify before delegating authority
async def delegate_safely(human_did: str, agent_did: str, scope: str):
    # Verify the agent has the required capability
    has_capability = await verify_capability(
        passport_did=agent_did,
        required_capability=f"delegation:{scope}",
        minimum_weight=0.75
    )
    
    if not has_capability:
        raise PermissionError(f"Agent lacks required capability: delegation:{scope}")
    
    # Proceed with delegation
    await HumanOS.Passport.delegate(
        grantor_did=human_did,
        delegatee_did=agent_did,
        scopes=[scope]
    )
```

go:Go
```go
package main

import (
    "fmt"
    "github.com/human/sdk-go/humanos"
)

func verifyCapability(
    passportDID string,
    requiredCapability string,
    minimumWeight float64,
) (bool, error) {
    verification, err := humanos.CapabilityGraph.VerifyCapability(humanos.VerifyCapabilityRequest{
        PassportDID:     passportDID,
        Capability:      requiredCapability,
        MinimumWeight:   minimumWeight,
        CheckRevocation: true,
        CheckExpiry:     true,
    })
    if err != nil {
        return false, fmt.Errorf("capability verification error: %w", err)
    }
    
    if !verification.Verified {
        fmt.Printf("⚠️  Capability verification failed: %s\n", verification.Reason)
        return false, nil
    }
    
    fmt.Printf("✅ Capability verified!\n")
    fmt.Printf("  Capability: %s\n", verification.Capability.Name)
    fmt.Printf("  Weight: %.2f\n", verification.Capability.Weight)
    fmt.Printf("  Granted by: %s\n", verification.Capability.GrantedBy)
    fmt.Printf("  Evidence: %s\n", verification.Capability.Evidence.Type)
    fmt.Printf("  Valid until: %s\n", verification.Capability.ValidUntil)
    
    return true, nil
}

// Example: Verify access before allowing operation
func authorizeOperation(passportDID, operation string) error {
    verified, err := verifyCapability(
        passportDID,
        fmt.Sprintf("operations:%s", operation),
        0.8, // 80% confidence required
    )
    if err != nil {
        return err
    }
    if !verified {
        return fmt.Errorf("insufficient capability for operation: %s", operation)
    }
    return nil
}
```

REST API Example

POST /v1/capability-graph/verify
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

{
  "passportDid": "did:human:alice",
  "capability": "ai_safety_evaluation",
  "minimumWeight": 0.8,
  "checkRevocation": true,
  "checkExpiry": true
}

Response (200 OK - Verified):

{
  "verified": true,
  "capability": {
    "id": "cap:human:a1b2c3d4e5f6...",
    "name": "ai_safety_evaluation",
    "category": "ai_safety",
    "weight": 0.85,
    "grantedBy": "did:human:org:human-academy",
    "grantedAt": "2026-01-01T12:00:00Z",
    "validUntil": "2027-01-01T12:00:00Z",
    "evidence": {
      "type": "training",
      "description": "Completed Advanced AI Safety course",
      "metadata": {
        "courseId": "AIS-201",
        "grade": "A"
      }
    },
    "ledgerProof": "0x4e8d1a9f..."
  },
  "verificationTimestamp": "2026-01-10T14:30:00Z"
}

Response (200 OK - Not Verified):

{
  "verified": false,
  "reason": "capability_expired",
  "details": "Capability expired on 2025-12-31T23:59:59Z",
  "suggestion": "Request capability renewal or re-certification"
}

Verification Failure Reasons

Reason	Description	Resolution
capability_not_found	No matching capability in graph	Grant capability first
insufficient_weight	Capability weight below minimum	Improve evidence or lower threshold
capability_expired	Capability past its validity date	Renew or re-certify
capability_revoked	Capability was explicitly revoked	Investigate revocation reason
invalid_signature	Cryptographic signature verification failed	Evidence may be forged
unauthorized_grantor	Grantor lacked authority to issue capability	Verify grantor credentials

Verification Confidence Levels

Different use cases require different confidence levels:

Use Case	Minimum Weight	Rationale
Critical Safety (medical, aviation)	0.95	Lives at stake—require near-certainty
Financial Transactions	0.90	Money at stake—high confidence needed
Enterprise Operations	0.80	Business impact—solid verification
Content Moderation	0.70	Lower risk—moderate confidence acceptable
Task Recommendations	0.50	Exploratory—suggest based on partial match

Offline Verification

Capability verification can work offline using cached capability bundles:

import { HumanOS } from '@human/sdk';

async function verifyCapabilityOffline(
  passportDid: string,
  capability: string,
  capabilityBundle: CapabilityBundle // Pre-downloaded
) {
  // Verify cryptographic signature (no network required)
  const isValid = await HumanOS.CapabilityGraph.verifyOffline({
    passportDid: passportDid,
    capability: capability,
    bundle: capabilityBundle,
    checkRevocation: false, // Skip network call
  });
  
  if (!isValid.verified) {
    console.warn(`Offline verification failed: ${isValid.reason}`);
  }
  
  return isValid.verified;
}

Note: Offline verification can't check for real-time revocations. Use online verification for high-security scenarios.

Zero-Knowledge Verification

Verify capabilities without revealing the evidence:

// Verify Alice has "security_clearance" without learning the details
const verified = await HumanOS.CapabilityGraph.verifyZeroKnowledge({
  passportDid: "did:human:alice",
  capability: "security_clearance",
  minimumWeight: 0.9,
  // Evidence remains encrypted—only proof is shared
});

console.log(verified.verified); // true or false
console.log(verified.evidenceType); // "confidential" (no details exposed)

This is critical for:

• Privacy-sensitive capabilities (medical licenses, security clearances)
• Competitive advantages (proprietary skills, trade secrets)
• Regulatory compliance (GDPR, HIPAA)

Batch Verification

Verify multiple capabilities at once for efficiency:

const verifications = await HumanOS.CapabilityGraph.verifyBatch({
  passportDid: "did:human:alice",
  capabilities: [
    { name: "typescript", minimumWeight: 0.8 },
    { name: "react", minimumWeight: 0.7 },
    { name: "nodejs", minimumWeight: 0.75 },
  ],
});

// Results:
// [
//   { capability: "typescript", verified: true, weight: 0.9 },
//   { capability: "react", verified: true, weight: 0.85 },
//   { capability: "nodejs", verified: false, weight: 0.6 }
// ]

const allVerified = verifications.every(v => v.verified);

network:Task Routing|Verify workers have required skills before assigning complex tasks
shield:Access Control|Verify capabilities before granting system permissions or delegations
building:Hiring & Staffing|Verify candidate qualifications during recruitment processes
bot:Agent Deployment|Verify AI agents have required capabilities before autonomous operation

do:Always verify capabilities before granting critical access
do:Use appropriate minimum weight thresholds for risk level
do:Check for both expiry and revocation in production
do:Log all verification attempts for audit trails
dont:Skip verification to save processing time in critical paths
dont:Trust capabilities without checking the grantor's authority
dont:Use offline verification for high-security scenarios
dont:Ignore verification failures - escalate to human review

Next Steps

• Learn how to Grant Capabilities
• Understand Capability-First Routing
• Explore Provenance Tracking

---

See Also

• Concept Doc: Capability Graph
• API Reference: Verify Capability API
• SDK Reference: CapabilityGraph.verifyCapability()