SSI Architecture

Zentity's SSI architecture makes verification artifacts portable: credentials issued from ZK proofs and signed claims can be held in external wallets and presented to third-party verifiers without Zentity involvement. This document maps the credential lifecycle from issuance through selective disclosure to revocation, with the holder's control surface as the axis of variation.

Executive Summary

Zentity issues portable verifiable credentials following OpenID standards while preserving the existing privacy model: no server-decryptable PII, passkey-secured secrets, and ZK/FHE-derived claims.

• OIDC4VCI: Credential issuance with pre-authorized code flow; SD-JWT VC format.
• OIDC4VP: Presentation requests from verifiers; Presentation Exchange (PEX) support.
• Derived claims only: Credentials contain verification flags, not raw PII.
• Holder binding: EdDSA proof JWT ties credentials to holder's cryptographic key.
• Selective disclosure: SD-JWT format lets users reveal only the claims needed.
• Pairwise identifiers: Different sub per relying party to prevent correlation.

This model enables external wallets to hold credentials and third-party verifiers to request presentations without Zentity involvement.

---

SSI Trust Model

SSI operates through three roles forming a "trust triangle":

Issuer (Zentity)

• Verifies user identity through document OCR, liveness detection, and face matching
• Issues SD-JWT verifiable credentials with derived claims only
• Signs credentials with issuer keys
• Never stores raw PII, only cryptographic artifacts

Holder (User)

• Controls cryptographic keys via passkey, OPAQUE password, or Web3 wallet
• Stores credentials in wallet (internal or external)
• Chooses which claims to reveal during presentation
• Authorizes all disclosures explicitly

Note on wallets: The term "wallet" can refer to two distinct concepts:

1. Credential wallet: stores and presents verifiable credentials (SSI context)
2. Web3 wallet: signs transactions and can be used for authentication (EIP-712 signatures)

These are not mutually exclusive; a Web3 wallet user can also hold credentials in a credential wallet.

Verifier (Relying Party)

• Requests credential presentations via OIDC4VP
• Validates holder binding and issuer signatures
• Verifies claims without contacting the issuer
• Cannot correlate users across presentations (pairwise identifiers)

Flow overview

---

Credential Issuance (OIDC4VCI)

Protocol

OpenID for Verifiable Credential Issuance

Endpoints

Pre-authorized code flow

1. User completes identity verification (document + liveness + face match).
2. Server creates credential offer with pre-authorized code.
3. Wallet scans QR or follows deep link.
4. Wallet exchanges code for access token.
5. Wallet requests credential with holder binding proof.
6. Server validates proof, generates SD-JWT VC.

Credential type

• Identifier: zentity_identity
• VCT: urn:zentity:credential:identity
• Format: dc+sd-jwt (SD-JWT VC with selective disclosure)

---

Credential Presentation (OIDC4VP)

Protocol

OpenID for Verifiable Presentations

Endpoints

Flow

1. Verifier creates presentation request with required claims (PEX format).
2. Wallet displays request to user.
3. User selects which claims to reveal (selective disclosure).
4. Wallet creates presentation with holder binding proof.
5. Verifier validates issuer signature, holder binding, and claims.

---

Derived Claims

Legend: ✅ always included, ◐ included if verified, — never included.

Important: Credentials derive claims from existing verification artifacts (ZK proofs, signed claims). No new PII collection is required for credential issuance.

Compliance derivation: verification_level and all boolean check claims are computed at request time by a pure function with no DB access, taking ZK proofs, signed claims, and flags as input. There are no mutable boolean columns; values cannot be flipped by DB manipulation. See Architecture: Compliance Derivation Engine for the full check matrix.

---

Holder Binding

Credentials are cryptographically bound to the holder's key to prevent theft and misuse.

Mechanism

• JWK Thumbprint Confirmation (cnf.jkt): Credential includes thumbprint of holder's public key.
• Proof JWT: Holder signs a proof demonstrating possession of private key.
• EdDSA (Ed25519): Efficient, secure binding signatures.

Key custody options

---

Privacy Preservation

Pairwise Subject Identifiers

Each relying party receives a unique opaque sub derived from the user ID, client ID, and a server secret, preventing cross-RP correlation. See OAuth Integrations for the derivation mechanism and sector identifier rules.

Selective disclosure (SD-JWT)

Users reveal only the claims needed. The holder controls which disclosure keys are included in the presentation.

ZK proofs for predicates

For binary eligibility checks, ZK proofs reveal nothing beyond the answer:

---

Relationship to Other Components

How VCs connect to existing architecture

What VCs do NOT replace

• ZK proofs (VCs package results, not replace the underlying proofs)
• Passkey-sealed profile (raw PII stays in vault, not in credentials)
• FHE ciphertexts (encrypted computation is separate from credential presentation)

---

Standards Compliance

---

Security Considerations

---

Related Documentation

• Attestation & Privacy Architecture for data classification and storage boundaries
• Cryptographic Pillars for ZK, FHE, commitments, key custody
• OAuth Integrations for OIDC4VCI/VP endpoint details