feat(harbour): schema-first Gaia-X Loire compliance, delegated signing, did:ethr

[jdsika]

Summary

This branch transforms harbour-credentials from a basic VC signing library into a full credential infrastructure for the ENVITED-X Data Space. It adds Gaia-X Loire (25.11) compliance, an OID4VP-based delegated signing evidence protocol, and migrates from did:web to did:ethr on Base (ERC-1056).

141 files changed, 27,956 insertions, 2,153 deletions across 78 commits.

---

Design Decisions

Why did:ethr over did:web?

did:web ties DID resolution to DNS and HTTPS infrastructure — if a domain changes or a TLS certificate expires, all credentials become unresolvable. did:ethr anchors identity on-chain via ERC-1056, making DIDs independent of any single hosting provider. The trade-off is blockchain dependency, but Base (Ethereum L2) provides low-cost operations with Ethereum-grade finality. P-256 was chosen over secp256k1 because Gaia-X and the W3C VC ecosystem standardize on ES256 (P-256), and EUDI wallets require it.

Why OID4VP dual-hash binding instead of simple nonce = hash(message)?

EVES-009 specifies that the VP nonce should equal the message hash. Harbour instead uses the OID4VP standard's dual-binding approach: the VP nonce carries a random value for replay prevention, while the KB-JWT transaction_data_hashes array carries SHA-256(base64url(transaction_data)) for message binding. This was chosen because:

1. Standard OID4VP wallets (EUDI, Sphereon, walt.id) expect KB-JWT binding, not a custom nonce format
2. Separating replay prevention from message binding avoids conflating two distinct security properties
3. Multiple evidence items in a single VP require an array of hashes — a single nonce field cannot bind to multiple messages

A review comment on EVES-009 suggests the spec be relaxed to accommodate both approaches.

Why delegation via evidence VPs, not DID capabilityDelegation?

The ENVITED use case requires proving that a specific user consented to a specific action (e.g., issuing a credential, executing a blockchain transaction). DID-level capabilityDelegation grants blanket authority — it cannot be scoped to individual transactions or carry consent evidence. The evidence VP approach binds consent to a deterministic challenge derived from the action, creating an independently verifiable audit trail. This follows the pattern described in EVES-009 §1.

Why SD-JWT-VC as the recommended format?

SD-JWT-VC (RFC 9901) supports selective disclosure — holders can redact claims before presenting credentials. This is critical for GDPR compliance: an administrator credential contains givenName, familyName, email, and address, but a service verifying membership only needs the memberOf reference. SD-JWT-VC lets the holder present only what's needed. The format also supports key binding (proving holder possession) and is the format mandated by the EUDI Architecture Reference Framework.

Why schema-first with LinkML?

All credential types, subject shapes, and property constraints are defined in LinkML YAML schemas. A single make generate produces OWL ontologies, SHACL validation shapes, and JSON-LD contexts. This eliminates drift between the data model and its machine-readable artifacts. The SHACL shapes use sh:closed true so unexpected properties are rejected, and exclude_imports=True ensures only harbour-defined types get shapes (Gaia-X base types are validated by upstream shapes).

Why Gaia-X composition over flat credentials?

Harbour credentials use a composition pattern: gx:LegalPerson and harbour.gx:NaturalPerson are inlined as blank nodes inside the credential subject's participant property, rather than flattened into the subject itself. This preserves the Gaia-X type hierarchy (a NaturalPerson IS-A gx:Participant) while allowing domain layers like SimpulseID to add their own properties (harbourCredential, legalForm, memberOf) without polluting the Gaia-X namespace.

Why CRSet revocation instead of X.509 CRL/OCSP?

Harbour uses a Credential Revocation Set (harbour:CRSetEntry) queryable via DID service endpoints, rather than X.509-style certificate revocation. CRSet entries are identified by <registry-did>/<credential-hash>, making revocation checks resolvable through the same DID infrastructure used for identity. This avoids introducing a separate PKI dependency.

---

Changes by category

LinkML schemas (8 files, +1,652/−458)

• harbour-core-credential.yaml — W3C VC v2 infrastructure types (HarbourCredential, CRSet, Evidence, DIDDocument, VerificationMethod)
• harbour-gx-credential.yaml — Gaia-X concrete types (LegalPerson, NaturalPerson, gxParticipant composition slot)
• harbour-core-delegation.yaml — OID4VP transaction data, delegation challenge encoding, evidence binding
• w3c-vc.yaml — thin shim projecting W3C VC v2 vocabulary terms into LinkML
• importmap.json — 80+ cross-directory import mappings through the OMB submodule chain

Python source (15 files, +2,056/−493)

• delegation.py — TransactionData creation/validation, challenge format (<nonce> HARBOUR_DELEGATE <hash>), SIWE-style consent display, OID4VP transaction_data parameter encoding
• sd_jwt.py — SD-JWT-VC issuance with structured selective disclosure (RFC 9901 §6.2), flat and nested disclosure paths
• kb_jwt.py — Key Binding JWT with sd_hash and transaction_data_hashes per OID4VP Appendix B.3.3
• sd_jwt_vp.py — SD-JWT VP issuance/verification with evidence binding, revocation status warning, optional transaction freshness check
• x509.py — X.509 self-signed certificate generation, chain validation, x5c header support
• keys.py — did:ethr derivation (P-256 uncompressed → keccak256 → Ethereum address), did:key multibase encoding
• credentials/example_signer.py — multi-key trust chain signing pipeline with role-based DID → kid mapping

TypeScript source (7 files, +1,046/−22)

• Feature parity with Python: delegation.ts, sd-jwt.ts, kb-jwt.ts, sd-jwt-vp.ts, x509.ts, keys.ts, signer.ts
• Uses jose library (WebCrypto API) for all crypto operations

Tests (34 files, +4,268/−437)

• test_delegation.py (55 tests) — shared canonicalization vectors, challenge parse/verify, CLI, display rendering, validation edge cases
• test_sd_jwt.py (28 tests) — RFC 9901 structured disclosure, partial/full/no disclosure, cnf binding, Ed25519 support
• test_kb_jwt.py (18 tests) — transaction data hashing, sd_hash computation, wrong key/nonce/audience detection
• test_sd_jwt_vp.py (23 tests) — full delegated consent flow, privacy-preserving audit scenario, multiple evidence items
• test_shacl_failures.py — mutation-based SHACL tests for harbour credential shapes
• 9 TypeScript test files mirroring Python test structure
• Cross-runtime interop tests (Python signs → TypeScript verifies, vice versa)

Documentation (36 files, +16,213/−263)

• 5 Architecture Decision Records: VC securing mechanism, dual runtime, canonicalization, key management, did:ethr migration
• Credential lifecycle guide with mermaid swimlane diagrams
• DID identity system overview
• Getting started (installation + quickstart for Python and TypeScript)
• API reference (Python via mkdocstrings, TypeScript via TypeDoc)
• Specification reference copies (DID Core, SD-JWT, OID4VP, Gaia-X ICAM 25.11, VC-JOSE-COSE)

Examples (25 files, +1,805/−166)

• did:ethr DID documents: signing service (with delegate key), trust anchor, legal person, natural person
• Gaia-X credentials: LegalPerson and NaturalPerson with evidence VPs
• Nested evidence example showing 2-level evidence chain

CI/CD and build (7 files, +733/−244)

• Credential lifecycle story job (generate → sign → verify → SHACL validate)
• OS × Python version matrix (ubuntu/macos/windows × 3.12/3.13)
• Migrated from black/isort/flake8 to ruff
• w3id artifact publishing in release workflow (OWL/SHACL/JSON-LD served via GitHub Pages)
• OMB pinned to v0.1.6, w3id.org synced to upstream master (all namespace redirects merged)

---

Test plan

• make test full passes (Python + TypeScript + interop)
• make story passes (generate → sign → verify → validate)
• make lint passes
• CI matrix green (3 OS × 2 Python versions)