diff --git a/docs/wallet-architecture/02-credential-engine/credential-parsing.md b/docs/wallet-architecture/02-credential-engine/credential-parsing.md new file mode 100644 index 0000000..031d6cf --- /dev/null +++ b/docs/wallet-architecture/02-credential-engine/credential-parsing.md @@ -0,0 +1,54 @@ +# Credential Parsing + +A parser is responsible for recognizing a credential format and transforming it into a common `ParsedCredential` structure. + +The normalized model contains: + +* Credential metadata +* Issuer information +* Validity information +* Signed claims +* Display metadata and warnings + +By exposing a common representation, wallet features can operate independently of the underlying credential format. + +## Parser Selection + +Parsers are registered with the `ParsingEngine`. + +When a credential is parsed, the engine invokes registered parsers until one successfully recognizes and parses the credential. This allows multiple credential formats to coexist within the same wallet while keeping format-specific logic isolated within each parser implementation. + +### Unsupported Formats + +A parser should only handle credentials that belong to its supported format. + +If a parser determines that a credential is not of the expected format, it should return an `UnsupportedFormat` parsing error so that the next registered parser can attempt to process the credential. + +This allows multiple credential formats to coexist within the same `ParsingEngine` while keeping format-specific detection logic isolated within each parser implementation. + +## Credential Display Metadata + +Credential formats often contain only the information required for cryptographic verification. + +To support a richer user experience, parsers may resolve and expose display metadata such as: + +* Human-readable credential names +* Localized labels +* Claim descriptions +* Credential images +* SVG templates and rendering information + +This metadata is surfaced through the normalized credential model and can originate from format-specific metadata registries or external resolution services. + +### Metadata Sources + +Display metadata may originate from different sources depending on the credential format and deployment configuration. + +Common sources include: + +- [OID4VCI Credential Issuer Metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata) +- [SD-JWT VC Type Metadata (VCT Metadata)](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-16.html#name-display-metadata) for the `dc+sd-jwt` credential format. +- Format-specific registries (example, [wwWallet's VCT Registry](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-16.html#name-display-metadata) for `dc+sd-jwt` VCs.) +- Application-defined metadata overrides + +Applications may also provide custom metadata for specific issuers or credential types when display metadata is unavailable from standard sources. \ No newline at end of file diff --git a/docs/wallet-architecture/02-credential-engine/credential-verification.md b/docs/wallet-architecture/02-credential-engine/credential-verification.md new file mode 100644 index 0000000..542b768 --- /dev/null +++ b/docs/wallet-architecture/02-credential-engine/credential-verification.md @@ -0,0 +1,29 @@ +# Credential Verification + +Verification is intentionally separate from parsing. + +A credential may be successfully parsed but still fail verification due to invalid signatures, expired validity periods, missing trust anchors, or format-specific validation failures. + +Verifiers are responsible for: + +* Signature validation +* Issuer trust validation +* Public key resolution +* Validity period checks +* Format-specific security requirements + +The verification result is intentionally format-agnostic, allowing higher-level wallet workflows to treat all credential formats consistently. + +## Public Key Resolution + +Many credential formats require external public keys for signature verification. + +The Credential Engine provides a dedicated public key resolution framework that can be extended to support different trust infrastructures, including: + +* DID Documents +* JWKS endpoints +* OpenID-based metadata +* Trusted registries +* Proprietary trust systems + +Resolvers are independent of credential formats and can be reused across multiple verifiers. \ No newline at end of file diff --git a/docs/wallet-architecture/02-credential-engine/index.md b/docs/wallet-architecture/02-credential-engine/index.md new file mode 100644 index 0000000..157bed9 --- /dev/null +++ b/docs/wallet-architecture/02-credential-engine/index.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 2 +--- +# Credential Engine + +The Credential Engine provides a pluggable framework for supporting multiple Verifiable Credential formats. Each format is integrated through two independent components: + +* **[Credential Parser](./credential-parsing)** — Converts a raw credential into the wallet's normalized credential model. +* **[Credential Verifier](./credential-verification)** — Validates the authenticity and integrity of a credential. + +This separation allows new credential formats to be added without changing the core engine. + +## Currently Supported Formats + +| Name | Format | Parser | Verifier | +| -------------------- | ----------- | --------------- | ----------------- | +| SD-JWT VC | `dc+sd-jwt` | `SDJWTVCParser` | `SDJWTVCVerifier` | +| ISO/IEC 23220-1:2023 | `mso_mdoc` | `MsoMdocParser` | `MsoMdocVerifier` | + +Both parsers and verifiers are registered during credential engine initialization. + +## Extending the Framework + +Supporting a new credential format typically requires: + +1. Implementing a `CredentialParser` +2. Implementing a `CredentialVerifier` +3. Registering the parser with the `ParsingEngine` +4. Exposing the verifier through the application + +Once registered, the new format becomes a first-class participant in credential issuance, storage, display, presentation, and verification workflows without requiring changes to existing format implementations. + +## Design Principles + +The framework is built around a few core principles: + +* **Format Independence** — Wallet features operate on a normalized credential model. +* **Separation of Concerns** — Parsing and verification are independent operations. +* **Pluggability** — New formats can be added through registration. +* **Extensibility** — Metadata and trust infrastructure can be customized. +* **Interoperability** — Multiple credential formats can coexist within the same deployment. + +This approach allows the Credential Engine to support evolving credential standards while providing a consistent integration experience for developers. diff --git a/docs/wallet-architecture/02-credential-formats.md b/docs/wallet-architecture/02-credential-formats.md deleted file mode 100644 index 9e6dae6..0000000 --- a/docs/wallet-architecture/02-credential-formats.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Credential Formats - -### Currently supported formats - -- `vc+sd-jwt` - - -### Credential format extension framework - -The parsing of the credentials is centralized in the useContainer hook where all credential parsers are chained -in a [CredentialParserRegistry](https://github.com/wwWallet/wallet-frontend/blob/master/src/lib/interfaces/ICredentialParser.ts). - -To add a credential parser in the chain, you would need to create an object that implements the ICredentialParser -interface and then include this parser in the rest of the chain by calling the addParser() function. - -Keep in mind that the parsers are called in the same order that they have been added in the CredentialParserRegistry. - -When a specific parser cannot parse the rawCredential, then it should throw an exception so that the next parser -of the chain can handle it. - -We are currently using only one parser for the `vc+sd-jwt` which is defined on the [useContainer hook](https://github.com/wwWallet/wallet-frontend/blob/master/src/hooks/useContainer.ts). - -This framework also gives the flexibility to hard-code specific credential display metadata for a specific issuer and vct, when these are absent from the possible sources. - -The two sources that are currently used for the extraction of the display metadata for the `vc+sd-jwt` format are: - -- OID4VCI Credential Issuer Metadata https://openid.github.io/OpenID4VCI/openid-4-verifiable-credential-issuance-wg-draft.html#name-credential-issuer-metadata-p -- SDJWT VC https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-05.html#name-display-metadata - - -The only exported attributes from a credential parser as defined on the [ICredentialParser](https://github.com/wwWallet/wallet-frontend/blob/master/src/lib/interfaces/ICredentialParser.ts) interface are `credentialFriendlyName`, `credentialImage`(containing the sources for the image) and `beautifiedForm` which is the JSON representation -of the credential.