@sphereon/oid4vci-client 0.2.0 → 0.4.1-next.285

package/lib/CredentialRequestClient.ts

@@ -0,0 +1,137 @@
+import {
+  CredentialRequestV1_0_08,
+  CredentialResponse,
+  OID4VCICredentialFormat,
+  OpenId4VCIVersion,
+  OpenIDResponse,
+  ProofOfPossession,
+  UniformCredentialRequest,
+  URL_NOT_VALID,
+} from '@sphereon/oid4vci-common';
+import { CredentialFormat } from '@sphereon/ssi-types';
+import Debug from 'debug';
+
+import { CredentialRequestClientBuilder } from './CredentialRequestClientBuilder';
+import { ProofOfPossessionBuilder } from './ProofOfPossessionBuilder';
+import { isValidURL, post } from './functions';
+
+const debug = Debug('sphereon:oid4vci:credential');
+
+export interface CredentialRequestOpts {
+  credentialEndpoint: string;
+  credentialTypes: string[];
+  format?: CredentialFormat | OID4VCICredentialFormat;
+  proof: ProofOfPossession;
+  token: string;
+  version: OpenId4VCIVersion;
+}
+
+export class CredentialRequestClient {
+  private readonly _credentialRequestOpts: Partial<CredentialRequestOpts>;
+
+  get credentialRequestOpts(): CredentialRequestOpts {
+    return this._credentialRequestOpts as CredentialRequestOpts;
+  }
+
+  public getCredentialEndpoint(): string {
+    return this.credentialRequestOpts.credentialEndpoint;
+  }
+
+  public constructor(builder: CredentialRequestClientBuilder) {
+    this._credentialRequestOpts = { ...builder };
+  }
+
+  public async acquireCredentialsUsingProof(opts: {
+    proofInput: ProofOfPossessionBuilder | ProofOfPossession;
+    credentialTypes?: string | string[];
+    format?: CredentialFormat | OID4VCICredentialFormat;
+  }): Promise<OpenIDResponse<CredentialResponse>> {
+    const { credentialTypes, proofInput, format } = opts;
+
+    const request = await this.createCredentialRequest({ proofInput, credentialTypes, 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 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}`);
+    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}`);
+    return response;
+  }
+
+  public async createCredentialRequest(opts: {
+    proofInput: ProofOfPossessionBuilder | ProofOfPossession;
+    credentialTypes?: string | 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) {
+      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 typesSelection =
+      opts?.credentialTypes && (typeof opts.credentialTypes === 'string' || opts.credentialTypes.length > 0)
+        ? opts.credentialTypes
+        : this.credentialRequestOpts.credentialTypes;
+    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) {
+      throw Error('Only a single credential type is supported for V8/V9');
+    }
+
+    const proof =
+      'proof_type' in proofInput
+        ? await ProofOfPossessionBuilder.fromProof(proofInput as ProofOfPossession, opts.version).build()
+        : await proofInput.build();
+    return {
+      types,
+      format,
+      proof,
+    } as UniformCredentialRequest;
+  }
+
+  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

@@ -0,0 +1,110 @@
+import {
+  AccessTokenResponse,
+  CredentialIssuerMetadata,
+  CredentialOfferPayloadV1_0_08,
+  CredentialOfferRequestWithBaseUrl,
+  determineSpecVersionFromOffer,
+  EndpointMetadata,
+  getIssuerFromCredentialOfferPayload,
+  OID4VCICredentialFormat,
+  OpenId4VCIVersion,
+  UniformCredentialOfferRequest,
+} from '@sphereon/oid4vci-common';
+import { CredentialFormat } from '@sphereon/ssi-types';
+
+import { CredentialOfferClient } from './CredentialOfferClient';
+import { CredentialRequestClient } from './CredentialRequestClient';
+
+export class CredentialRequestClientBuilder {
+  credentialEndpoint?: string;
+  credentialTypes: string[] = [];
+  format?: CredentialFormat | OID4VCICredentialFormat;
+  token?: string;
+  version?: OpenId4VCIVersion;
+
+  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 });
+  }
+
+  public static fromCredentialOfferRequest(opts: {
+    request: UniformCredentialOfferRequest;
+    scheme?: string;
+    baseUrl?: string;
+    version?: OpenId4VCIVersion;
+    metadata?: EndpointMetadata;
+  }): CredentialRequestClientBuilder {
+    const { request, metadata } = opts;
+    const version = opts.version ?? request.version ?? determineSpecVersionFromOffer(request.original_credential_offer);
+    const builder = new 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 (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)));
+    }
+
+    return builder;
+  }
+
+  public static fromCredentialOffer({
+    credentialOffer,
+    metadata,
+  }: {
+    credentialOffer: CredentialOfferRequestWithBaseUrl;
+    metadata?: EndpointMetadata;
+  }): CredentialRequestClientBuilder {
+    return CredentialRequestClientBuilder.fromCredentialOfferRequest({
+      request: credentialOffer,
+      metadata,
+      version: credentialOffer.version,
+    });
+  }
+
+  public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): CredentialRequestClientBuilder {
+    this.credentialEndpoint = metadata.credential_endpoint;
+    return this;
+  }
+
+  public withCredentialEndpoint(credentialEndpoint: string): CredentialRequestClientBuilder {
+    this.credentialEndpoint = credentialEndpoint;
+    return this;
+  }
+
+  public withCredentialType(credentialTypes: string | string[]): CredentialRequestClientBuilder {
+    this.credentialTypes = Array.isArray(credentialTypes) ? credentialTypes : [credentialTypes];
+    return this;
+  }
+
+  public withFormat(format: CredentialFormat | OID4VCICredentialFormat): CredentialRequestClientBuilder {
+    this.format = format;
+    return this;
+  }
+
+  public withToken(accessToken: string): CredentialRequestClientBuilder {
+    this.token = accessToken;
+    return this;
+  }
+
+  public withTokenFromResponse(response: AccessTokenResponse): CredentialRequestClientBuilder {
+    this.token = response.access_token;
+    return this;
+  }
+
+  public withVersion(version: OpenId4VCIVersion): CredentialRequestClientBuilder {
+    this.version = version;
+    return this;
+  }
+
+  public build(): CredentialRequestClient {
+    if (!this.version) {
+      this.withVersion(OpenId4VCIVersion.VER_1_0_11);
+    }
+    return new CredentialRequestClient(this);
+  }
+}

package/lib/MetadataClient.ts

@@ -0,0 +1,147 @@
+import {
+  CredentialIssuerMetadata,
+  CredentialOfferPayload,
+  CredentialOfferRequestWithBaseUrl,
+  EndpointMetadata,
+  getIssuerFromCredentialOfferPayload,
+  OAuth2ASMetadata,
+  Oauth2ASWithOID4VCIMetadata,
+  OpenIDResponse,
+  WellKnownEndpoints,
+} from '@sphereon/oid4vci-common';
+import Debug from 'debug';
+
+import { getJson } from './functions';
+
+const debug = Debug('sphereon:oid4vci:metadata');
+
+export class MetadataClient {
+  /**
+   * Retrieve metadata using the Initiation obtained from a previous step
+   *
+   * @param credentialOffer
+   */
+  public static async retrieveAllMetadataFromCredentialOffer(credentialOffer: CredentialOfferRequestWithBaseUrl): Promise<EndpointMetadata> {
+    return MetadataClient.retrieveAllMetadataFromCredentialOfferRequest(credentialOffer.credential_offer);
+  }
+
+  /**
+   * Retrieve the metada using the initiation request obtained from a previous step
+   * @param request
+   */
+  public static async retrieveAllMetadataFromCredentialOfferRequest(request: CredentialOfferPayload): Promise<EndpointMetadata> {
+    if (getIssuerFromCredentialOfferPayload(request)) {
+      return MetadataClient.retrieveAllMetadata(getIssuerFromCredentialOfferPayload(request) as string);
+    }
+    throw new Error("can't retrieve metadata from CredentialOfferRequest. No issuer field is present");
+  }
+
+  /**
+   * Retrieve all metadata from an issuer
+   * @param issuer The issuer URL
+   * @param opts
+   */
+  public static async retrieveAllMetadata(issuer: string, opts?: { errorOnNotFound: boolean }): Promise<EndpointMetadata> {
+    let token_endpoint;
+    let credential_endpoint;
+    const response = await MetadataClient.retrieveOpenID4VCIServerMetadata(issuer);
+    let issuerMetadata = response?.successBody;
+    if (issuerMetadata) {
+      debug(`Issuer ${issuer} OID4VCI well-known server metadata\r\n${issuerMetadata}`);
+      credential_endpoint = issuerMetadata.credential_endpoint;
+      token_endpoint = issuerMetadata.token_endpoint;
+      if (!token_endpoint && issuerMetadata.authorization_server) {
+        debug(
+          `Issuer ${issuer} OID4VCI metadata has separate authorization_server ${issuerMetadata.authorization_server} that contains the token endpoint`
+        );
+        // Crossword uses this to separate the AS metadata. We fail when not found, since we now have no way of getting the token endpoint
+        const response: OpenIDResponse<OAuth2ASMetadata> = await this.retrieveWellknown(
+          issuerMetadata.authorization_server,
+          WellKnownEndpoints.OAUTH_AS,
+          {
+            errorOnNotFound: true,
+          }
+        );
+        token_endpoint = response.successBody?.token_endpoint;
+      }
+    } else {
+      // No specific OID4VCI endpoint. Either can be an OAuth2 AS or an OpenID IDP. Let's start with OIDC first
+      let response: OpenIDResponse<Oauth2ASWithOID4VCIMetadata> = await MetadataClient.retrieveWellknown(
+        issuer,
+        WellKnownEndpoints.OPENID_CONFIGURATION,
+        {
+          errorOnNotFound: false,
+        }
+      );
+      let asConfig = response.successBody;
+      if (asConfig) {
+        debug(`Issuer ${issuer} has OpenID Connect Server metadata in well-known location`);
+      } else {
+        // Now oAuth2
+        response = await MetadataClient.retrieveWellknown(issuer, WellKnownEndpoints.OAUTH_AS, { errorOnNotFound: false });
+        asConfig = response.successBody;
+      }
+      if (asConfig) {
+        debug(`Issuer ${issuer} has oAuth2 Server metadata in well-known location`);
+        issuerMetadata = asConfig;
+        credential_endpoint = issuerMetadata.credential_endpoint;
+        token_endpoint = issuerMetadata.token_endpoint;
+      }
+    }
+    if (!token_endpoint) {
+      debug(`Issuer ${issuer} does not have a token_endpoint listed in well-known locations!`);
+      if (opts?.errorOnNotFound) {
+        throw new Error(`Could not deduce the token endpoint for ${issuer}`);
+      } else {
+        token_endpoint = `${issuer}${issuer.endsWith('/') ? '' : '/'}token`;
+      }
+    }
+    if (!credential_endpoint) {
+      debug(`Issuer ${issuer} does not have a credential_endpoint listed in well-known locations!`);
+      if (opts?.errorOnNotFound) {
+        throw new Error(`Could not deduce the credential endpoint for ${issuer}`);
+      } else {
+        credential_endpoint = `${issuer}${issuer.endsWith('/') ? '' : '/'}credential`;
+      }
+    }
+    debug(`Issuer ${issuer} token endpoint ${token_endpoint}, credential endpoint ${credential_endpoint}`);
+    return {
+      issuer,
+      token_endpoint,
+      credential_endpoint,
+      issuerMetadata,
+    };
+  }
+
+  /**
+   * Retrieve only the OID4VCI metadata for the issuer. So no OIDC/OAuth2 metadata
+   *
+   * @param issuerHost The issuer hostname
+   */
+  public static async retrieveOpenID4VCIServerMetadata(issuerHost: string): Promise<OpenIDResponse<CredentialIssuerMetadata> | undefined> {
+    // Since the server metadata endpoint is optional we are not going to throw an error.
+    return MetadataClient.retrieveWellknown(issuerHost, WellKnownEndpoints.OPENID4VCI_ISSUER, { errorOnNotFound: false });
+  }
+
+  /**
+   * Allows to retrieve information from a well-known location
+   *
+   * @param host The host
+   * @param endpointType The endpoint type, currently supports OID4VCI, OIDC and OAuth2 endpoint types
+   * @param opts Options, like for instance whether an error should be thrown in case the endpoint doesn't exist
+   */
+  public static async retrieveWellknown<T>(
+    host: string,
+    endpointType: WellKnownEndpoints,
+    opts?: { errorOnNotFound?: boolean }
+  ): Promise<OpenIDResponse<T>> {
+    const result: OpenIDResponse<T> = await getJson(`${host.endsWith('/') ? host.slice(0, -1) : host}${endpointType}`, {
+      exceptionOnHttpErrorStatus: opts?.errorOnNotFound,
+    });
+    if (result.origResponse.status === 404) {
+      // We only get here when error on not found is false
+      debug(`host ${host} with endpoint type ${endpointType} was not found (404)`);
+    }
+    return result;
+  }
+}