@sphereon/oid4vci-client 0.0.1-unstable.1

package/lib/AccessTokenClient.ts

@@ -0,0 +1,139 @@
+import { ObjectUtils } from '@sphereon/ssi-types';
+
+import { convertJsonToURI, post } from './functions';
+import {
+  AccessTokenRequest,
+  AccessTokenRequestOpts,
+  AccessTokenResponse,
+  AuthorizationServerOpts,
+  ErrorResponse,
+  GrantTypes,
+  IssuanceInitiationRequestPayload,
+  IssuanceInitiationWithBaseUrl,
+  IssuerTokenEndpointOpts,
+} from './types';
+
+export class AccessTokenClient {
+  // private _clientId?: string;
+  // private _authorizationServerUrl?: string;
+
+  public async acquireAccessTokenUsingIssuanceInitiation(
+    issuanceInitiation: IssuanceInitiationWithBaseUrl,
+    clientId: string,
+    opts?: AccessTokenRequestOpts
+  ): Promise<AccessTokenResponse | ErrorResponse> {
+    const { issuanceInitiationRequest } = issuanceInitiation;
+    const reqOpts = {
+      isPinRequired: issuanceInitiationRequest.user_pin_required || false,
+      issuerOpts: { issuer: issuanceInitiationRequest.issuer },
+      asOpts: opts?.asOpts ? { ...opts.asOpts } : undefined,
+    };
+    return await this.acquireAccessTokenUsingRequest(await this.createAccessTokenRequest(issuanceInitiationRequest, clientId, opts), reqOpts);
+  }
+
+  public async acquireAccessTokenUsingRequest(
+    accessTokenRequest: AccessTokenRequest,
+    opts: { isPinRequired?: boolean; asOpts?: AuthorizationServerOpts; issuerOpts?: IssuerTokenEndpointOpts }
+  ): Promise<AccessTokenResponse | ErrorResponse> {
+    this.validate(accessTokenRequest, opts?.isPinRequired);
+    const requestTokenURL = convertJsonToURI(accessTokenRequest, {
+      baseUrl: this.determineTokenURL(opts?.asOpts, opts?.issuerOpts),
+    });
+    return this.sendAuthCode(requestTokenURL, accessTokenRequest);
+  }
+
+  public async createAccessTokenRequest(
+    issuanceInitiationRequest: IssuanceInitiationRequestPayload,
+    clientId: string,
+    opts?: AccessTokenRequestOpts
+  ): Promise<AccessTokenRequest> {
+    const request: Partial<AccessTokenRequest> = {
+      client_id: clientId,
+    };
+    if (issuanceInitiationRequest.user_pin_required) {
+      this.assertNumericPin(true, opts.pin);
+      request.user_pin = opts.pin;
+    }
+    if (issuanceInitiationRequest.pre_authorized_code) {
+      request.grant_type = GrantTypes.PRE_AUTHORIZED_CODE;
+      request.pre_authorized_code = issuanceInitiationRequest.pre_authorized_code;
+    }
+    if (issuanceInitiationRequest.op_state) {
+      if (issuanceInitiationRequest.pre_authorized_code) {
+        throw new Error('Cannot have both a pre_authorized_code and a op_state in the same initiation request');
+      }
+      request.grant_type = GrantTypes.AUTHORIZATION_CODE;
+      this.throwNotSupportedFlow();
+    }
+
+    return request as AccessTokenRequest;
+  }
+
+  private assertPreAuthorizedGrantType(grantType: GrantTypes): void {
+    if (GrantTypes.PRE_AUTHORIZED_CODE !== grantType) {
+      throw new Error("grant type must be 'urn:ietf:params:oauth:grant-type:pre-authorized_code'");
+    }
+  }
+
+  private assertNumericPin(isPinRequired?: boolean, pin?: number): void {
+    if (isPinRequired) {
+      if (!pin || pin < 0 || 99999999 < pin) {
+        throw new Error('A valid pin consisting of maximal 8 numeric characters must be present.');
+      }
+    } else if (pin) {
+      throw new Error('Cannot set a pin, when the pin is not required.');
+    }
+  }
+
+  private assertNonEmptyPreAuthorizedCode(accessTokenRequest: AccessTokenRequest): void {
+    if (!accessTokenRequest.pre_authorized_code) {
+      throw new Error('Pre-authorization must be proven by presenting the pre-authorized code. Code must be present.');
+    }
+  }
+
+  private assertNonEmptyClientId(accessTokenRequest: AccessTokenRequest): void {
+    if (!accessTokenRequest.client_id || accessTokenRequest.client_id.length < 1) {
+      throw new Error('The client Id must be present.');
+    }
+  }
+
+  private validate(accessTokenRequest: AccessTokenRequest, isPinRequired?: boolean): void {
+    if (accessTokenRequest.grant_type === GrantTypes.PRE_AUTHORIZED_CODE) {
+      this.assertPreAuthorizedGrantType(accessTokenRequest.grant_type);
+      this.assertNonEmptyPreAuthorizedCode(accessTokenRequest);
+      this.assertNumericPin(isPinRequired, accessTokenRequest.user_pin);
+      this.assertNonEmptyClientId(accessTokenRequest);
+    } else {
+      this.throwNotSupportedFlow();
+    }
+  }
+
+  private async sendAuthCode(requestTokenURL: string, accessTokenRequest: AccessTokenRequest): Promise<AccessTokenResponse | ErrorResponse> {
+    const response = await post(requestTokenURL, accessTokenRequest);
+    return await response.json();
+  }
+
+  private determineTokenURL(asOpts?: AuthorizationServerOpts, issuerOpts?: IssuerTokenEndpointOpts): string {
+    if (!asOpts && !issuerOpts) {
+      throw new Error('Cannot determine token URL if no issuer and no Authorization Server values are present');
+    }
+    const url = asOpts
+      ? this.creatTokenURLFromURL(asOpts.as, asOpts.tokenEndpoint)
+      : this.creatTokenURLFromURL(issuerOpts.issuer, issuerOpts.tokenEndpoint);
+    if (!url || !ObjectUtils.isString(url)) {
+      throw new Error('No authorization server token URL present. Cannot acquire access token');
+    }
+    return url;
+  }
+
+  private creatTokenURLFromURL(url: string, tokenEndpoint?: string): string {
+    const hostname = url.replace(/https?:\/\//, '').split('/')[0];
+    const endpoint = tokenEndpoint ? tokenEndpoint : '/token';
+    // We always require https
+    return `https://${hostname}${endpoint}`;
+  }
+
+  private throwNotSupportedFlow(): void {
+    throw new Error('Only pre-authorized-code flow is supported');
+  }
+}

package/lib/CredentialRequestClient.ts

@@ -0,0 +1,61 @@
+import { CredentialFormat } from '@sphereon/ssi-types';
+
+import CredentialRequestClientBuilder from './CredentialRequestClientBuilder';
+import { createProofOfPossession, isValidURL, post } from './functions';
+import { CredentialRequest, CredentialResponse, ErrorResponse, ProofOfPossession, ProofOfPossessionOpts, URL_NOT_VALID } from './types';
+
+export class CredentialRequestClient {
+  _issuanceRequestOpts: Partial<{
+    credentialRequestUrl: string;
+    credentialType: string | string[];
+    format: CredentialFormat | CredentialFormat[];
+    proof: ProofOfPossession;
+    token: string;
+  }>;
+
+  public getCredentialRequestUrl(): string {
+    return this._issuanceRequestOpts.credentialRequestUrl;
+  }
+
+  public constructor(builder: CredentialRequestClientBuilder) {
+    this._issuanceRequestOpts = { ...builder };
+  }
+
+  public static builder(): CredentialRequestClientBuilder {
+    return new CredentialRequestClientBuilder();
+  }
+
+  public async sendCredentialRequest(
+    request: CredentialRequest,
+    opts?: { overrideCredentialRequestUrl?: string; overrideToken?: string }
+  ): Promise<CredentialResponse | ErrorResponse> {
+    const requestUrl: string = opts?.overrideCredentialRequestUrl
+      ? opts.overrideCredentialRequestUrl
+      : this._issuanceRequestOpts.credentialRequestUrl;
+    if (!isValidURL(requestUrl)) {
+      throw new Error(URL_NOT_VALID);
+    }
+    const requestToken: string = opts?.overrideToken ? opts.overrideToken : this._issuanceRequestOpts.token;
+    const response = await post(requestUrl, request, requestToken);
+    const responseJson = await response.json();
+    if (responseJson.error) {
+      return { ...responseJson } as ErrorResponse;
+    }
+    return { ...responseJson } as CredentialResponse;
+  }
+
+  public async createCredentialRequest(
+    proof: ProofOfPossession | ProofOfPossessionOpts,
+    opts?: {
+      credentialType?: string | string[];
+      format?: CredentialFormat | CredentialFormat[];
+    }
+  ): Promise<CredentialRequest> {
+    const proofOfPossession = 'jwt' in proof ? proof : await createProofOfPossession(proof);
+    return {
+      type: opts?.credentialType ? opts.credentialType : this._issuanceRequestOpts.credentialType,
+      format: opts?.format ? opts.format : this._issuanceRequestOpts.format,
+      proof: proofOfPossession,
+    };
+  }
+}

package/lib/CredentialRequestClientBuilder.ts

@@ -0,0 +1,46 @@
+import { CredentialFormat } from '@sphereon/ssi-types';
+
+import { CredentialRequestClient } from './CredentialRequestClient';
+import { convertURIToJsonObject } from './functions';
+import { IssuanceInitiationRequestPayload } from './types';
+
+export default class CredentialRequestClientBuilder {
+  credentialRequestUrl: string;
+  credentialType: string | string[];
+  format: CredentialFormat | CredentialFormat[];
+
+  static fromIssuanceInitiationURI(issuanceInitiation: string): CredentialRequestClientBuilder {
+    return CredentialRequestClientBuilder.fromIssuanceInitiationRequest(
+      convertURIToJsonObject(issuanceInitiation, {
+        arrayTypeProperties: ['credential_type'],
+        requiredProperties: ['issuer', 'credential_type'],
+      }) as IssuanceInitiationRequestPayload
+    );
+  }
+
+  static fromIssuanceInitiationRequest(issuanceInitiation: IssuanceInitiationRequestPayload): CredentialRequestClientBuilder {
+    const builder = new CredentialRequestClientBuilder();
+    builder.withCredentialRequestUrl(issuanceInitiation.issuer);
+    builder.withCredentialType(issuanceInitiation.credential_type);
+    return builder;
+  }
+
+  withCredentialRequestUrl(credentialRequestUrl: string): CredentialRequestClientBuilder {
+    this.credentialRequestUrl = credentialRequestUrl;
+    return this;
+  }
+
+  withCredentialType(credentialType: string | string[]): CredentialRequestClientBuilder {
+    this.credentialType = credentialType;
+    return this;
+  }
+
+  withFormat(format: CredentialFormat | CredentialFormat[]): CredentialRequestClientBuilder {
+    this.format = format;
+    return this;
+  }
+
+  build(): CredentialRequestClient {
+    return new CredentialRequestClient(this);
+  }
+}

package/lib/IssuanceInitiation.ts

@@ -0,0 +1,28 @@
+import { convertJsonToURI, convertURIToJsonObject } from './functions';
+import { IssuanceInitiationRequestPayload, IssuanceInitiationWithBaseUrl } from './types';
+
+export default class IssuanceInitiation {
+  static fromURI(issuanceInitiationURI: string): IssuanceInitiationWithBaseUrl {
+    if (!issuanceInitiationURI.includes('?')) {
+      throw new Error('Invalid Issuance Initiation Request Payload');
+    }
+    const baseUrl = issuanceInitiationURI.split('?')[0];
+    const issuanceInitiationRequest = convertURIToJsonObject(issuanceInitiationURI, {
+      arrayTypeProperties: ['credential_type'],
+      requiredProperties: ['issuer', 'credential_type'],
+    }) as IssuanceInitiationRequestPayload;
+
+    return {
+      baseUrl,
+      issuanceInitiationRequest,
+    };
+  }
+
+  static toURI(issuanceInitiation: IssuanceInitiationWithBaseUrl): string {
+    return convertJsonToURI(issuanceInitiation.issuanceInitiationRequest, {
+      baseUrl: issuanceInitiation.baseUrl,
+      arrayTypeProperties: ['credential_type'],
+      uriTypeProperties: ['issuer', 'credential_type'],
+    });
+  }
+}

package/lib/functions/Encoding.ts

@@ -0,0 +1,132 @@
+import { BAD_PARAMS, DecodeURIAsJsonOpts, EncodeJsonAsURIOpts, SearchValue } from '../types';
+
+/**
+ * @function encodeJsonAsURI encodes a Json object into a URI
+ * @param json object
+ * @param opts:
+ *          - urlTypeProperties: a list of properties of which the value is a URL
+ *          - arrayTypeProperties: a list of properties which are an array
+ */
+export function convertJsonToURI(json: unknown, opts?: EncodeJsonAsURIOpts): string {
+  if (typeof json === 'string') {
+    return convertJsonToURI(JSON.parse(json), opts);
+  }
+  const results = [];
+
+  function encodeAndStripWhitespace(key: string): string {
+    return encodeURIComponent(key.replace(' ', ''));
+  }
+
+  for (const [key, value] of Object.entries(json)) {
+    if (!value) {
+      continue;
+    }
+    //Skip properties that are not of URL type
+    if (!opts?.uriTypeProperties?.includes(key)) {
+      results.push(`${key}=${value}`);
+      continue;
+    }
+    if (opts?.arrayTypeProperties?.includes(key) && Array.isArray(value)) {
+      results.push(value.map((v) => `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(v, /\./g)}`).join('&'));
+      continue;
+    }
+    const isBool = typeof value == 'boolean';
+    const isNumber = typeof value == 'number';
+    const isString = typeof value == 'string';
+    let encoded;
+    if (isBool || isNumber) {
+      encoded = `${encodeAndStripWhitespace(key)}=${value}`;
+    } else if (isString) {
+      encoded = `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(value, /\./g)}`;
+    } else {
+      encoded = `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(JSON.stringify(value), /\./g)}`;
+    }
+    results.push(encoded);
+  }
+  const components = results.join('&');
+  if (opts.baseUrl) {
+    return `${opts.baseUrl}?${components}`;
+  }
+  return components;
+}
+
+/**
+ * @function decodeUriAsJson decodes an URI into a Json object
+ * @param uri string
+ * @param opts:
+ *          - requiredProperties: the required properties
+ *          - arrayTypeProperties: properties that can show up more that once
+ */
+export function convertURIToJsonObject(uri: string, opts?: DecodeURIAsJsonOpts): unknown {
+  if (!uri || !opts?.requiredProperties.every((p) => uri.includes(p))) {
+    throw new Error(BAD_PARAMS);
+  }
+  const uriComponents = getURIComponentsAsArray(uri, opts?.arrayTypeProperties);
+  return decodeJsonProperties(uriComponents);
+}
+
+function decodeJsonProperties(parts: string[]): unknown {
+  const json: unknown = {};
+  for (const key in parts) {
+    const value = parts[key];
+    if (!value) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > 1) {
+        json[decodeURIComponent(key)] = value.map((v) => decodeURIComponent(v));
+      } else {
+        json[decodeURIComponent(key)] = decodeURIComponent(value[0]);
+      }
+    }
+    const isBool = typeof value == 'boolean';
+    const isNumber = typeof value == 'number';
+    const isString = typeof value == 'string';
+    if (isBool || isNumber) {
+      json[decodeURIComponent(key)] = value;
+    } else if (isString) {
+      const decoded = decodeURIComponent(value);
+      if (decoded.startsWith('{') && decoded.endsWith('}')) {
+        json[decodeURIComponent(key)] = JSON.parse(decoded);
+      } else {
+        json[decodeURIComponent(key)] = decoded;
+      }
+    }
+  }
+  return json;
+}
+
+/**
+ * @function get URI Components as Array
+ * @param uri string
+ * @param arrayType array of string containing array like keys
+ */
+function getURIComponentsAsArray(uri: string, arrayType?: string[]): string[] {
+  const parts = uri.includes('?') ? uri.split('?')[1] : uri.includes('://') ? uri.split('://')[1] : uri;
+  const json: string[] = [];
+  const dict = parts.split('&');
+  for (const entry of dict) {
+    const pair = entry.split('=');
+    if (arrayType?.includes(pair[0])) {
+      if (json[pair[0]] !== undefined) {
+        json[pair[0]].push(pair[1]);
+      } else {
+        json[pair[0]] = [pair[1]];
+      }
+      continue;
+    }
+    json[pair[0]] = pair[1];
+  }
+  return json;
+}
+
+/**
+ * @function customEncodeURIComponent is used to encode chars that are not encoded by default
+ * @param searchValue The pattern/regexp to find the char(s) to be encoded
+ * @param uriComponent query string
+ */
+function customEncodeURIComponent(uriComponent: string, searchValue: SearchValue): string {
+  // -_.!~*'() are not escaped because they are considered safe.
+  // Add them to the regex as you need
+  return encodeURIComponent(uriComponent).replace(searchValue, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}

package/lib/functions/HttpUtils.ts

@@ -0,0 +1,42 @@
+import { fetch } from 'cross-fetch';
+
+export async function post(url: string, body: unknown, bearerToken?: string): Promise<Response> {
+  let message = '';
+  try {
+    const payload: RequestInit = {
+      method: 'POST',
+      body: JSON.stringify(body),
+    };
+
+    if (bearerToken) {
+      payload.headers = {
+        Authorization: `Bearer ${bearerToken}`,
+      };
+    }
+    const response = await fetch(url, payload);
+    if (response && response.status && response.status < 400) {
+      return response;
+    } else {
+      if (response) {
+        message = `${response.status}:${response.statusText}, ${await response.text()}`;
+      }
+    }
+  } catch (error) {
+    throw new Error(`${(error as Error).message}`);
+  }
+
+  throw new Error('unexpected error: ' + message);
+}
+
+export function isValidURL(url: string): boolean {
+  const urlPattern = new RegExp(
+    '^(https:\\/\\/)?' + // validate protocol
+      '((([a-z\\d]([a-z\\d-]*[a-z\\d])*)\\.)+[a-z]{2,}|' + // validate domain name
+      '((\\d{1,3}\\.){3}\\d{1,3}))' + // validate OR ip (v4) address
+      '(\\:\\d+)?(\\/[-a-z\\d%_.~+]*)*' + // validate port and path
+      '(\\?[;&a-z\\d%_.~+=-]*)?' + // validate query string
+      '(\\#[-a-z\\d_]*)?$',
+    'i'
+  ); // validate fragment locator
+  return !!urlPattern.test(url);
+}

package/lib/functions/ProofUtil.ts

@@ -0,0 +1,56 @@
+import { BAD_PARAMS, JWS_NOT_VALID, JWTHeader, JWTPayload, JWTSignerArgs, ProofOfPossession, ProofOfPossessionOpts, ProofType } from '../types';
+
+/**
+ * createProofOfPossession creates and returns the ProofOfPossession object
+ * @param opts
+ *         - jwtSignerArgs: The arguments to create the signature
+ *         - jwtSignerCallback: function to sign the proof
+ *         - jwtVerifyCallback: function to verify if JWT is valid
+ */
+export async function createProofOfPossession(opts: ProofOfPossessionOpts): Promise<ProofOfPossession> {
+  if (!opts.jwtSignerCallback || !opts.jwtSignerArgs) {
+    throw new Error(BAD_PARAMS);
+  }
+  const signerArgs = setJWSDefaults(opts.jwtSignerArgs, opts.credentialRequestUrl);
+  const jwt = await opts.jwtSignerCallback(signerArgs);
+  try {
+    if (opts.jwtVerifyCallback) {
+      const algorithm = opts.jwtSignerArgs.header.alg;
+      await opts.jwtVerifyCallback({ jws: jwt, key: opts.jwtSignerArgs.publicKey, algorithms: [algorithm] });
+    } else {
+      partiallyValidateJWS(jwt);
+    }
+  } catch {
+    throw new Error(JWS_NOT_VALID);
+  }
+  return {
+    proof_type: ProofType.JWT,
+    jwt,
+  };
+}
+
+function partiallyValidateJWS(jws: string): void {
+  if (jws.split('.').length !== 3 || !jws.startsWith('ey')) {
+    throw new Error(JWS_NOT_VALID);
+  }
+}
+
+function setJWSDefaults(args: JWTSignerArgs, credentialRequestUrl?: string): JWTSignerArgs {
+  const now = +new Date();
+  const aud = args.payload.aud ? args.payload.aud : credentialRequestUrl;
+  if (!aud) {
+    throw new Error('No request url provider');
+  }
+  const defaultPayload: Partial<JWTPayload> = {
+    aud,
+    iat: args.payload.iat ? args.payload.iat : now / 1000,
+    exp: args.payload.exp ? args.payload.exp : (now + 5 * 60000) / 1000,
+  };
+  const defaultHeader: JWTHeader = {
+    alg: 'ES256',
+    typ: 'JWT',
+  };
+  args.payload = { ...defaultPayload, ...args.payload };
+  args.header = { ...defaultHeader, ...args.header };
+  return args;
+}

package/lib/functions/index.ts

@@ -0,0 +1,3 @@
+export * from './Encoding';
+export * from './HttpUtils';
+export * from './ProofUtil';

package/lib/index.ts

@@ -0,0 +1,6 @@
+export * from './functions';
+export * from './types';
+export * from './IssuanceInitiation';
+export * from './AccessTokenClient';
+export * from './CredentialRequestClient';
+export * from './CredentialRequestClientBuilder';

package/lib/types/OIDC4VCI.types.ts

@@ -0,0 +1,72 @@
+export enum GrantTypes {
+  AUTHORIZATION_CODE = 'authorization_code',
+  PRE_AUTHORIZED_CODE = 'urn:ietf:params:oauth:grant-type:pre-authorized_code',
+  PASSWORD = 'password',
+}
+
+export enum Encoding {
+  FORM_URL_ENCODED = 'application/x-www-form-urlencoded',
+  UTF_8 = 'UTF-8',
+}
+
+export enum ResponseType {
+  AUTH_CODE = 'code',
+}
+
+export interface AuthorizationServerOpts {
+  as?: string; // If not provided the issuer hostname will be used!
+  tokenEndpoint?: string; // Allows to override the default '/token' endpoint
+  clientId?: string; // If not provided a random clientId will be generated
+}
+
+export interface IssuerTokenEndpointOpts {
+  issuer: string;
+  tokenEndpoint?: string;
+}
+
+export interface AccessTokenRequestOpts {
+  asOpts?: AuthorizationServerOpts;
+  pin?: number;
+  // client_id?: string;
+}
+
+export interface AuthorizationRequest {
+  response_type: ResponseType.AUTH_CODE;
+  client_id: string;
+  redirect_uri: string;
+  scope?: string;
+}
+
+export interface AuthorizationGrantResponse {
+  grant_type: string;
+  code: string;
+  scope?: string;
+  state?: string;
+}
+
+export interface AccessTokenRequest {
+  client_id?: string;
+  code_verifier?: string;
+  grant_type: GrantTypes;
+  pre_authorized_code: string;
+  redirect_uri?: string;
+  scope?: string;
+  user_pin?: number;
+}
+
+export interface AccessTokenResponse {
+  access_token?: number; // integer
+  token_type?: string;
+  expires_in?: number; // in seconds
+  c_nonce?: string;
+  c_nonce_expires_in?: number; // in seconds
+  authorization_pending?: boolean;
+  interval?: number; // in seconds
+}
+
+export interface ErrorResponse extends Response {
+  error: string;
+  error_description?: string;
+  error_uri?: string;
+  state?: string;
+}

package/lib/types/Oidc4vciErrors.ts

@@ -0,0 +1,3 @@
+export const BAD_PARAMS = 'Wrong parameters provided';
+export const URL_NOT_VALID = 'Request url is not valid';
+export const JWS_NOT_VALID = 'JWS is not valid';