[caparicio-esd]

Summary

This PR integrates Eclipse EDC IdentityHub as a delegated wallet backend for Alexandria alongside Fafnir, adopting hexagonal architecture principles, rich key management (PEM and JWK), DID lifecycle management, Verifiable Credential storage & querying, DCP issuance requests, participant context administration, and structured error propagation.

---

Key Changes

1. Hexagonal Architecture Alignment

• Secondary Port (wallet.Wallet): Extended the secondary port interface to declare capabilities for extended key management, DID publishing/unpublishing, service endpoints, credential containers, DCP requests, and participant context administration.
• IdentityHub Adapter (identityhub/):
  • Implemented Adapter and low-level EdcClient (edc_client.go) adhering to hexagonal naming conventions.
  • Implemented data normalization in normalize.go with robust type parsing and safe JSON serialization.
• Fafnir Adapter (fafnir/):
  • Renamed client.go to adapter.go for architectural consistency.
  • Implemented unsupported method stubs returning common.ErrNotImplementedInFafnir.
• Driving Adapter (rest/):
  • Clean HTTP routing in wallet_router.go and wire DTOs in wallet_dto.go.

2. Key Pair Operations

• Added support for both PEM and serialized JWK (JsonWebKey2020 / Ed25519) in POST /api/v1/ssi-auth/wallet/keys.
• Key rotation (POST /api/v1/ssi-auth/wallet/keys/:id/rotate) with configurable overlap duration.
• Key revocation (POST /api/v1/ssi-auth/wallet/keys/:id/revoke).
• Automatic resolution of internal IdentityHub key resource IDs.
• Cleaned up GET /api/v1/ssi-auth/wallet/keys (excluded unused .usage field).

3. DID Lifecycle & Service Endpoints

• Full state machine integration:
  • POST /api/v1/ssi-auth/wallet/did: Registration.
  • GET /api/v1/ssi-auth/wallet/did/:id/state: Query state (PUBLISHED, UNPUBLISHED).
  • POST /api/v1/ssi-auth/wallet/did/:id/publish: Publish DID (reactivating participant context if needed).
  • POST /api/v1/ssi-auth/wallet/did/:id/unpublish: Unpublish DID (deactivating participant context as required by IdentityHub).
  • DELETE /api/v1/ssi-auth/wallet/did/:id: Delete DID after unpublishing.
• Service endpoints:
  • POST /api/v1/ssi-auth/wallet/did/:id/endpoints: Add service endpoint.
  • DELETE /api/v1/ssi-auth/wallet/did/:id/endpoints/:endpoint_id: Remove service endpoint via query param (?serviceId=).

4. Verifiable Credentials & DCP Requests

• POST /api/v1/ssi-auth/wallet/credential: Supports both verifiableCredentialContainer and flat format, automatically building minimal W3C credential JSON when omitted.
• GET /api/v1/ssi-auth/wallet/vcs: Fixed response serialization for raw JWT strings; safely normalizes and outputs complete credential payloads.
• GET /api/v1/ssi-auth/wallet/vcs?type=:type: Filtering by credential type.
• DELETE /api/v1/ssi-auth/wallet/credential/:id: Deletes stored credential.
• POST /api/v1/ssi-auth/wallet/dcp/request: Supports issuerDid and credentials descriptors, with fallback extraction of requestId from the HTTP Location header.
• GET /api/v1/ssi-auth/wallet/dcp/request/:id: Query DCP request status.

5. Participant Context Management

• POST /api/v1/ssi-auth/wallet/participants: Create participant contexts with optional keyDescriptor (defaults to EdDSA/Ed25519).
• GET /api/v1/ssi-auth/wallet/participants/:id: Query participant context.
• POST /api/v1/ssi-auth/wallet/participants/:id/state: Activate/deactivate participant context.
• POST /api/v1/ssi-auth/wallet/participants/:id/token: Regenerate API key token and update the in-memory client immediately.
• PUT /api/v1/ssi-auth/wallet/participants/:id/token: Hot-update participant API token in memory.

6. Configuration, Documentation & Postman

• Added config/config-ih.yaml for local development against IdentityHub.
• Added ADR docs/adr/0002-identityhub-integration-data-models-mutation-queries-and-structured-errors.md.
• Added Postman collection under postman/collections/Ssi-auth/IdentityHub/.

---

Verification

• task fmt: All Go files formatted with gofumpt.
• task lint: 0 issues with golangci-lint.
• task test: 100% unit tests passing across all packages (cmd, internal/...).
• task test:integration:identityhub: Live integration tests passing against running IdentityHub container.
• End-to-end verified with live HTTP requests via Alexandria proxy and Caddy.