@sphereon/oid4vci-client 0.16.1-next.4 → 0.16.1-next.402

package/lib/CredentialRequestClient.ts

@@ -2,8 +2,10 @@ import { createDPoP, CreateDPoPClientOpts, getCreateDPoPOptions } from '@sphereo
 import {
   acquireDeferredCredential,
   CredentialRequestV1_0_13,
+  CredentialRequestWithoutProofV1_0_13,
   CredentialResponse,
   DPoPResponseParams,
+  ExperimentalSubjectIssuance,
   getCredentialRequestForVersion,
   getUniformFormat,
   isDeferredCredentialResponse,
@@ -16,7 +18,6 @@ import {
   UniformCredentialRequest,
   URL_NOT_VALID,
 } from '@sphereon/oid4vci-common';
-import { ExperimentalSubjectIssuance } from '@sphereon/oid4vci-common/dist/experimental/holder-vci';
 import { CredentialFormat } from '@sphereon/ssi-types';
 import Debug from 'debug';
 
@@ -40,10 +41,20 @@ export interface CredentialRequestOpts {
   token: string;
   version: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 }
 
-export async function buildProof<DIDDoc>(
-  proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession,
+export type CreateCredentialRequestOpts = {
+  credentialIdentifier?: string;
+  credentialTypes?: string | string[];
+  context?: string[];
+  format?: CredentialFormat | OID4VCICredentialFormat;
+  subjectIssuance?: ExperimentalSubjectIssuance;
+  version: OpenId4VCIVersion;
+};
+
+export async function buildProof(
+  proofInput: ProofOfPossessionBuilder | ProofOfPossession,
   opts: {
     version: OpenId4VCIVersion;
     cNonce?: string;
@@ -85,8 +96,35 @@ export class CredentialRequestClient {
     this._credentialRequestOpts = { ...builder };
   }
 
-  public async acquireCredentialsUsingProof<DIDDoc>(opts: {
-    proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
+  /**
+   * Typically you should not use this method, as it omits a proof from the request.
+   * There are certain issuers that in specific circumstances can do without this proof, because they have other means of user binding
+   * like using DPoP together with an authorization code flow. These are however rare, so you should be using the acquireCredentialsUsingProof normally
+   * @param opts
+   */
+  public async acquireCredentialsWithoutProof(opts: {
+    credentialIdentifier?: string;
+    credentialTypes?: string | string[];
+    context?: string[];
+    format?: CredentialFormat | OID4VCICredentialFormat;
+    subjectIssuance?: ExperimentalSubjectIssuance;
+    createDPoPOpts?: CreateDPoPClientOpts;
+  }): Promise<OpenIDResponse<CredentialResponse, DPoPResponseParams> & { access_token: string }> {
+    const { credentialIdentifier, credentialTypes, format, context, subjectIssuance } = opts;
+
+    const request = await this.createCredentialRequestWithoutProof({
+      credentialTypes,
+      context,
+      format,
+      version: this.version(),
+      credentialIdentifier,
+      subjectIssuance,
+    });
+    return await this.acquireCredentialsUsingRequestWithoutProof(request, opts.createDPoPOpts);
+  }
+
+  public async acquireCredentialsUsingProof(opts: {
+    proofInput: ProofOfPossessionBuilder | ProofOfPossession;
     credentialIdentifier?: string;
     credentialTypes?: string | string[];
     context?: string[];
@@ -108,9 +146,23 @@ export class CredentialRequestClient {
     return await this.acquireCredentialsUsingRequest(request, opts.createDPoPOpts);
   }
 
+  public async acquireCredentialsUsingRequestWithoutProof(
+    uniformRequest: UniformCredentialRequest,
+    createDPoPOpts?: CreateDPoPClientOpts,
+  ): Promise<OpenIDResponse<CredentialResponse, DPoPResponseParams> & { access_token: string }> {
+    return await this.acquireCredentialsUsingRequestImpl(uniformRequest, createDPoPOpts);
+  }
+
   public async acquireCredentialsUsingRequest(
     uniformRequest: UniformCredentialRequest,
     createDPoPOpts?: CreateDPoPClientOpts,
+  ): Promise<OpenIDResponse<CredentialResponse, DPoPResponseParams> & { access_token: string }> {
+    return await this.acquireCredentialsUsingRequestImpl(uniformRequest, createDPoPOpts);
+  }
+
+  private async acquireCredentialsUsingRequestImpl(
+    uniformRequest: UniformCredentialRequest & { proof?: ProofOfPossession },
+    createDPoPOpts?: CreateDPoPClientOpts,
   ): Promise<OpenIDResponse<CredentialResponse, DPoPResponseParams> & { access_token: string }> {
     if (this.version() < OpenId4VCIVersion.VER_1_0_13) {
       throw new Error('Versions below v1.0.13 (draft 13) are not supported by the V13 credential request client.');
@@ -194,24 +246,35 @@ export class CredentialRequestClient {
     });
   }
 
-  public async createCredentialRequest<DIDDoc>(opts: {
-    proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
-    credentialIdentifier?: string;
-    credentialTypes?: string | string[];
-    context?: string[];
-    format?: CredentialFormat | OID4VCICredentialFormat;
-    subjectIssuance?: ExperimentalSubjectIssuance;
-    version: OpenId4VCIVersion;
-  }): Promise<CredentialRequestV1_0_13> {
+  public async createCredentialRequestWithoutProof(opts: CreateCredentialRequestOpts): Promise<CredentialRequestWithoutProofV1_0_13> {
+    return await this.createCredentialRequestImpl(opts);
+  }
+
+  public async createCredentialRequest(
+    opts: CreateCredentialRequestOpts & {
+      proofInput: ProofOfPossessionBuilder | ProofOfPossession;
+    },
+  ): Promise<CredentialRequestV1_0_13> {
+    return await this.createCredentialRequestImpl(opts);
+  }
+
+  private async createCredentialRequestImpl(
+    opts: CreateCredentialRequestOpts & {
+      proofInput?: ProofOfPossessionBuilder | ProofOfPossession;
+    },
+  ): Promise<CredentialRequestV1_0_13> {
     const { proofInput, credentialIdentifier: credential_identifier } = opts;
-    const proof = await buildProof(proofInput, opts);
+    let proof: ProofOfPossession | undefined = undefined;
+    if (proofInput) {
+      proof = await buildProof(proofInput, opts);
+    }
     if (credential_identifier) {
       if (opts.format || opts.credentialTypes || opts.context) {
         throw Error(`You cannot mix credential_identifier with format, credential types and/or context`);
       }
       return {
         credential_identifier,
-        proof,
+        ...(proof && { proof }),
       };
     }
     const formatSelection = opts.format ?? this.credentialRequestOpts.format;
@@ -231,6 +294,7 @@ export class CredentialRequestClient {
     if (types.length === 0) {
       throw Error(`Credential type(s) need to be provided`);
     }
+    const issuer_state = this.credentialRequestOpts.issuerState;
 
     // TODO: we should move format specific logic
     if (format === 'jwt_vc_json' || format === 'jwt_vc') {
@@ -239,7 +303,8 @@ export class CredentialRequestClient {
           type: types,
         },
         format,
-        proof,
+        ...(issuer_state && { issuer_state }),
+        ...(proof && { proof }),
         ...opts.subjectIssuance,
       };
     } else if (format === 'jwt_vc_json-ld' || format === 'ldp_vc') {
@@ -249,7 +314,8 @@ export class CredentialRequestClient {
 
       return {
         format,
-        proof,
+        ...(issuer_state && { issuer_state }),
+        ...(proof && { proof }),
         ...opts.subjectIssuance,
 
         credential_definition: {
@@ -261,16 +327,27 @@ export class CredentialRequestClient {
       if (types.length > 1) {
         throw Error(`Only a single credential type is supported for ${format}`);
       }
-      // fixme: this isn't up to the CredentialRequest that we see in the version v1_0_13
       return {
         format,
-        proof,
+        ...(issuer_state && { issuer_state }),
+        ...(proof && { proof }),
         vct: types[0],
         ...opts.subjectIssuance,
       };
+    } else if (format === 'mso_mdoc') {
+      if (types.length > 1) {
+        throw Error(`Only a single credential type is supported for ${format}`);
+      }
+      return {
+        format,
+        ...(issuer_state && { issuer_state }),
+        ...(proof && { proof }),
+        doctype: types[0],
+        ...opts.subjectIssuance,
+      };
     }
 
-    throw new Error(`Unsupported format: ${format}`);
+    throw new Error(`Unsupported credential format: ${format}`);
   }
 
   private version(): OpenId4VCIVersion {

package/lib/CredentialRequestClientBuilder.ts

@@ -168,6 +168,10 @@ export class CredentialRequestClientBuilder {
     return this;
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this._builder.withIssuerState(issuerState);
+    return this;
+  }
   public withCredentialType(credentialTypes: string | string[]): this {
     this._builder.withCredentialType(credentialTypes);
     return this;

package/lib/CredentialRequestClientBuilderV1_0_11.ts

@@ -28,6 +28,7 @@ export class CredentialRequestClientBuilderV1_0_11 {
   token?: string;
   version?: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 
   public static fromCredentialIssuer({
     credentialIssuer,
@@ -98,6 +99,11 @@ export class CredentialRequestClientBuilderV1_0_11 {
     });
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this.issuerState = issuerState;
+    return this;
+  }
+
   public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): this {
     this.credentialEndpoint = metadata.credential_endpoint;
     return this;

package/lib/CredentialRequestClientBuilderV1_0_13.ts

@@ -27,6 +27,7 @@ export class CredentialRequestClientBuilderV1_0_13 {
   token?: string;
   version?: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 
   public static fromCredentialIssuer({
     credentialIssuer,
@@ -86,6 +87,7 @@ export class CredentialRequestClientBuilderV1_0_13 {
     if (ids.length && ids.length === 1) {
       builder.withCredentialIdentifier(ids[0]);
     }
+
     return builder;
   }
 
@@ -96,11 +98,13 @@ export class CredentialRequestClientBuilderV1_0_13 {
     credentialOffer: CredentialOfferRequestWithBaseUrl;
     metadata?: EndpointMetadata;
   }): CredentialRequestClientBuilderV1_0_13 {
-    return CredentialRequestClientBuilderV1_0_13.fromCredentialOfferRequest({
+    const builder = CredentialRequestClientBuilderV1_0_13.fromCredentialOfferRequest({
       request: credentialOffer,
       metadata,
       version: credentialOffer.version,
     });
+
+    return builder;
   }
 
   public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadataV1_0_13): this {
@@ -113,6 +117,11 @@ export class CredentialRequestClientBuilderV1_0_13 {
     return this;
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this.issuerState = issuerState;
+    return this;
+  }
+
   public withDeferredCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadataV1_0_13): this {
     this.deferredCredentialEndpoint = metadata.deferred_credential_endpoint;
     return this;

package/lib/CredentialRequestClientV1_0_11.ts

@@ -62,8 +62,8 @@ export class CredentialRequestClientV1_0_11 {
     this._credentialRequestOpts = { ...builder };
   }
 
-  public async acquireCredentialsUsingProof<DIDDoc>(opts: {
-    proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
+  public async acquireCredentialsUsingProof(opts: {
+    proofInput: ProofOfPossessionBuilder | ProofOfPossession;
     credentialTypes?: string | string[];
     context?: string[];
     format?: CredentialFormat | OID4VCICredentialFormat;
@@ -153,8 +153,8 @@ export class CredentialRequestClientV1_0_11 {
     });
   }
 
-  public async createCredentialRequest<DIDDoc>(opts: {
-    proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
+  public async createCredentialRequest(opts: {
+    proofInput: ProofOfPossessionBuilder | ProofOfPossession;
     credentialTypes?: string | string[];
     context?: string[];
     format?: CredentialFormat | OID4VCICredentialFormat;
@@ -215,6 +215,16 @@ export class CredentialRequestClientV1_0_11 {
         proof,
         vct: types[0],
       };
+    } else if (format === 'mso_mdoc') {
+      if (types.length > 1) {
+        throw Error(`Only a single credential type is supported for ${format}`);
+      }
+
+      return {
+        format,
+        proof,
+        doctype: types[0],
+      };
     }
 
     throw new Error(`Unsupported format: ${format}`);

package/lib/MetadataClient.ts

@@ -19,7 +19,7 @@ import Debug from 'debug';
 
 import { MetadataClientV1_0_11 } from './MetadataClientV1_0_11';
 import { MetadataClientV1_0_13 } from './MetadataClientV1_0_13';
-import { retrieveWellknown } from './functions/OpenIDUtils';
+import { retrieveWellknown } from './functions';
 
 const debug = Debug('sphereon:oid4vci:metadata');
 
@@ -70,6 +70,7 @@ export class MetadataClient {
     let credential_endpoint: string | undefined;
     let deferred_credential_endpoint: string | undefined;
     let authorization_endpoint: string | undefined;
+    let authorization_challenge_endpoint: string | undefined;
     let authorizationServerType: AuthorizationServerType = 'OID4VCI';
     let authorization_servers: string[] | undefined = [issuer];
     let authorization_server: string | undefined = undefined;
@@ -84,6 +85,7 @@ export class MetadataClient {
       if (credentialIssuerMetadata.token_endpoint) {
         token_endpoint = credentialIssuerMetadata.token_endpoint;
       }
+      authorization_challenge_endpoint = credentialIssuerMetadata.authorization_challenge_endpoint;
       if (credentialIssuerMetadata.authorization_servers) {
         authorization_servers = credentialIssuerMetadata.authorization_servers as string[];
       } else if (credentialIssuerMetadata.authorization_server) {
@@ -130,8 +132,14 @@ export class MetadataClient {
         );
       }
       authorization_endpoint = authMetadata.authorization_endpoint;
+      if (authorization_challenge_endpoint && authMetadata.authorization_challenge_endpoint !== authorization_challenge_endpoint) {
+        throw Error(
+          `Credential issuer has a different authorization_challenge_endpoint (${authorization_challenge_endpoint}) from the Authorization Server (${authMetadata.authorization_challenge_endpoint})`,
+        );
+      }
+      authorization_challenge_endpoint = authMetadata.authorization_challenge_endpoint;
       if (!authMetadata.token_endpoint) {
-        throw Error(`Authorization Sever ${authorization_servers} did not provide a token_endpoint`);
+        throw Error(`Authorization Server ${authorization_servers} did not provide a token_endpoint`);
       } else if (token_endpoint && authMetadata.token_endpoint !== token_endpoint) {
         throw Error(
           `Credential issuer has a different token_endpoint (${token_endpoint}) from the Authorization Server (${authMetadata.token_endpoint})`,
@@ -185,6 +193,7 @@ export class MetadataClient {
         : (authMetadata as CredentialIssuerMetadataV1_0_13);
     }
     debug(`Issuer ${issuer} token endpoint ${token_endpoint}, credential endpoint ${credential_endpoint}`);
+
     return {
       issuer,
       token_endpoint,
@@ -192,6 +201,7 @@ export class MetadataClient {
       deferred_credential_endpoint,
       ...(authorization_server ? { authorization_server } : { authorization_servers: authorization_servers }),
       authorization_endpoint,
+      authorization_challenge_endpoint,
       authorizationServerType,
       credentialIssuerMetadata: authorization_server
         ? (credentialIssuerMetadata as IssuerMetadataV1_0_08 & Partial<AuthorizationServerMetadata>)
@@ -204,6 +214,7 @@ export class MetadataClient {
    * Retrieve only the OID4VCI metadata for the issuer. So no OIDC/OAuth2 metadata
    *
    * @param issuerHost The issuer hostname
+   * @param opts
    */
   public static async retrieveOpenID4VCIServerMetadata(
     issuerHost: string,

package/lib/MetadataClientV1_0_11.ts

@@ -50,6 +50,7 @@ export class MetadataClientV1_0_11 {
     let credential_endpoint: string | undefined;
     let deferred_credential_endpoint: string | undefined;
     let authorization_endpoint: string | undefined;
+    let authorization_challenge_endpoint: string | undefined;
     let authorizationServerType: AuthorizationServerType = 'OID4VCI';
     let authorization_server: string = issuer;
     const oid4vciResponse = await MetadataClientV1_0_11.retrieveOpenID4VCIServerMetadata(issuer, { errorOnNotFound: false }); // We will handle errors later, given we will also try other metadata locations
@@ -61,6 +62,7 @@ export class MetadataClientV1_0_11 {
       if (credentialIssuerMetadata.token_endpoint) {
         token_endpoint = credentialIssuerMetadata.token_endpoint;
       }
+      authorization_challenge_endpoint = credentialIssuerMetadata.authorization_challenge_endpoint;
       if (credentialIssuerMetadata.authorization_server) {
         authorization_server = credentialIssuerMetadata.authorization_server;
       }
@@ -105,8 +107,14 @@ export class MetadataClientV1_0_11 {
         );
       }
       authorization_endpoint = authMetadata.authorization_endpoint;
+      if (authorization_challenge_endpoint && authMetadata.authorization_challenge_endpoint !== authorization_challenge_endpoint) {
+        throw Error(
+          `Credential issuer has a different authorization_challenge_endpoint (${authorization_challenge_endpoint}) from the Authorization Server (${authMetadata.authorization_challenge_endpoint})`,
+        );
+      }
+      authorization_challenge_endpoint = authMetadata.authorization_challenge_endpoint;
       if (!authMetadata.token_endpoint) {
-        throw Error(`Authorization Sever ${authorization_server} did not provide a token_endpoint`);
+        throw Error(`Authorization Server ${authorization_server} did not provide a token_endpoint`);
       } else if (token_endpoint && authMetadata.token_endpoint !== token_endpoint) {
         throw Error(
           `Credential issuer has a different token_endpoint (${token_endpoint}) from the Authorization Server (${authMetadata.token_endpoint})`,
@@ -165,6 +173,7 @@ export class MetadataClientV1_0_11 {
       deferred_credential_endpoint,
       authorization_server,
       authorization_endpoint,
+      authorization_challenge_endpoint,
       authorizationServerType,
       credentialIssuerMetadata: credentialIssuerMetadata as unknown as Partial<AuthorizationServerMetadata> & IssuerMetadataV1_0_08,
       authorizationServerMetadata: authMetadata,

package/lib/MetadataClientV1_0_13.ts

@@ -12,7 +12,7 @@ import {
 } from '@sphereon/oid4vci-common';
 import Debug from 'debug';
 
-import { retrieveWellknown } from './functions/OpenIDUtils';
+import { retrieveWellknown } from './functions';
 
 const debug = Debug('sphereon:oid4vci:metadata');
 
@@ -50,6 +50,7 @@ export class MetadataClientV1_0_13 {
     let credential_endpoint: string | undefined;
     let deferred_credential_endpoint: string | undefined;
     let authorization_endpoint: string | undefined;
+    let authorization_challenge_endpoint: string | undefined;
     let authorizationServerType: AuthorizationServerType = 'OID4VCI';
     let authorization_servers: string[] = [issuer];
     const oid4vciResponse = await MetadataClientV1_0_13.retrieveOpenID4VCIServerMetadata(issuer, { errorOnNotFound: false }); // We will handle errors later, given we will also try other metadata locations
@@ -61,6 +62,7 @@ export class MetadataClientV1_0_13 {
       if (credentialIssuerMetadata.token_endpoint) {
         token_endpoint = credentialIssuerMetadata.token_endpoint;
       }
+      authorization_challenge_endpoint = credentialIssuerMetadata.authorization_challenge_endpoint;
       if (credentialIssuerMetadata.authorization_servers) {
         authorization_servers = credentialIssuerMetadata.authorization_servers;
       }
@@ -104,8 +106,14 @@ export class MetadataClientV1_0_13 {
         );
       }
       authorization_endpoint = authMetadata.authorization_endpoint;
+      if (authorization_challenge_endpoint && authMetadata.authorization_challenge_endpoint !== authorization_challenge_endpoint) {
+        throw Error(
+          `Credential issuer has a different authorization_challenge_endpoint (${authorization_challenge_endpoint}) from the Authorization Server (${authMetadata.authorization_challenge_endpoint})`,
+        );
+      }
+      authorization_challenge_endpoint = authMetadata.authorization_challenge_endpoint;
       if (!authMetadata.token_endpoint) {
-        throw Error(`Authorization Sever ${authorization_servers} did not provide a token_endpoint`);
+        throw Error(`Authorization Server ${authorization_servers} did not provide a token_endpoint`);
       } else if (token_endpoint && authMetadata.token_endpoint !== token_endpoint) {
         throw Error(
           `Credential issuer has a different token_endpoint (${token_endpoint}) from the Authorization Server (${authMetadata.token_endpoint})`,
@@ -164,6 +172,7 @@ export class MetadataClientV1_0_13 {
       deferred_credential_endpoint,
       authorization_server: authorization_servers[0],
       authorization_endpoint,
+      authorization_challenge_endpoint,
       authorizationServerType,
       credentialIssuerMetadata: credentialIssuerMetadata,
       authorizationServerMetadata: authMetadata,
@@ -174,6 +183,7 @@ export class MetadataClientV1_0_13 {
    * Retrieve only the OID4VCI metadata for the issuer. So no OIDC/OAuth2 metadata
    *
    * @param issuerHost The issuer hostname
+   * @param opts
    */
   public static async retrieveOpenID4VCIServerMetadata(
     issuerHost: string,