Technical & logical architecture
proConsul is a stateless orchestration layer — a control plane that sequences and coordinates discrete trust services: an API gateway, a policy/orchestration engine, and dedicated verification, issuance, presentation, status-list, and timestamping (TSA) services. All cryptographic operations are delegated to TrustVault via an HSM-broker; proConsul never holds key material. Postgres registries persist credential and status state; HashiCorp Vault manages secrets. The diagrams below depict exactly this topology.
Logical architecture
proConsul sits between the API gateway and the domain services that perform real credential work. The gateway handles TLS termination, authentication, and rate-limiting; the policy/orchestration layer decides which service to invoke and in what order; downstream services — verification, issuance, presentation, status-list, and TSA — execute discrete operations and write results to Postgres registries. No component crosses these boundaries: the orchestration layer is intentionally stateless so it scales horizontally without coordination overhead.
Part 1 · Gateway to services — how requests enter the platform
Control, data & identity planes
proConsul's architecture separates concerns across distinct planes for clearer security boundaries and operational clarity.
The policy/orchestration engine and gateway together form the control plane. The gateway enforces authentication and admission; the orchestration engine resolves policy rules — attribute requirements, trust-level thresholds, revocation-check obligations — and determines which trust service to invoke and in what sequence. No credential payload data transits this plane; it handles decisions and routing only.
The five trust services — verification, issuance, presentation, status-list, and TSA — operate in the data plane. They handle credential-payload processing: constructing OID4VCI credential responses, validating OID4VP proofs, generating W3C StatusList2021 bitstrings, and recording RFC 3161 timestamps. Signing calls are always delegated to the HSM-broker; the data plane services receive the signed payload back and embed it into the credential structure.
Handles authentication, authorization, and identity federation. External IdPs (national registries, enterprise directories, OpenID Connect providers) are federated at the gateway. DID-based subject identifiers — engineered to align with W3C Decentralized Identifiers — are resolved here and bound to credential subject records in the Postgres registry. The identity plane establishes the verified subject context that the orchestration engine uses for policy evaluation.
Operational configuration, health monitoring, and Vault secret rotation live in the management plane, isolated from trust-operation traffic. Operators configure service endpoints, credential schema versions, TSA policies, and HSM-broker parameters here. Separation from the control and data planes means a management-plane operation — such as a schema upgrade or certificate rotation — cannot interrupt in-flight credential transactions.
Part 2 · Services to data stores — where state lives
Deployment topology
proConsul is deployable as a coordinated set of containerised services behind a gateway — on-premises, in a private cloud, or in a hybrid topology with HSM hardware on-site. The orchestration layer and the five trust services are stateless and scale horizontally; only the Postgres registries and Vault cluster carry durable state. Existing IdPs and enterprise directories integrate at the gateway via OpenID Connect or SAML 2.0 federation — no rip-and-replace of identity infrastructure is required.
Data flows & request processing
Both flows illustrate the separation of concerns: the gateway admits and authenticates, the orchestration engine decides and sequences, the trust services execute narrow operations, TrustVault signs, and the registries persist state. The orchestration engine is the only component that calls more than one downstream service in a single transaction.
The holder (wallet or portal) POSTs a credential request to the gateway's OID4VCI credential endpoint, presenting a proof-of-possession JWT bound to the subject DID.
The gateway validates the bearer token (OAuth 2.0 access token from the authorisation server) and the proof-of-possession DID binding, then forwards the authenticated request to the orchestration engine.
The orchestration engine resolves the applicable issuance policy: required attributes, trust-level floor, credential format (W3C VC SD-JWT or ISO mdoc), validity period, and approval-chain requirements.
The orchestration engine queries the Postgres registry to retrieve and validate the subject's attested attributes, checking against the policy's attribute requirements before proceeding.
For credentials requiring human authorisation, the orchestration engine places the request in an approval queue and awaits a signed approval event before continuing the chain.
The issuance service constructs the credential payload: populates W3C VC claims (or ISO mdoc data elements), sets validity and subject DID, serialises to the target format, and passes the to-be-signed bytes to the HSM-broker.
The HSM-broker calls TrustVault, which performs the signing operation using the appropriate Document Signer Certificate (DSC) private key inside the HSM boundary. The signature bytes are returned; key material never leaves the secure zone.
The status-list service allocates a bit-index in the relevant W3C StatusList2021 bitstring and writes the initial (valid) status entry to the Postgres registry. The credential's credentialStatus reference is resolved to this index.
The TSA service issues an RFC 3161-aligned timestamp token over the signed credential, providing a trusted time-of-issuance anchor. The token is stored in the credential event record in the Postgres audit stream.
The gateway returns the signed credential to the holder. For mdoc credentials the response follows ISO/IEC 18013-5 issuer-signed structure; for W3C VC credentials the response is a JWT or JSON-LD document.
The relying party (verifier) sends an OID4VP authorisation request to the presentation service, specifying the credential types and claims required (a Presentation Definition). For ISO mdoc credentials this aligns with the ISO/IEC 18013-5 DeviceRequest structure.
The holder responds with a Verifiable Presentation (VP token) containing the credential and a proof-of-possession over the nonce. For mdoc, this is a DeviceResponse with DeviceAuth COSE-signed by the device key.
The verification service validates the credential signature chain against the trusted issuer certificate (DSC → IACA root, resolved via TrustVault), verifies the holder binding proof-of-possession, and checks the presentation nonce to prevent replay.
The verification service fetches the W3C StatusList2021 bitstring from the status-list service (or its cached copy), resolves the credential's bit-index, and confirms the credential has not been revoked or suspended.
The orchestration engine evaluates the verification policy: attribute-disclosure minimisation rules, permitted verifier identities, and data-purpose constraints aligned with GDPR accountability requirements.
A signed verification result is returned to the relying party. The full verification event — credential identifier, timestamp, revocation check result, policy outcome — is written to the Postgres audit stream and timestamped by the TSA service.
Colour-coded pipeline — the end-to-end path of an operation
TrustVault & PKI integration
proConsul orchestrates credential operations but delegates every cryptographic action to TrustVault via the HSM-broker. The division is strict: the orchestration layer decides what to sign and when; TrustVault decides how, using keys that never leave HSM custody. This architecture means a compromise of the orchestration layer does not expose private key material.
The issuance service passes the credential's to-be-signed byte sequence to the HSM-broker with a key reference (e.g. the active mDL DSC key handle). The broker calls TrustVault, which executes the ECDSA or RSA-PSS signing operation inside the HSM boundary and returns only the signature. The issuance service embeds the signature in the credential structure — it never sees the private key. The orchestration engine is not in this signing path at all; it only called the issuance service.
TrustVault manages the full PKI trust chain — IACA root CA, intermediate CAs, and Document Signer Certificates (DSCs) used for mDL and other mdoc credential signing, engineered to align with ISO/IEC 18013-5 IACA profile requirements. Certificate lifecycle events — issuance, renewal, revocation — are initiated by the orchestration engine via the HSM-broker and reflected in the status-list and CRL/OCSP infrastructure. The verification service resolves issuer certificates from TrustVault when validating credential signature chains, so the trust anchor is always current without requiring static certificate bundles in the verifier.
Part 3 · Services to vault mounts — secrets and PKI integration
Security architecture
Security properties are structural, not bolted on. The network-zone separation, the HSM-broker delegation model, and the stateless orchestration design each eliminate entire classes of risk — a laterally-moved attacker in the orchestration zone cannot sign credentials without crossing into the secure zone through the single, audited HSM-broker channel.
Three network zones (DMZ, internal service zone, secure zone) enforce that no single breach yields both code execution and key access. mTLS between services prevents service impersonation inside the internal zone. All credentials are encrypted at rest in the Postgres registries. The Vault cluster provides envelope encryption for registry records and manages TLS certificate rotation for inter-service channels. Audit event records are append-only and timestamped by the TSA service, providing tamper-evident evidence for forensic and compliance use.
STRIDE analysis is applied at each architectural boundary. The critical risk boundary is the channel between the HSM-broker and TrustVault: tampering with a signing request here could result in a fraudulently-issued credential. Controls at this boundary include request signing, HSM-side audit logging, and key-usage policy enforcement (a DSC key can only sign credential payloads that match its registered credential type). Repudiation is addressed by TSA timestamps on every issuance and verification event; denial-of-service is addressed by circuit breakers and rate limits at the gateway. The stateless orchestration design eliminates persistent-session hijacking as an attack surface.
Explore integration patterns, deployment models and implementation details with our technical team.