feat: SimpulseID credentials — schema-first domain layer on harbour-credentials

[jdsika]

Summary

Schema-first SimpulseID credential and identity framework for the ENVITED-X Data Space, built as a domain layer on top of harbour-credentials. Implements EVES-008 (SimpulseID Credential and Identity Framework) with evidence protocol per EVES-009 (Evidence-Based Consent Using Verifiable Presentations).

91 files changed, 9,675 insertions, 797 deletions across 125 commits.

---

Specification compliance

Standard	Status	Reference
EVES-008	Implemented	5 credential types, did:ethr on Base, Gaia-X alignment, schema-first pipeline
EVES-009	Implemented	Evidence VPs use HARBOUR_DELEGATE challenge format (credential.issue action)
W3C VC Data Model v2	Compliant	JSON-LD contexts, @context ordering, credentialStatus
Gaia-X Trust Framework 25.11	Compliant	LegalPerson/NaturalPerson composition via harbour layer
OID4VP	Aligned	KB-JWT transaction_data_hashes for challenge binding

---

Design Decisions

Why a domain layer, not a standalone repo?

SimpulseID extends harbour-credentials rather than reimplementing credential infrastructure. Harbour provides the cryptographic signing/verification layer (ES256, SD-JWT, delegation), the W3C VC v2 base types, and the Gaia-X compliance model. SimpulseID adds only ENVITED-specific semantics: credential types, membership chains, program metadata, and legal form enums. This separation means harbour can serve other ecosystems (not just ENVITED), while SimpulseID stays focused on ASCS e.V. governance.

Why harbourCredential IRI reference instead of inline Gaia-X data?

Each SimpulseID credential subject (Participant, Administrator, User) carries a mandatory harbourCredential IRI pointing to a separate Harbour Gaia-X compliance credential. This avoids duplicating Gaia-X data (registration numbers, addresses, legal names) across every SimpulseID credential. The Harbour credential serves as the "baseline of trust" — if Gaia-X compliance is revoked, all SimpulseID credentials referencing it become invalid via the CRSet revocation mechanism. Membership credentials (AscsBaseMembership, AscsEnvitedMembership) do NOT carry harbourCredential because they attest to a relationship, not an identity.

Why OrganizationParticipant instead of Participant?

The LinkML schema originally used class_uri: simpulseid:Participant, but the JSON-LD context generator emitted "SimpulseidParticipant": {"@id": "Participant"} — and the bare term Participant was already claimed by gx:Participant from the Gaia-X imports. This caused the SHACL shape to never fire on participant credential subjects (the type resolved to the wrong namespace). The fix was renaming to simpulseid:OrganizationParticipant, which generates a unique context term. This is documented in the EVES-008 spec with an explanatory note.

Why urn:uuid for membership credential subjects?

Membership credentials use urn:uuid: identifiers instead of participant DIDs for credentialSubject.id. If two membership credentials (base + ENVITED) shared a participant DID as their subject ID, loading both into an RDF graph would merge all properties onto a single node — conflating the base membership's hostingOrganization with the ENVITED membership's baseMembershipCredential. The urn:uuid: pattern keeps each membership as an independent graph node. The schema:member property on the membership object points back to the participant DID.

Why member vs memberOf (not interchangeable)?

schema:member is used on the membership object, pointing TO the member: AscsBaseMembership.member = <BMW DID>. schema:memberOf is used on the person, pointing TO the organization they belong to: Administrator.memberOf = [<BMW DID>]. This follows schema.org semantics and is enforced by SHACL shapes — swapping them would produce validation failures.

Why program metadata in DID service endpoints?

Program definitions (AdministratorProgram, UserProgram, BaseMembershipProgram, EnvitedMembershipProgram) are embedded as serviceEndpoint objects inside ProgramMetadataService entries on program DIDs. This is a DID Core §5.4 pattern: the program DID is externally controlled (via the controller property pointing to the issuing participant DID) and serves its metadata through standard DID resolution. The alternative — separate JSON files or a centralized API — would break the decentralized resolution model.

Why closed SHACL shapes with exclude_imports?

The SHACL generator uses closed=True (unexpected properties trigger ClosedConstraintComponent) and exclude_imports=True (only SimpulseID-defined classes get shapes). This means:

• Harbour/Gaia-X base types are NOT re-validated by SimpulseID shapes (harbour's own shapes handle those)
• Any typo or extra property in a credential is caught immediately
• The sh:ignoredProperties (rdf:type) declaration allows JSON-LD @type to coexist with closed shapes

Why HARBOUR_DELEGATE for evidence VPs?

Evidence VPs in SimpulseID use harbour's delegation module with the credential.issue action type. The nonce format is <random> HARBOUR_DELEGATE <SHA-256(TransactionData)>, where TransactionData includes the credential ID being consented to. This replaced an earlier custom format (<random> <hash>) that bypassed the delegation module and was not parseable by parse_delegation_challenge(). The HARBOUR_DELEGATE format aligns with EVES-009 §2 and makes evidence VPs verifiable through the standard delegation verification pipeline.

Why signer DIDs vs resource DIDs?

Two distinct DID patterns serve different roles:

• Signer DIDs (participants, users): Self-sovereign — carry verificationMethod with P-256 JsonWebKey, referenced from authentication and assertionMethod. No document-level controller. These DIDs sign credentials and evidence VPs.
• Resource DIDs (programs, services): Externally controlled — carry a controller property pointing to the governing participant DID, no local verificationMethod. Authority is delegated via the controller chain, not local keys.

This separation is enforced by integrity tests (test_signer_did_has_verification_method, test_resource_did_has_controller).

---

Changes by category

LinkML schemas (3 files, +560)

• simpulseid-core.yaml — 5 credential types, 5 subject types, 6 program metadata types, SimpulseIdLegalForm enum (21 values across DE/US/UK jurisdictions)
• importmap.json — 70+ cross-directory import mappings (harbour → gaia-x → service-characteristics)
• Mandatory harbourCredential IRI on Participant/Administrator/User subjects
• Membership chain enforcement: member (required), baseMembershipCredential (required on ENVITED)

Generated artifacts (1 file, +148)

• OWL ontology (simpulseid-core.owl.ttl)
• SHACL shapes (simpulseid-core.shacl.ttl) — closed shapes with sh:in enum enforcement
• JSON-LD context (simpulseid-core.context.jsonld) with type: @type alias injection
• Generated via src/generate_artifacts.py with exclude_imports=True

Python source (5 files, +466)

• generate_artifacts.py — LinkML → OWL/SHACL/JSON-LD pipeline with importmap resolution
• sign_examples.py — evidence VP signing with HARBOUR_DELEGATE challenge format via delegation module (credential.issue action)
• verify_signed_examples.py — JWT + evidence VP verification against DID keyring

Tests (13 files, +1,995)

• test_shacl_failures.py — 30 mutation-based SHACL tests across 7 test classes:
  • MinCountConstraintComponent (11 cases: issuer, validFrom, credentialStatus, harbourCredential, member, baseMembershipCredential, givenName)
  • ClosedConstraintComponent (5 cases: credential, subject, DID, program endpoint)
  • InConstraintComponent (2 cases: invalid legalForm enum values)
  • DID mutations (4 cases: missing serviceEndpoint, unexpected properties, trust anchor)
  • Program metadata mutations (2 cases: admin + membership program closed shapes)
• test_shacl_validation.py — 15 positive baselines (credentials + DIDs) + 7 invalid example regression tests
• test_examples_integrity.py — 30+ structural assertions: Gaia-X LegalPerson/NaturalPerson composition, DID key linkage (P-256 JsonWebKey in authentication + assertionMethod), cross-document IRI resolution (subject DIDs, memberOf, hostingOrganization, member, baseMembershipCredential, revocation registry), program metadata required fields, IRI type pollution regression guard (issue fix: DID document fixtures fail SHACL validation when loaded as data #28)
• test_evidence_proof.py — evidence VP signing and verification parametrized across all 5 credential types, full proof chain (evidence VP → outer VC), sign-verify fixture roundtrip

Examples (21 files, +992/−223)

• 5 credential examples with Gaia-X composition and CRSet revocation entries
• 10 did:ethr DID documents: 2 signer (participant), 2 signer (user), 4 program, 1 trust anchor service, 1 revocation registry service
• Evidence VPs with HARBOUR_DELEGATE nonce format and did:key ephemeral holders

Documentation (17 files, +2,116)

• MkDocs Material site: architecture, credential data model, DID identity system
• Specification reference copies (DID Core, did:ethr method, Gaia-X ICAM 25.11, SD-JWT)
• artifacts/README.md documenting the generation pipeline and artifact structure

Wallet manifests (6 files, +525/−78)

• DIF/Altme-compatible wallet rendering manifests for all 5 credential types
• Display mappings for credential fields to wallet UI

CI/CD and build (12 files, +1,380/−17)

• GitHub Actions pipeline: standards-and-syntax, lint-markdown, generate-validate (3 OS), test-python (3 OS × 2 Python), test-ts (3 OS), credential story (3 OS)
• cliff.toml for git-cliff release changelog generation
• dependabot.yml for automated pip and github-actions dependency updates
• npm cache for markdownlint-cli2, yarn cache for TypeScript tests
• cd-release.yml with semantic versioning, pre-release detection, GitHub Pages docs deployment
• cd-docs.yml with path-based triggering for documentation changes

Submodule pins

• harbour-credentials: OMB v0.1.6 (CI artifact generation verification, cross-platform matrix), w3id.org at upstream master, EVES-009 compliance fixes (revocation warning, transaction freshness)
• w3id.org (top-level): upstream master (d004a453) with merged reachhaven/harbour and ascs-ev/simpulse-id namespace redirect rules

---

Test plan

• make story passes (generate → sign → verify → validate)
• make test simpulseid — all SHACL + integrity + evidence tests green (156 passed)
• make lint passes (pre-commit hooks green)
• CI pipeline passes on all OS × Python matrix
• git submodule status --recursive clean after fresh clone

[jdsika]

Audit resolution — 6 new commits pushed

Submodule pins

• 95a4568 chore: pin harbour-credentials with OMB v0.1.6 and sync w3id.org

Test coverage gaps closed

• f8d74e3 test: close SHACL test coverage gaps
  • +2 parametrized mandatory field cases (User-missing-validFrom, Administrator-missing-givenName)
  • +2 enum constraint tests (SimpulseIdLegalForm sh:in violation)
  • +2 program metadata closed shape tests (Admin/Membership endpoints)
  • +8 program integrity assertions (required fields per program type)
  • Evidence VP signing parametrized across all 5 credential types

CI/CD

• 56ec55c ci: add cliff.toml, Node.js caching, and dependabot

EVES-009 compliance

• d6b7c74 fix: align evidence VP nonce with EVES-009 delegation challenge format
  • Evidence VPs now use <nonce> HARBOUR_DELEGATE <hash> via delegation module
  • Action type: credential.issue (registered in harbour ACTION_LABELS)
  • Harbour: added revocation warning + optional transaction freshness in verify_sd_jwt_vp()

Verification

• make story passes end-to-end
• All SHACL tests pass (60 passed)
• All evidence + integrity tests pass (96 passed)
• Harbour SD-JWT VP tests pass (23 passed)
• Pre-commit hooks green