@sphereon/oid4vci-client 0.8.2-next.6 → 0.8.2-next.88

package/lib/CredentialRequestClient.ts

@@ -1,6 +1,9 @@
 import {
-  CredentialRequestV1_0_08,
+  acquireDeferredCredential,
   CredentialResponse,
+  getCredentialRequestForVersion,
+  getUniformFormat,
+  isDeferredCredentialResponse,
   OID4VCICredentialFormat,
   OpenId4VCIVersion,
   OpenIDResponse,
@@ -18,7 +21,10 @@ import { isValidURL, post } from './functions';
 const debug = Debug('sphereon:oid4vci:credential');
 
 export interface CredentialRequestOpts {
+  deferredCredentialAwait?: boolean;
+  deferredCredentialIntervalInMS?: number;
   credentialEndpoint: string;
+  deferredCredentialEndpoint?: string;
   credentialTypes: string[];
   format?: CredentialFormat | OID4VCICredentialFormat;
   proof: ProofOfPossession;
@@ -26,17 +32,45 @@ export interface CredentialRequestOpts {
   version: OpenId4VCIVersion;
 }
 
+export async function buildProof<DIDDoc>(
+  proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession,
+  opts: {
+    version: OpenId4VCIVersion;
+    cNonce?: string;
+  },
+) {
+  if ('proof_type' in proofInput) {
+    if (opts.cNonce) {
+      throw Error(`Cnonce param is only supported when using a Proof of Posession builder`);
+    }
+    return await ProofOfPossessionBuilder.fromProof(proofInput as ProofOfPossession, opts.version).build();
+  }
+  if (opts.cNonce) {
+    proofInput.withAccessTokenNonce(opts.cNonce);
+  }
+  return await proofInput.build();
+}
+
 export class CredentialRequestClient {
   private readonly _credentialRequestOpts: Partial<CredentialRequestOpts>;
+  private _isDeferred = false;
 
   get credentialRequestOpts(): CredentialRequestOpts {
     return this._credentialRequestOpts as CredentialRequestOpts;
   }
 
+  public isDeferred(): boolean {
+    return this._isDeferred;
+  }
+
   public getCredentialEndpoint(): string {
     return this.credentialRequestOpts.credentialEndpoint;
   }
 
+  public getDeferredCredentialEndpoint(): string | undefined {
+    return this.credentialRequestOpts.deferredCredentialEndpoint;
+  }
+
   public constructor(builder: CredentialRequestClientBuilder) {
     this._credentialRequestOpts = { ...builder };
   }
@@ -44,68 +78,73 @@ export class CredentialRequestClient {
   public async acquireCredentialsUsingProof<DIDDoc>(opts: {
     proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
     credentialTypes?: string | string[];
+    context?: string[];
     format?: CredentialFormat | OID4VCICredentialFormat;
   }): Promise<OpenIDResponse<CredentialResponse>> {
-    const { credentialTypes, proofInput, format } = opts;
+    const { credentialTypes, proofInput, format, context } = opts;
 
-    const request = await this.createCredentialRequest({ proofInput, credentialTypes, format, version: this.version() });
+    const request = await this.createCredentialRequest({ proofInput, credentialTypes, context, format, version: this.version() });
     return await this.acquireCredentialsUsingRequest(request);
   }
 
   public async acquireCredentialsUsingRequest(uniformRequest: UniformCredentialRequest): Promise<OpenIDResponse<CredentialResponse>> {
-    let request: CredentialRequestV1_0_08 | UniformCredentialRequest = uniformRequest;
-    if (!this.isV11OrHigher()) {
-      let format: string = uniformRequest.format;
-      if (format === 'jwt_vc_json') {
-        format = 'jwt_vc';
-      } else if (format === 'jwt_vc_json-ld') {
-        format = 'ldp_vc';
-      }
-
-      request = {
-        format,
-        proof: uniformRequest.proof,
-        type:
-          'types' in uniformRequest
-            ? uniformRequest.types.filter((t) => t !== 'VerifiableCredential')[0]
-            : uniformRequest.credential_definition.types[0],
-      } as CredentialRequestV1_0_08;
-    }
+    const request = getCredentialRequestForVersion(uniformRequest, this.version());
     const credentialEndpoint: string = this.credentialRequestOpts.credentialEndpoint;
     if (!isValidURL(credentialEndpoint)) {
       debug(`Invalid credential endpoint: ${credentialEndpoint}`);
       throw new Error(URL_NOT_VALID);
     }
     debug(`Acquiring credential(s) from: ${credentialEndpoint}`);
+    debug(`request\n: ${JSON.stringify(request, null, 2)}`);
     const requestToken: string = this.credentialRequestOpts.token;
-    const response: OpenIDResponse<CredentialResponse> = await post(credentialEndpoint, JSON.stringify(request), { bearerToken: requestToken });
-    debug(`Credential endpoint ${credentialEndpoint} response:\r\n${response}`);
+    let response: OpenIDResponse<CredentialResponse> = await post(credentialEndpoint, JSON.stringify(request), { bearerToken: requestToken });
+    this._isDeferred = isDeferredCredentialResponse(response);
+    if (this.isDeferred() && this.credentialRequestOpts.deferredCredentialAwait && response.successBody) {
+      response = await this.acquireDeferredCredential(response.successBody, { bearerToken: this.credentialRequestOpts.token });
+    }
+
+    debug(`Credential endpoint ${credentialEndpoint} response:\r\n${JSON.stringify(response, null, 2)}`);
     return response;
   }
 
+  public async acquireDeferredCredential(
+    response: Pick<CredentialResponse, 'transaction_id' | 'acceptance_token' | 'c_nonce'>,
+    opts?: {
+      bearerToken?: string;
+    },
+  ): Promise<OpenIDResponse<CredentialResponse>> {
+    const transactionId = response.transaction_id;
+    const bearerToken = response.acceptance_token ?? opts?.bearerToken;
+    const deferredCredentialEndpoint = this.getDeferredCredentialEndpoint();
+    if (!deferredCredentialEndpoint) {
+      throw Error(`No deferred credential endpoint supplied.`);
+    } else if (!bearerToken) {
+      throw Error(`No bearer token present and refresh for defered endpoint not supported yet`);
+      // todo updated bearer token with new c_nonce
+    }
+    return await acquireDeferredCredential({
+      bearerToken,
+      transactionId,
+      deferredCredentialEndpoint,
+      deferredCredentialAwait: this.credentialRequestOpts.deferredCredentialAwait,
+      deferredCredentialIntervalInMS: this.credentialRequestOpts.deferredCredentialIntervalInMS,
+    });
+  }
+
   public async createCredentialRequest<DIDDoc>(opts: {
     proofInput: ProofOfPossessionBuilder<DIDDoc> | ProofOfPossession;
     credentialTypes?: string | string[];
+    context?: string[];
     format?: CredentialFormat | OID4VCICredentialFormat;
     version: OpenId4VCIVersion;
   }): Promise<UniformCredentialRequest> {
     const { proofInput } = opts;
     const formatSelection = opts.format ?? this.credentialRequestOpts.format;
 
-    let format: OID4VCICredentialFormat = formatSelection as OID4VCICredentialFormat;
-    if (opts.version < OpenId4VCIVersion.VER_1_0_11) {
-      if (formatSelection === 'jwt_vc' || formatSelection === 'jwt') {
-        format = 'jwt_vc_json';
-      } else if (formatSelection === 'ldp_vc' || formatSelection === 'ldp') {
-        format = 'jwt_vc_json-ld';
-      }
-    }
-
-    if (!format) {
+    if (!formatSelection) {
       throw Error(`Format of credential to be issued is missing`);
-    } else if (format !== 'jwt_vc_json-ld' && format !== 'jwt_vc_json' && format !== 'ldp_vc') {
-      throw Error(`Invalid format of credential to be issued: ${format}`);
     }
+    const format = getUniformFormat(formatSelection);
     const typesSelection =
       opts?.credentialTypes && (typeof opts.credentialTypes === 'string' || opts.credentialTypes.length > 0)
         ? opts.credentialTypes
@@ -113,24 +152,56 @@ export class CredentialRequestClient {
     const types = Array.isArray(typesSelection) ? typesSelection : [typesSelection];
     if (types.length === 0) {
       throw Error(`Credential type(s) need to be provided`);
-    } else if (!this.isV11OrHigher() && types.length !== 1) {
+    }
+    // FIXME: this is mixing up the type (as id) from v8/v9 and the types (from the vc.type) from v11
+    else if (!this.isV11OrHigher() && types.length !== 1) {
       throw Error('Only a single credential type is supported for V8/V9');
     }
+    const proof = await buildProof(proofInput, opts);
+
+    // TODO: we should move format specific logic
+    if (format === 'jwt_vc_json' || format === 'jwt_vc') {
+      return {
+        types,
+        format,
+        proof,
+      };
+    } else if (format === 'jwt_vc_json-ld' || format === 'ldp_vc') {
+      if (this.version() >= OpenId4VCIVersion.VER_1_0_12 && !opts.context) {
+        throw Error('No @context value present, but it is required');
+      }
+
+      return {
+        format,
+        proof,
+
+        // Ignored because v11 does not have the context value, but it is required in v12
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        credential_definition: {
+          types,
+          ...(opts.context && { '@context': opts.context }),
+        },
+      };
+    } else if (format === 'vc+sd-jwt') {
+      if (types.length > 1) {
+        throw Error(`Only a single credential type is supported for ${format}`);
+      }
+
+      return {
+        format,
+        proof,
+        vct: types[0],
+      };
+    }
 
-    const proof =
-      'proof_type' in proofInput
-        ? await ProofOfPossessionBuilder.fromProof(proofInput as ProofOfPossession, opts.version).build()
-        : await proofInput.build();
-    return {
-      types,
-      format,
-      proof,
-    } as UniformCredentialRequest;
+    throw new Error(`Unsupported format: ${format}`);
   }
 
   private version(): OpenId4VCIVersion {
     return this.credentialRequestOpts?.version ?? OpenId4VCIVersion.VER_1_0_11;
   }
+
   private isV11OrHigher(): boolean {
     return this.version() >= OpenId4VCIVersion.VER_1_0_11;
   }

package/lib/CredentialRequestClientBuilder.ts

@@ -6,6 +6,7 @@ import {
   determineSpecVersionFromOffer,
   EndpointMetadata,
   getIssuerFromCredentialOfferPayload,
+  getTypesFromOffer,
   OID4VCICredentialFormat,
   OpenId4VCIVersion,
   UniformCredentialOfferRequest,
@@ -17,11 +18,36 @@ import { CredentialRequestClient } from './CredentialRequestClient';
 
 export class CredentialRequestClientBuilder {
   credentialEndpoint?: string;
+  deferredCredentialEndpoint?: string;
+  deferredCredentialAwait = false;
+  deferredCredentialIntervalInMS = 5000;
   credentialTypes: string[] = [];
   format?: CredentialFormat | OID4VCICredentialFormat;
   token?: string;
   version?: OpenId4VCIVersion;
 
+  public static fromCredentialIssuer({
+    credentialIssuer,
+    metadata,
+    version,
+    credentialTypes,
+  }: {
+    credentialIssuer: string;
+    metadata?: EndpointMetadata;
+    version?: OpenId4VCIVersion;
+    credentialTypes: string | string[];
+  }): CredentialRequestClientBuilder {
+    const issuer = credentialIssuer;
+    const builder = new CredentialRequestClientBuilder();
+    builder.withVersion(version ?? OpenId4VCIVersion.VER_1_0_11);
+    builder.withCredentialEndpoint(metadata?.credential_endpoint ?? (issuer.endsWith('/') ? `${issuer}credential` : `${issuer}/credential`));
+    if (metadata?.deferred_credential_endpoint) {
+      builder.withDeferredCredentialEndpoint(metadata.deferred_credential_endpoint);
+    }
+    builder.withCredentialType(credentialTypes);
+    return builder;
+  }
+
   public static async fromURI({ uri, metadata }: { uri: string; metadata?: EndpointMetadata }): Promise<CredentialRequestClientBuilder> {
     const offer = await CredentialOfferClient.fromURI(uri);
     return CredentialRequestClientBuilder.fromCredentialOfferRequest({ request: offer, ...offer, metadata, version: offer.version });
@@ -40,13 +66,16 @@ export class CredentialRequestClientBuilder {
     const issuer = getIssuerFromCredentialOfferPayload(request.credential_offer) ?? (metadata?.issuer as string);
     builder.withVersion(version);
     builder.withCredentialEndpoint(metadata?.credential_endpoint ?? (issuer.endsWith('/') ? `${issuer}credential` : `${issuer}/credential`));
+    if (metadata?.deferred_credential_endpoint) {
+      builder.withDeferredCredentialEndpoint(metadata.deferred_credential_endpoint);
+    }
 
     if (version <= OpenId4VCIVersion.VER_1_0_08) {
       //todo: This basically sets all types available during initiation. Probably the user only wants a subset. So do we want to do this?
       builder.withCredentialType((request.original_credential_offer as CredentialOfferPayloadV1_0_08).credential_type);
     } else {
       // todo: look whether this is correct
-      builder.withCredentialType(request.credential_offer.credentials.flatMap((c) => (typeof c === 'string' ? c : c.types)));
+      builder.withCredentialType(getTypesFromOffer(request.credential_offer));
     }
 
     return builder;
@@ -66,37 +95,53 @@ export class CredentialRequestClientBuilder {
     });
   }
 
-  public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): CredentialRequestClientBuilder {
+  public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): this {
     this.credentialEndpoint = metadata.credential_endpoint;
     return this;
   }
 
-  public withCredentialEndpoint(credentialEndpoint: string): CredentialRequestClientBuilder {
+  public withCredentialEndpoint(credentialEndpoint: string): this {
     this.credentialEndpoint = credentialEndpoint;
     return this;
   }
 
-  public withCredentialType(credentialTypes: string | string[]): CredentialRequestClientBuilder {
+  public withDeferredCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): this {
+    this.deferredCredentialEndpoint = metadata.deferred_credential_endpoint;
+    return this;
+  }
+
+  public withDeferredCredentialEndpoint(deferredCredentialEndpoint: string): this {
+    this.deferredCredentialEndpoint = deferredCredentialEndpoint;
+    return this;
+  }
+
+  public withDeferredCredentialAwait(deferredCredentialAwait: boolean, deferredCredentialIntervalInMS?: number): this {
+    this.deferredCredentialAwait = deferredCredentialAwait;
+    this.deferredCredentialIntervalInMS = deferredCredentialIntervalInMS ?? 5000;
+    return this;
+  }
+
+  public withCredentialType(credentialTypes: string | string[]): this {
     this.credentialTypes = Array.isArray(credentialTypes) ? credentialTypes : [credentialTypes];
     return this;
   }
 
-  public withFormat(format: CredentialFormat | OID4VCICredentialFormat): CredentialRequestClientBuilder {
+  public withFormat(format: CredentialFormat | OID4VCICredentialFormat): this {
     this.format = format;
     return this;
   }
 
-  public withToken(accessToken: string): CredentialRequestClientBuilder {
+  public withToken(accessToken: string): this {
     this.token = accessToken;
     return this;
   }
 
-  public withTokenFromResponse(response: AccessTokenResponse): CredentialRequestClientBuilder {
+  public withTokenFromResponse(response: AccessTokenResponse): this {
     this.token = response.access_token;
     return this;
   }
 
-  public withVersion(version: OpenId4VCIVersion): CredentialRequestClientBuilder {
+  public withVersion(version: OpenId4VCIVersion): this {
     this.version = version;
     return this;
   }

package/lib/MetadataClient.ts

@@ -45,6 +45,7 @@ export class MetadataClient {
   public static async retrieveAllMetadata(issuer: string, opts?: { errorOnNotFound: boolean }): Promise<EndpointMetadataResult> {
     let token_endpoint: string | undefined;
     let credential_endpoint: string | undefined;
+    let deferred_credential_endpoint: string | undefined;
     let authorization_endpoint: string | undefined;
     let authorizationServerType: AuthorizationServerType = 'OID4VCI';
     let authorization_server: string = issuer;
@@ -53,6 +54,7 @@ export class MetadataClient {
     if (credentialIssuerMetadata) {
       debug(`Issuer ${issuer} OID4VCI well-known server metadata\r\n${JSON.stringify(credentialIssuerMetadata)}`);
       credential_endpoint = credentialIssuerMetadata.credential_endpoint;
+      deferred_credential_endpoint = credentialIssuerMetadata.deferred_credential_endpoint;
       if (credentialIssuerMetadata.token_endpoint) {
         token_endpoint = credentialIssuerMetadata.token_endpoint;
       }
@@ -111,12 +113,21 @@ export class MetadataClient {
       if (authMetadata.credential_endpoint) {
         if (credential_endpoint && authMetadata.credential_endpoint !== credential_endpoint) {
           debug(
-            `Credential issuer has a different credential_endpoint (${credential_endpoint}) from the Authorization Server (${authMetadata.token_endpoint}). Will use the issuer value`,
+            `Credential issuer has a different credential_endpoint (${credential_endpoint}) from the Authorization Server (${authMetadata.credential_endpoint}). Will use the issuer value`,
           );
         } else {
           credential_endpoint = authMetadata.credential_endpoint;
         }
       }
+      if (authMetadata.deferred_credential_endpoint) {
+        if (deferred_credential_endpoint && authMetadata.deferred_credential_endpoint !== deferred_credential_endpoint) {
+          debug(
+            `Credential issuer has a different deferred_credential_endpoint (${deferred_credential_endpoint}) from the Authorization Server (${authMetadata.deferred_credential_endpoint}). Will use the issuer value`,
+          );
+        } else {
+          deferred_credential_endpoint = authMetadata.deferred_credential_endpoint;
+        }
+      }
     }
 
     if (!authorization_endpoint) {
@@ -148,6 +159,7 @@ export class MetadataClient {
       issuer,
       token_endpoint,
       credential_endpoint,
+      deferred_credential_endpoint,
       authorization_server,
       authorization_endpoint,
       authorizationServerType,