Documentation for credential issuer

docs/wallet-issuer/01-overview.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+
+![](../../static/img/diagrams/overview-issuer.png)
+

docs/wallet-issuer/02-essentials/01-connect-with-as.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+---
+
+# Connect with an Authorization Server
+
+Define the required parameters to integrate with an external Authorization Server.
+
+## Overview
+
+The Wallet Issuer component operates as a [OpenID for Verifiable Credentials Issuer](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). To ensure that only authorized users or entities can request and receive verifiable credentials, the Issuer must outsource identity verification and token issuance to an external [OAuth Authorization Server (RFC6749)](https://datatracker.ietf.org/doc/html/rfc6749).
+
+This integration ensures a secure handshake where the Wallet Issuer can:
+
+- Validate incoming requests by communicating with the Authorization Server's introspection endpoint.
+
+- Verify scopes to ensure the requester has the necessary permissions for specific credential types.
+
+The following configuration steps outline how to establish this trust relationship using environment variables.
+
+## Specify the URL of the Authorization Server
+
+The first step to connect the Wallet Issuer component with an Authorization Server
+is by defining the `AUTHORIZATION_SERVER_URL` environment variable variable. This variable is
+mandatory since the Wallet Issuer component requires an externat Authorization Server component
+to be operating.
+
+## Scope alignment with the Authorization Server
+
+In order for the Wallet Issuer component to interoperate with an Authorization Server, it is required
+that both components agree on common scope names.
+
+## Authenticate with the Introspection Endpoint of the Authorization Server
+
+
+The current implementation of the Wallet Issuer component, implements the `client_secret_basic` introspection endpoint authentication mechanism as means of authentication with the [Token Introspection Endpoint(RFC7662)](https://datatracker.ietf.org/doc/html/rfc7662) of an Authorization Server component.
+
+The configurations requires that the `INTROSPECTION_ENDPOINT_BASIC_AUTH_HEADER` environment variable is set.
+
+The value of the `INTROSPECTION_ENDPOINT_BASIC_AUTH_HEADER` environment variable should be the base64-encoded credentials.
+
+Example: `aXNzdWVyOnNlY3JldA==` which decodes to `issuer:secret`.

docs/wallet-issuer/02-essentials/02-connect-data-provider.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+# Connect with a Data Provider
+
+The current Wallet Issuer implementation provides the capability to define a communication channel with a Data Provider to retrieve user's information in order to sign the credential.
+
+Currently, the dataset is provided internally without communication with an external Data Provider.
+
+The configuration file `config.accountFinder.ts` can be utilized to define the dataset retrieval method for any scope.

docs/wallet-issuer/02-essentials/03-introduce-new-vc-type.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 3
+---
+
+# Introduce a custom VC Type
+
+The Wallet Issuer service currently supports EUDI PID ('dc+sd-jwt' and
+'mso_mdoc' formats), Diploma, EHIC and Power of Representation
+credential types. To support a different VC type, the following files need
+to be configured:
+
+- config/supportedCredentialConfiguration.ts
+- config/accountFinder.ts
+
+The file `config/supportedCredentialConfiguration.ts`
+needs to be extended by defining a new Supported Credential Configuration Metadata entry
+based on the schema defined in the section [12.2 Credential IssuerMetadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata). It is recommended that all credential configurations are assigned a unique `scope` value for simplicity purposes.
+
+To define the way that claims will retrieved from an Data Provide depening on the requested `scope` the
+the file `config/accountFinder.ts` needs to be extended to support the new scope value.
+
+Note that the new `scope` value must be a scope that is aggreed with the Authorization Server that the Wallet Issuer service is connected with.
+
+## New credential format support
+
+To support a completely new credential format, aside from the above changes,
+the signCredentials(.) function from the `lib/issuer` module needs to be extended to supported
+that additional credential format.

docs/wallet-issuer/02-essentials/04-key-mgmt.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Key Management
+
+The keys required for the Wallet Issuer service to operate are the following:
+
+Credential Issuer's Signing Key:
+
+- keys/pem.key
+- keys/ca.crt
+- keys/pem.crt
+
+
+Credential Issuer's HS512 shared secret for `c_nonce` generation:
+
+- keys/secret.hs512.b64
+
+
+Encryption keypair for the Credential Request/Response encryption operations:
+
+- keys/private.enc.ecdh.jwk
+- keys/public.enc.ecdh.jwk
+
+
+
+All the above files can be generated by using the `yarn setup` command in `wwwallet` repository.

docs/wallet-issuer/02-essentials/05-add-trust-anchors.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 5
+---
+
+# Add Trusted Certificates
+
+
+The current Wallet Issuer implementation currently requires importing
+the trust anchors to the filesystem under the `certs` directory. All files
+need to have the extension `.pem`.
+
+The `yarn setup` command in `wwwallet` repository initializes also this
+directory with a trusted root certificate.

docs/wallet-issuer/02-essentials/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Essentials",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Describing the architecture and API of the Wallet Issuer service"
+  }
+}

docs/wallet-issuer/03-views/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Views",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Describing the architecture and configuration of views"
+  }
+}

docs/wallet-issuer/04-lib-issuer/01-essentials/01-instantiate-IssuerOpenID4VCI.md

@@ -0,0 +1,48 @@
+---
+position: 1
+---
+
+# Creating an IssuerOpenID4VCI object
+
+
+```ts
+
+
+
+// the Credential Request Store can be changed to a Database or Redis, by providing your
+// own implementation of the GenericStore interface
+const credentialRequestStore = new MemoryStore<string, CredentialRequestWithClaims>(10000);
+
+
+export const credentialRequestHelper = createCredentialRequestHelper(credentialRequestStore);
+
+export const issuer = createIssuerOpenID4VCI(config.url + '/openid', {
+    stateStore: new MemoryStore<string, State>(10000), // can be changed to other store
+    credentialOfferStore: new MemoryStore <string, CredentialOffer>(100000), // can be chaned to other store
+	clockTolerance: config.clockTolerance,
+	findAccount: findAccount,
+	credentialRequestHelper,
+	proofTypesSupported: [ProofTypesSupported.JWT, ProofTypesSupported.ATTESTATION],
+	requireKeyBindingInCredentialConfigurationIds: [],
+	getAllTrustedPemCertificates: localTrustedCertsManager.getAllPemCertificates,
+	secret: secret,
+	authorizationServerUrl: config.authorizationServerUrl,
+	credentialSigner: signer,
+	x5c: [pemToBase64(fs.readFileSync(path.join(__dirname, '../../../keys/pem.crt'), 'utf-8'))],
+	introspectionEndpointBasicAuthString: config.introspectionEndpointBasicAuthString,
+	credentialRequestEncryption: {
+		encryptionRequired: false,
+		keypair: {
+			alg: config.jweEncryptionAlg,
+			publicKeyJwk: publicKeyJwk,
+			privateKeyJwk: privateKeyJwk,
+		},
+	},
+	display: config.display,
+	vctDocumentProvider: vctDocumentProvider,
+});
+
+Object.entries(supportedCredentialConfigurations).map(([credentialConfigurationId, conf]) => issuer.registerSupportedCredentialConfiguration(credentialConfigurationId, conf, disclosureFrameMap[credentialConfigurationId]));
+
+```
+

docs/wallet-issuer/04-lib-issuer/01-essentials/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Essentials",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Describing the architecture and API of the Wallet Issuer service"
+  }
+}

docs/wallet-issuer/04-lib-issuer/03-CredentialSigner.md

@@ -0,0 +1,16 @@
+---
+---
+
+# interface CredentialSigner
+
+
+This interface serves as a customizable contract that allows
+library users to implement their own credential signing logic based on
+specific architectural needs. It provides a standardized structure for
+issuing SD-JWT VCs and ISO mDL MSO MDoc credentials while offering
+full control over key management and salt generation. By implementing
+this interface, developers can flexibly define how signing occurs depending
+on whether the issuer's keys are stored locally, in a HSM, or via a cloud provider.
+
+The Wallet Issuer service implements this interface in the `src/signer.ts` file.
+

docs/wallet-issuer/04-lib-issuer/05-ClaimsFuture.md

@@ -0,0 +1,17 @@
+---
+---
+
+# type ClaimsFuture
+
+
+```ts
+export type ClaimsFuture<Claims> = PendingClaims | RejectedClaims | ResolvedClaims<Claims>;
+```
+
+Acts as a Value Wrapper that encapsulates both the claim data
+and its current lifecycle state for safe propagation across the system.
+This type enables functions to remain "context-aware" by requiring explicit
+handling of pending and rejected states before accessing the payload. It models
+Asynchronous State Transitions for claims, explicitly handling pending,
+rejected, and resolved outcomes. This was required in order to support
+deferred credential issuance scenarios.

docs/wallet-issuer/04-lib-issuer/06-Account.md

@@ -0,0 +1,20 @@
+---
+---
+
+# Account
+
+## type FindAccount function
+
+
+The FindAccount type is defined on lib/issues/Account directory
+
+
+The purpose of this type is to define functions that will be used for
+retrieving the claims of an Account for a specific set of scopes which
+are allowed. The main identifier used for each account is the accountId
+which is synonymous with the 'sub' claim. Additionally, the `ctx` parameter
+includes the `credentialRequestHelper` which is utilized for managing the
+pending ClaimFutures in cases where the credential is not ready to be sent
+and therefore an asynchronous proceedure needs to follow.
+
+[Example implementation of the FindAccount type](https://github.com/wwWallet/wallet-issuer/blob/babd3d3aac351d3b5e179100626cda20766b608f/config/accountFinder.ts)

docs/wallet-issuer/04-lib-issuer/07-DataModels.md

@@ -0,0 +1,22 @@
+---
+---
+
+# Data Models
+
+## State Data Model
+
+The `State` data model is the main model used for the temporary storage
+of credential issuance flow state.
+
+- id: string;
+- sub: unique identifier of the associated account
+- clientId: client_id value received from the wallet
+- attestedKeys: An array of JWK objects. These keys will be used
+  to bind each verifiable credential with a unique public key provided
+  by the wallet.
+- credentialConfigurationId: string | null
+- transactionId: Each credential request is binded to a single transaction id.
+  This value is also used as an identifier for the credential request by
+  the OpenID4VCI 1.0
+- scope: Scopes to be released to the wallet during credential issuance
+- iso_datetime_created: The timestamp in ISO string format, in which the state was created.

docs/wallet-issuer/04-lib-issuer/08-signCredentials.md

@@ -0,0 +1,22 @@
+---
+---
+
+# function signCredentials()
+
+The `signCredentials()` function is responsible for handling
+the signing process of each credentail format. This function passes
+all the required parameters to the credential signer instance to
+sign a credential.
+
+
+```ts
+function signCredentials(
+	credentialConfigurationId: string,
+	metadata: OpenidCredentialIssuerMetadata,
+	claims: GenericClaims,
+	attestedKeys: JWK[],
+	disclosureFrameMap: Map<string, Record<string, unknown>>,
+	requestOpts: PlainIssueCredentialRequestOptions,
+	createOpts: CredentialIssuerCreateOptions
+): Promise<Result<string[], CredentialRequestError>>
+```

docs/wallet-issuer/04-lib-issuer/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Lib Issuer",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Describing the architecture and API of the lib/issuer"
+  }
+}

docs/wallet-issuer/05-deploy.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 5
+---
+
+# Deploy using Docker
+
+The Wallet Issuer service currently does not depend on
+external services for simplicity reasons however it has been designed
+to allow different types of stores (memory cache or database for
+persistent storage). By default, the Credential Issuer services uses
+the memory store.
+
+
+The container should be able to start with the following command:
+
+```
+docker run -p 8003:8003 \
+    -e 'SERVICE_URL=https://qa-issuer.wwwallet.org' \
+    -e 'SERVICE_PORT=8003' \
+    -e 'AUTHORIZATION_SERVER_URL=https://qa-issuer.wwwallet.org/as' \
+    -e 'INTROSPECTION_ENDPOINT_BASIC_AUTH_HEADER=dGVzdDoxMjMxMzMxMTIzMjIxMw==' \
+    -e 'VCT_REGISTRY_URL=https://myvct-registry/type-metadata' \
+    -v '$PWD/wallet-issuer/dataset/:/home/node/app/dataset/' \
+    -v '$PWD/wallet-issuer/keys/:/home/node/app/keys/' \
+    -v '$PWD/wallet-issuer/certs/:/home/node/app/certs/' \
+    wwwallet/wallet-issuer:latest
+```
+

docs/wallet-issuer/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Wallet Issuer",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Describing the architecture and API of the Wallet Issuer service"
+  }
+}