@sphereon/oid4vci-common 0.4.1-next.285

package/lib/functions/IssuerMetadataUtils.ts

@@ -0,0 +1,101 @@
+import {
+  CredentialIssuerMetadata,
+  CredentialOfferFormat,
+  CredentialSupported,
+  CredentialSupportedTypeV1_0_08,
+  CredentialSupportedV1_0_08,
+  IssuerMetadataV1_0_08,
+  OpenId4VCIVersion,
+} from '../types';
+
+export function getSupportedCredentials(opts?: {
+  issuerMetadata?: CredentialIssuerMetadata | IssuerMetadataV1_0_08;
+  version: OpenId4VCIVersion;
+  credentialTypes?: (CredentialOfferFormat | string)[];
+  supportedType?: CredentialOfferFormat | string;
+}): CredentialSupported[] {
+  const { issuerMetadata } = opts ?? {};
+  let credentialsSupported: CredentialSupported[];
+  if (!issuerMetadata) {
+    return [];
+  }
+  const { version, credentialTypes, supportedType } = opts ?? { version: OpenId4VCIVersion.VER_1_0_11 };
+  if (version === OpenId4VCIVersion.VER_1_0_08 || !Array.isArray(issuerMetadata.credentials_supported)) {
+    credentialsSupported = credentialsSupportedV8ToV11((issuerMetadata as IssuerMetadataV1_0_08).credentials_supported);
+    /*    const credentialsSupportedV8: CredentialSupportedV1_0_08 = credentialsSupported as CredentialSupportedV1_0_08
+        // const initiationTypes = credentialTypes.map(type => typeof type === 'string' ? [type] : type.types)
+        const supported: IssuerCredentialSubject = {}
+        for (const [key, value] of Object.entries(credentialsSupportedV8)) {
+          if (initiationTypes.find((type) => (typeof type === 'string' ? type === key : type.types.includes(key)))) {
+            supported[key] = value
+          }
+        }
+        // todo: fix this later. we're returning CredentialSupportedV1_0_08 as a list of CredentialSupported (for v09 onward)
+        return supported as unknown as CredentialSupported[]*/
+  } else {
+    credentialsSupported = (issuerMetadata as CredentialIssuerMetadata).credentials_supported;
+  }
+
+  if (credentialsSupported === undefined || credentialsSupported.length === 0) {
+    return [];
+  } else if (!credentialTypes || credentialTypes.length === 0) {
+    return credentialsSupported;
+  }
+  /**
+   * the following (not array part is a legacy code from version 1_0-08 which JFF plugfest 2 implementors used)
+   */
+  const initiationTypes = supportedType ? [supportedType] : credentialTypes;
+
+  const credentialSupportedOverlap: CredentialSupported[] = [];
+  for (const offerType of initiationTypes) {
+    if (typeof offerType === 'string') {
+      const supported = credentialsSupported.find((sup) => sup.id === offerType || sup.types.includes(offerType));
+      if (supported) {
+        credentialSupportedOverlap.push(supported);
+      }
+    } else {
+      const supported = credentialsSupported.find((sup) => arrayEqualsIgnoreOrder(sup.types, offerType.types) && sup.format === offerType.format);
+      if (supported) {
+        credentialSupportedOverlap.push(supported);
+      }
+    }
+  }
+  return credentialSupportedOverlap;
+}
+
+function arrayEqualsIgnoreOrder(a: string[], b: string[]) {
+  if (a.length !== b.length) return false;
+  const uniqueValues = new Set([...a, ...b]);
+  for (const v of uniqueValues) {
+    const aCount = a.filter((e) => e === v).length;
+    const bCount = b.filter((e) => e === v).length;
+    if (aCount !== bCount) return false;
+  }
+  return true;
+}
+
+export function credentialsSupportedV8ToV11(supportedV8: CredentialSupportedTypeV1_0_08): CredentialSupported[] {
+  return Object.entries(supportedV8).flatMap((entry) => {
+    const type = entry[0];
+    const supportedV8 = entry[1];
+    return credentialSupportedV8ToV11(type, supportedV8);
+  });
+}
+
+export function credentialSupportedV8ToV11(key: string, supportedV8: CredentialSupportedV1_0_08): CredentialSupported[] {
+  return Object.entries(supportedV8.formats).map((entry) => {
+    const format = entry[0];
+    const credentialSupportBrief = entry[1];
+    if (typeof format !== 'string') {
+      throw Error(`Unknown format received ${JSON.stringify(format)}`);
+    }
+    let credentialSupport: Partial<CredentialSupported> = {};
+    credentialSupport = {
+      format,
+      display: supportedV8.display,
+      ...credentialSupportBrief,
+      credentialSubject: supportedV8.claims,
+    };
+    return credentialSupport as CredentialSupported;
+  });
+}

package/lib/functions/TypeConversionUtils.ts

@@ -0,0 +1,3 @@
+export const getNumberOrUndefined = (input?: string): number | undefined => {
+  return input && !isNaN(+input) ? +input : undefined;
+};

package/lib/functions/index.ts

@@ -0,0 +1,3 @@
+export * from './CredentialOfferUtil';
+export * from './Encoding';
+export * from './TypeConversionUtils';

package/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './functions';
+export * from './types';

package/lib/types/Authorization.types.ts

@@ -0,0 +1,234 @@
+import { CredentialOfferPayload, UniformCredentialOffer } from './CredentialIssuance.types';
+import {
+  EndpointMetadata,
+  ErrorResponse,
+  IssuerCredentialDefinition,
+  IssuerCredentialSubject,
+  OID4VCICredentialFormat,
+  PRE_AUTH_CODE_LITERAL,
+} from './Generic.types';
+
+export interface CommonAuthorizationRequest {
+  /**
+   * REQUIRED.  Value MUST be set to "code". for Authorization Code Grant
+   */
+  response_type: ResponseType.AUTH_CODE;
+  /**
+   * The authorization server issues the registered client a client
+   *    identifier -- a unique string representing the registration
+   *    information provided by the client.
+   */
+  client_id: string;
+  /**
+   * If the "code_challenge_method" from Section 4.3 was "S256", the
+   *    received "code_verifier" is hashed by SHA-256, base64url-encoded, and
+   *    then compared to the "code_challenge", i.e.:
+   *    BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge
+   *
+   * If the "code_challenge_method" from Section 4.3 was "plain", they are
+   *    compared directly, i.e.:
+   *    code_verifier == code_challenge.
+   */
+  code_challenge: string;
+  /**
+   * value must be set either to "S256" or a value defined by a cryptographically secure
+   */
+  code_challenge_method: CodeChallengeMethod;
+  /**
+   * The redirection endpoint URI MUST be an absolute URI as defined by: absolute-URI  = scheme ":" hier-part [ "?" query ]
+   */
+  redirect_uri: string;
+  /**
+   * The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.
+   */
+  scope?: string;
+  /**
+   * There are two possible ways to request issuance of a specific Credential type in an Authorization Request.
+   * One way is to use of the authorization_details request parameter as defined in [I-D.ietf-oauth-rar]
+   * with one or more authorization details objects of type openid_credential Section 5.1.1.
+   * (The other is through the use of scopes as defined in Section 5.1.2.)
+   */
+  authorization_details?: AuthorizationDetails[] | AuthorizationDetails;
+  /**
+   * OPTIONAL. JSON string containing the Wallet's OpenID Connect issuer URL. The Credential Issuer will use the discovery process as defined in
+   * [SIOPv2] to determine the Wallet's capabilities and endpoints. RECOMMENDED in Dynamic Credential Request.
+   */
+  wallet_issuer?: string;
+  /**
+   * OPTIONAL. JSON string containing an opaque user hint the Wallet MAY use in subsequent callbacks to optimize the user's experience.
+   * RECOMMENDED in Dynamic Credential Request.
+   */
+  user_hint?: string;
+  /**
+   * OPTIONAL. String value identifying a certain processing context at the Credential Issuer. A value for this parameter is typically passed in
+   * an issuance initation request from the Credential Issuer to the Wallet (see (Section 4.1). This request parameter is used to pass the
+   * issuer_state value back to the Credential Issuer.
+   */
+  issuer_state?: string;
+}
+
+/**
+ * string type added for conformity with our previous code in the client
+ */
+export type AuthorizationDetails = AuthorizationDetailsJwtVcJson | AuthorizationRequestJwtVcJsonLdAndLdpVc | string;
+
+export type AuthorizationRequest = AuthorizationRequestJwtVcJson | AuthorizationDetailsJwtVcJsonLdAndLdpVc;
+
+export interface AuthorizationRequestJwtVcJson extends CommonAuthorizationRequest {
+  authorization_details?: AuthorizationDetailsJwtVcJson[];
+}
+
+export interface AuthorizationRequestJwtVcJsonLdAndLdpVc extends CommonAuthorizationRequest {
+  authorization_details?: AuthorizationDetailsJwtVcJsonLdAndLdpVc[];
+}
+
+export interface CommonAuthorizationDetails {
+  /**
+   * REQUIRED. JSON string that determines the authorization details type.
+   * MUST be set to openid_credential for the purpose of this specification.
+   */
+  type: 'openid_credential' | string;
+  /**
+   * REQUIRED. JSON string representing the format in which the Credential is requested to be issued.
+   * This Credential format identifier determines further claims in the authorization details object
+   * specifically used to identify the Credential type to be issued. This specification defines
+   * Credential Format Profiles in Appendix E.
+   */
+  format: OID4VCICredentialFormat;
+  /**
+   * If the Credential Issuer metadata contains an authorization_server parameter,
+   * the authorization detail's locations common data field MUST be set to the Credential Issuer Identifier value.
+   */
+  locations?: string[];
+  types: string[]; // This claim contains the type values the Wallet requests authorization for at the issuer.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export interface AuthorizationDetailsJwtVcJson extends CommonAuthorizationDetails {
+  /**
+   * A JSON object containing a list of key value pairs, where the key identifies the claim offered in the Credential.
+   * The value MAY be a dictionary, which allows to represent the full (potentially deeply nested) structure of the
+   * verifiable credential to be issued. This object indicates the claims the Wallet would like to turn up in the
+   * credential to be issued.
+   */
+  credentialSubject?: IssuerCredentialSubject;
+}
+
+export interface AuthorizationDetailsJwtVcJsonLdAndLdpVc extends CommonAuthorizationDetails {
+  /**
+   * REQUIRED. JSON object containing (and isolating) the detailed description of the credential type.
+   * This object MUST be processed using full JSON-LD processing. It consists of the following sub-claims:
+   *   - @context: REQUIRED. JSON array as defined in Appendix E.1.3.2
+   *   - types: REQUIRED. JSON array as defined in Appendix E.1.3.2.
+   *            This claim contains the type values the Wallet shall request in the subsequent Credential Request
+   */
+  credential_definition: IssuerCredentialDefinition;
+}
+
+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 enum CodeChallengeMethod {
+  TEXT = 'text',
+  SHA256 = 'S256',
+}
+
+export interface AuthorizationServerOpts {
+  allowInsecureEndpoints?: boolean;
+  as?: string; // If not provided the issuer hostname will be used!
+  tokenEndpoint?: string; // Allows to override the default '/token' endpoint
+  clientId?: string;
+}
+
+export interface IssuerOpts {
+  issuer: string;
+  tokenEndpoint?: string;
+  fetchMetadata?: boolean;
+}
+
+export interface AccessTokenRequestOpts {
+  credentialOffer: UniformCredentialOffer;
+  asOpts?: AuthorizationServerOpts;
+  metadata?: EndpointMetadata;
+  codeVerifier?: string; // only required for authorization flow
+  code?: string; // only required for authorization flow
+  redirectUri?: string; // only required for authorization flow
+  pin?: string; // Pin-number. Only used when required
+}
+
+export interface AuthorizationRequestOpts {
+  clientId: string;
+  codeChallenge: string;
+  codeChallengeMethod: CodeChallengeMethod;
+  authorizationDetails?: AuthorizationDetails[];
+  redirectUri: string;
+  scope?: string;
+}
+
+export interface AuthorizationGrantResponse {
+  grant_type: string;
+  code: string;
+  scope?: string;
+  state?: string;
+}
+
+export interface AccessTokenRequest {
+  client_id?: string;
+  code?: string;
+  code_verifier?: string;
+  grant_type: GrantTypes;
+  'pre-authorized_code': string;
+  redirect_uri?: string;
+  scope?: string;
+  user_pin?: string;
+}
+
+export interface OpenIDResponse<T> {
+  origResponse: Response;
+  successBody?: T;
+  errorBody?: ErrorResponse;
+}
+
+export interface AccessTokenResponse {
+  access_token: string;
+  scope?: string;
+  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 enum AuthzFlowType {
+  AUTHORIZATION_CODE_FLOW = 'Authorization Code Flow',
+  PRE_AUTHORIZED_CODE_FLOW = 'Pre-Authorized Code Flow',
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace AuthzFlowType {
+  export function valueOf(request: CredentialOfferPayload): AuthzFlowType {
+    if (PRE_AUTH_CODE_LITERAL in request) {
+      return AuthzFlowType.PRE_AUTHORIZED_CODE_FLOW;
+    }
+    return AuthzFlowType.AUTHORIZATION_CODE_FLOW;
+  }
+}
+
+export interface PushedAuthorizationResponse {
+  request_uri: string;
+  expires_in: number;
+}

package/lib/types/CredentialIssuance.types.ts

@@ -0,0 +1,167 @@
+import { W3CVerifiableCredential } from '@sphereon/ssi-types';
+
+import { AuthzFlowType } from './Authorization.types';
+import { OID4VCICredentialFormat } from './Generic.types';
+import { OpenId4VCIVersion } from './OpenID4VCIVersions.types';
+import { CredentialOfferPayloadV1_0_08 } from './v1_0_08.types';
+import { CredentialOfferPayloadV1_0_09, CredentialOfferV1_0_09 } from './v1_0_09.types';
+import { CredentialOfferPayloadV1_0_11, CredentialOfferV1_0_11 } from './v1_0_11.types';
+
+export interface CredentialResponse {
+  credential?: W3CVerifiableCredential; // OPTIONAL. Contains issued Credential. MUST be present when acceptance_token is not returned. MAY be a JSON string or a JSON object, depending on the Credential format. See Appendix E for the Credential format specific encoding requirements
+  format: OID4VCICredentialFormat /* | OID4VCICredentialFormat[]*/; // REQUIRED. JSON string denoting the format of the issued Credential
+  acceptance_token?: string; // OPTIONAL. A JSON string containing a security token subsequently used to obtain a Credential. MUST be present when credential is not returned
+  c_nonce?: string; // OPTIONAL. JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential (see Section 7.2). When received, the Wallet MUST use this nonce value for its subsequent credential requests until the Credential Issuer provides a fresh nonce
+  c_nonce_expires_in?: number; // OPTIONAL. JSON integer denoting the lifetime in seconds of the c_nonce
+}
+
+export interface CredentialOfferRequestWithBaseUrl extends UniformCredentialOfferRequest {
+  scheme: string;
+  baseUrl: string;
+  userPinRequired: boolean;
+  issuerState?: string;
+  preAuthorizedCode?: string;
+}
+
+export type CredentialOffer = CredentialOfferV1_0_09 | CredentialOfferV1_0_11;
+
+export type CredentialOfferPayload = CredentialOfferPayloadV1_0_08 | CredentialOfferPayloadV1_0_09 | CredentialOfferPayloadV1_0_11;
+
+export interface AssertedUniformCredentialOffer extends UniformCredentialOffer {
+  credential_offer: UniformCredentialOfferPayload;
+}
+
+export interface UniformCredentialOffer {
+  credential_offer?: UniformCredentialOfferPayload;
+  credential_offer_uri?: string;
+}
+
+export interface UniformCredentialOfferRequest extends AssertedUniformCredentialOffer {
+  original_credential_offer: CredentialOfferPayload;
+  version: OpenId4VCIVersion;
+  supportedFlows: AuthzFlowType[];
+}
+
+export type UniformCredentialOfferPayload = CredentialOfferPayloadV1_0_11;
+
+export interface ProofOfPossession {
+  proof_type: 'jwt';
+  jwt: string;
+
+  [x: string]: unknown;
+}
+
+export type SearchValue = {
+  // eslint-disable-next-line  @typescript-eslint/no-explicit-any
+  [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string;
+};
+
+export type EncodeJsonAsURIOpts = {
+  uriTypeProperties?: string[];
+  arrayTypeProperties?: string[];
+  baseUrl?: string;
+  param?: string;
+  version?: OpenId4VCIVersion;
+};
+
+export type DecodeURIAsJsonOpts = {
+  requiredProperties?: string[];
+  arrayTypeProperties?: string[];
+};
+
+export interface BaseJWK {
+  kty?: string;
+  crv?: string;
+  x?: string;
+  y?: string;
+  e?: string;
+  n?: string;
+}
+
+export interface JWK extends BaseJWK {
+  alg?: string;
+  d?: string;
+  dp?: string;
+  dq?: string;
+  ext?: boolean;
+  k?: string;
+  key_ops?: string[];
+  kid?: string;
+  oth?: Array<{
+    d?: string;
+    r?: string;
+    t?: string;
+  }>;
+  p?: string;
+  q?: string;
+  qi?: string;
+  use?: string;
+  x5c?: string[];
+  x5t?: string;
+  'x5t#S256'?: string;
+  x5u?: string;
+  [propName: string]: unknown;
+}
+
+export interface Jwt {
+  header: JWTHeader;
+  payload: JWTPayload;
+}
+
+export interface ProofOfPossessionCallbacks {
+  signCallback: JWTSignerCallback;
+  verifyCallback?: JWTVerifyCallback;
+}
+
+export enum Alg {
+  EdDSA = 'EdDSA',
+  ES256 = 'ES256',
+  ES256K = 'ES256K',
+}
+
+export type Typ =
+  | 'jwt'
+  // https://www.rfc-editor.org/rfc/rfc8725.pdf#name-use-explicit-typing
+  // https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-7.2.1-2.1.2.1.2.1.1
+  | 'openid4vci-proof+jwt';
+
+export interface JoseHeaderParameters {
+  kid?: string; // CONDITIONAL. JWT header containing the key ID. If the Credential shall be bound to a DID, the kid refers to a DID URL which identifies a particular key in the DID Document that the Credential shall be bound to. MUST NOT be present if jwk or x5c is present.
+  x5t?: string;
+  x5c?: string[]; // CONDITIONAL. JWT header containing a certificate or certificate chain corresponding to the key used to sign the JWT. This element may be used to convey a key attestation. In such a case, the actual key certificate will contain attributes related to the key properties. MUST NOT be present if kid or jwk is present.
+  x5u?: string;
+  jku?: string;
+  jwk?: BaseJWK; // CONDITIONAL. JWT header containing the key material the new Credential shall be bound to. MUST NOT be present if kid or x5c is present.
+  typ?: string; //JWT always
+  cty?: string;
+}
+
+export interface JWSHeaderParameters extends JoseHeaderParameters {
+  alg?: Alg | string; // REQUIRED by the JWT signer
+  b64?: boolean;
+  crit?: string[];
+  [propName: string]: unknown;
+}
+
+export interface CompactJWSHeaderParameters extends JWSHeaderParameters {
+  alg: string;
+}
+
+export interface JWTHeaderParameters extends CompactJWSHeaderParameters {
+  b64?: true;
+}
+
+export type JWTHeader = JWTHeaderParameters;
+
+export interface JWTPayload {
+  iss?: string; // REQUIRED (string). The value of this claim MUST be the client_id of the client making the credential request.
+  aud?: string; // REQUIRED (string). The value of this claim MUST be the issuer URL of credential issuer.
+  iat?: number; // REQUIRED (number). The value of this claim MUST be the time at which the proof was issued using the syntax defined in [RFC7519].
+  nonce?: string; // REQUIRED (string). The value type of this claim MUST be a string, where the value is a c_nonce provided by the credential issuer. //TODO: Marked as required not present in NGI flow
+  jti?: string; // A new nonce chosen by the wallet. Used to prevent replay
+  exp?: number; // Not longer than 5 minutes
+  [s: string]: unknown;
+}
+
+export type JWTSignerCallback = (jwt: Jwt, kid?: string) => Promise<string>;
+export type JWTVerifyCallback = (args: { jwt: string; kid?: string }) => Promise<Jwt>;