security: DID cryptographic identity audit — SDK fixes

- Add verify_w3c_credential() for offline W3C VC v2.0 verification
- Add format param to get_reputation_credential() (avp/w3c)
- Document did:key risk, challenge-response, credential signing in SECURITY.md
- Part of full DID/crypto identity revision (Sprint 1+2)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: creatorrmode-lead

SECURITY.md

@@ -30,6 +30,39 @@ We will acknowledge receipt within **48 hours** and aim to provide an initial as
 - **Audit trail** — SHA-256 hash-chained logs anchored to IPFS
 - **Key storage** — local keys saved with `chmod 0600` permissions
 
+## Cryptographic Identity
+
+### DID Method: did:key
+
+AVP uses `did:key` (W3C CCG, Ed25519) for agent identifiers. This is a **stateless, self-certifying** method: the DID is derived deterministically from the public key.
+
+**By design, did:key does not support:**
+- Key rotation (new key = new DID)
+- DID deactivation/revocation at the protocol level
+- Key recovery after loss
+
+**Implications for key compromise:** If an agent's private key is compromised, the attacker gains full control of that identity. AVP mitigates this server-side: agents can be suspended or revoked via the AVP registry, and webhook alerts notify operators of anomalous score drops. However, this protection is scoped to the AVP ecosystem.
+
+**Recommendations:**
+- Use encrypted key storage (`agent.save(passphrase="...")`) with Argon2id key derivation for production agents.
+- For long-lived, high-value agents, consider `did:web` (supports rotation, revocation, key history) when AVP adds support.
+- Store keys in hardware security modules (HSM) or secure enclaves where possible.
+- Monitor reputation velocity alerts for early compromise detection.
+
+### Challenge-Response Authentication
+
+- **Registration challenge:** 64 random hex chars (`secrets.token_hex(32)`), stored in Redis with 300-second TTL. Expired challenges auto-delete. One-time use — consumed on verification.
+- **API request auth:** Ed25519 signature over `{method}:{path}:{timestamp}:{nonce}:{body_sha256}`. Timestamp window: 60 seconds. Nonces tracked in Redis with 120-second TTL (2x timestamp window for safety margin). Redis unavailable = fail closed (503).
+- **Proof-of-Work:** Required on registration to prevent Sybil attacks. SHA-256 with configurable difficulty (default 24 leading zero bits).
+
+### Credential Signing
+
+Reputation credentials are signed by the server's Ed25519 key (configured via `CREDENTIAL_SIGNING_KEY_HEX`). Two formats available:
+- **AVP format:** Custom JSON with hex-encoded signature. Verify with `AVPAgent.verify_credential()`.
+- **W3C VC v2.0 format:** Standards-compliant Verifiable Credential with Data Integrity proof (`eddsa-jcs-2022`). Verify with any VC library or `AVPAgent.verify_w3c_credential()`.
+
+Ephemeral signing keys are rejected in production (`CREDENTIAL_SIGNING_KEY_HEX` must be set).
+
 ## Disclosure Policy
 
 We follow coordinated disclosure. Please do not open public issues for security vulnerabilities.

agentveil/agent.py

@@ -788,6 +788,7 @@ def get_reputation_credential(
         self,
         did: Optional[str] = None,
         risk_level: str = "medium",
+        format: str = "avp",
     ) -> dict:
         """
         Get a signed reputation credential for offline verification.
@@ -799,20 +800,26 @@ def get_reputation_credential(
             did: Agent DID (defaults to self)
             risk_level: "low" (60min TTL), "medium" (15min), "high" (5min).
                         "critical" is rejected — use get_reputation() instead.
+            format: "avp" (default, AVP-native format) or "w3c" (W3C VC v2.0).
+                    W3C format is verifiable by any standard VC library.
 
         Returns:
-            dict with did, score, confidence, issued_at, expires_at,
-            ipfs_cid, risk_level, signature, signer_did
+            dict — AVP format or W3C Verifiable Credential depending on format param.
+            Use verify_credential() for AVP format, verify_w3c_credential() for W3C.
         """
         if risk_level not in ("low", "medium", "high", "critical"):
             raise AVPValidationError(
                 f"Invalid risk_level: {risk_level}. Must be low/medium/high/critical"
             )
+        if format not in ("avp", "w3c"):
+            raise AVPValidationError(
+                f"Invalid format: {format}. Must be avp or w3c"
+            )
         target = did or self._did
         with httpx.Client(base_url=self._base_url, timeout=self._timeout) as c:
             r = c.get(
                 f"/v1/reputation/{target}/credential",
-                params={"risk_level": risk_level},
+                params={"risk_level": risk_level, "format": format},
             )
             return self._handle_response(r)
 
@@ -877,6 +884,86 @@ def verify_credential(credential: dict) -> bool:
         except Exception:
             return False
 
+    @staticmethod
+    def verify_w3c_credential(credential: dict) -> bool:
+        """
+        Verify a W3C VC v2.0 reputation credential offline — no API call needed.
+
+        Checks:
+        1. W3C VC structure (@context, type, proof)
+        2. Temporal validity (validFrom/validUntil)
+        3. Data Integrity proof (eddsa-jcs-2022): Ed25519 signature over
+           JCS-canonicalized credential (proof removed)
+
+        Args:
+            credential: The W3C VC dict from get_reputation_credential(format="w3c")
+
+        Returns:
+            True if the credential is valid, not expired, and signature checks out
+        """
+        import base58
+        from datetime import datetime, timezone, timedelta
+
+        try:
+            # Structure checks
+            contexts = credential.get("@context", [])
+            if "https://www.w3.org/ns/credentials/v2" not in contexts:
+                return False
+            types = credential.get("type", [])
+            if "VerifiableCredential" not in types:
+                return False
+            proof = credential.get("proof")
+            if not proof or proof.get("type") != "DataIntegrityProof":
+                return False
+            if proof.get("cryptosuite") != "eddsa-jcs-2022":
+                return False
+
+            # Temporal validity
+            now = datetime.now(timezone.utc)
+            valid_until = credential.get("validUntil")
+            if valid_until:
+                expires = datetime.strptime(
+                    valid_until, "%Y-%m-%dT%H:%M:%SZ"
+                ).replace(tzinfo=timezone.utc)
+                if now > expires:
+                    return False
+            valid_from = credential.get("validFrom")
+            if valid_from:
+                starts = datetime.strptime(
+                    valid_from, "%Y-%m-%dT%H:%M:%SZ"
+                ).replace(tzinfo=timezone.utc)
+                if now < starts - timedelta(seconds=60):
+                    return False
+
+            # Extract public key from verification method DID
+            vm = proof.get("verificationMethod", "")
+            signer_did = vm.split("#")[0]
+            if not signer_did.startswith("did:key:z"):
+                return False
+            decoded = base58.b58decode(signer_did[9:])
+            if len(decoded) < 2 or decoded[0] != 0xED or decoded[1] != 0x01:
+                return False
+            public_key = decoded[2:]
+            if len(public_key) != 32:
+                return False
+
+            # Reconstruct signed payload (credential without proof)
+            payload = {k: v for k, v in credential.items() if k != "proof"}
+            message = json.dumps(
+                payload, sort_keys=True, separators=(",", ":")
+            ).encode()
+
+            # Decode multibase proof value and verify
+            proof_value = proof.get("proofValue", "")
+            if not proof_value.startswith("z"):
+                return False
+            signature = base58.b58decode(proof_value[1:])
+            verify_key = VerifyKey(public_key)
+            verify_key.verify(message, signature)
+            return True
+        except Exception:
+            return False
+
     def get_agent_info(self, did: Optional[str] = None) -> dict:
         """Get public info about an agent."""
         target = did or self._did