@sphereon/oid4vci-common
Version:
OpenID 4 Verifiable Credential Issuance Common Types
1,214 lines (1,201 loc) • 88.5 kB
TypeScript
import * as _sphereon_ssi_types from '@sphereon/ssi-types';
import { CredentialFormat, ICredentialContextType, W3CVerifiableCredential, IVerifiableCredential, EventManager, Loggers } from '@sphereon/ssi-types';
import { DynamicRegistrationClientMetadata, SigningAlgo, JWK, BaseJWK, CreateDPoPClientOpts } from '@sphereon/oid4vc-common';
import { SupportedEncodings } from 'uint8arrays/to-string';
/**
* Copied from openid-client
*/
type ClientResponseType = 'code' | 'id_token' | 'code id_token' | 'none' | string;
type ClientAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'client_secret_jwt' | 'private_key_jwt' | 'tls_client_auth' | 'self_signed_tls_client_auth' | 'none';
interface ClientMetadata {
client_id: string;
id_token_signed_response_alg?: string;
token_endpoint_auth_method?: ClientAuthMethod;
client_secret?: string;
redirect_uris?: string[];
response_types?: ClientResponseType[];
post_logout_redirect_uris?: string[];
default_max_age?: number;
require_auth_time?: boolean;
tls_client_certificate_bound_access_tokens?: boolean;
request_object_signing_alg?: string;
id_token_encrypted_response_alg?: string;
id_token_encrypted_response_enc?: string;
introspection_endpoint_auth_method?: ClientAuthMethod;
introspection_endpoint_auth_signing_alg?: string;
request_object_encryption_alg?: string;
request_object_encryption_enc?: string;
revocation_endpoint_auth_method?: ClientAuthMethod;
revocation_endpoint_auth_signing_alg?: string;
token_endpoint_auth_signing_alg?: string;
userinfo_encrypted_response_alg?: string;
userinfo_encrypted_response_enc?: string;
userinfo_signed_response_alg?: string;
authorization_encrypted_response_alg?: string;
authorization_encrypted_response_enc?: string;
authorization_signed_response_alg?: string;
[key: string]: unknown;
}
/**
* Experimental support not following the VCI spec to have the holder actually (re)sign the issued credential and return it to the issuer
*/
declare const EXPERIMENTAL_SUBJECT_PROOF_MODE_ENABLED: boolean;
type SubjectProofMode = 'proof_chain' | 'proof_set' | 'proof_replace';
type SubjectProofNotificationEventsSupported = 'credential_accepted_holder_signed' | 'credential_deleted_holder_signed' | 'credential_accepted';
interface ExperimentalSubjectIssuance {
credential_subject_issuance?: {
subject_proof_mode: SubjectProofMode;
notification_events_supported: Array<SubjectProofNotificationEventsSupported>;
};
}
type OAuthResponseType = 'code' | 'token' | 'id_token' | 'code token' | 'code id_token' | 'token id_token' | 'code token id_token';
type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'client_secret_jwt' | 'private_key_jwt' | 'none';
type TokenEndpointAuthSigningAlg = 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512' | 'HS256' | 'HS384' | 'HS512';
type OAuthScope = 'openid' | 'profile' | 'email' | 'address' | 'phone' | 'offline_access';
type OAuthResponseMode = 'query' | 'fragment' | 'form_post';
type OAuthGrantType = 'authorization_code' | 'implicit' | 'password' | 'client_credentials' | 'refresh_token' | 'urn:ietf:params:oauth:grant-type:device_code' | 'urn:ietf:params:oauth:grant-type:saml2-bearer' | 'urn:ietf:params:oauth:grant-type:jwt-bearer';
type RevocationEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'client_secret_jwt' | 'private_key_jwt' | 'none';
type RevocationEndpointAuthSigningAlg = 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512' | 'HS256' | 'HS384' | 'HS512';
type PKCECodeChallengeMethod = 'plain' | 'S256';
interface AuthorizationServerMetadata extends DynamicRegistrationClientMetadata {
issuer: string;
authorization_endpoint?: string;
authorization_challenge_endpoint?: string;
token_endpoint?: string;
token_endpoint_auth_methods_supported?: Array<TokenEndpointAuthMethod>;
token_endpoint_auth_signing_alg_values_supported?: Array<TokenEndpointAuthSigningAlg>;
registration_endpoint?: string;
scopes_supported?: Array<OAuthScope | string>;
response_types_supported: Array<OAuthResponseType>;
response_modes_supported?: Array<OAuthResponseMode>;
grant_types_supported?: Array<OAuthGrantType>;
service_documentation?: string;
ui_locales_supported?: string[];
op_policy_uri?: string;
op_tos_uri?: string;
revocation_endpoint?: string;
revocation_endpoint_auth_methods_supported?: Array<RevocationEndpointAuthMethod>;
revocation_endpoint_auth_signing_alg_values_supported?: Array<RevocationEndpointAuthSigningAlg>;
introspection_endpoint?: string;
code_challenge_methods_supported?: Array<PKCECodeChallengeMethod>;
pushed_authorization_request_endpoint?: string;
require_pushed_authorization_requests?: boolean;
'pre-authorized_grant_anonymous_access_supported': boolean;
dpop_signing_alg_values_supported?: (string | SigningAlgo)[];
frontchannel_logout_supported?: boolean;
frontchannel_logout_session_supported?: boolean;
backchannel_logout_supported?: boolean;
backchannel_logout_session_supported?: boolean;
userinfo_endpoint?: string;
check_session_iframe?: string;
end_session_endpoint?: string;
acr_values_supported?: string[];
subject_types_supported?: string[];
request_object_signing_alg_values_supported?: string[];
display_values_supported?: string[];
claim_types_supported?: string[];
claims_supported?: string[];
claims_parameter_supported?: boolean;
credential_endpoint?: string;
deferred_credential_endpoint?: string;
[x: string]: any;
}
declare const authorizationServerMetadataFieldNames: Array<keyof AuthorizationServerMetadata>;
declare enum WellKnownEndpoints {
OPENID_CONFIGURATION = "/.well-known/openid-configuration",
OAUTH_AS = "/.well-known/oauth-authorization-server",
OPENID4VCI_ISSUER = "/.well-known/openid-credential-issuer"
}
type AuthorizationServerType = 'OIDC' | 'OAuth 2.0' | 'OID4VCI';
interface EndpointMetadata {
issuer: string;
token_endpoint: string;
credential_endpoint: string;
deferred_credential_endpoint?: string;
authorization_server?: string;
authorization_endpoint?: string;
authorization_challenge_endpoint?: string;
}
interface StateType {
createdAt: number;
expiresAt?: number;
}
interface CredentialOfferSession extends StateType {
clientId?: string;
credentialOffer: AssertedUniformCredentialOffer;
credentialDataSupplierInput?: CredentialDataSupplierInput;
txCode?: string;
status: IssueStatus;
error?: string;
lastUpdatedAt: number;
notification_id: string;
notification?: NotificationRequest;
issuerState?: string;
preAuthorizedCode?: string;
authorizationCode?: string;
redirectUri?: string;
statusLists?: Array<StatusListOpts>;
}
declare enum IssueStatus {
OFFER_CREATED = "OFFER_CREATED",// An offer is created. This is the initial state
ACCESS_TOKEN_REQUESTED = "ACCESS_TOKEN_REQUESTED",// Optional state, given the token endpoint could also be on a separate AS
ACCESS_TOKEN_CREATED = "ACCESS_TOKEN_CREATED",// Optional state, given the token endpoint could also be on a separate AS
CREDENTIAL_REQUEST_RECEIVED = "CREDENTIAL_REQUEST_RECEIVED",// Credential request received. Next state would either be error or issued
CREDENTIAL_ISSUED = "CREDENTIAL_ISSUED",// The credential iss issued from the issuer's perspective
NOTIFICATION_CREDENTIAL_ACCEPTED = "NOTIFICATION_CREDENTIAL_ACCEPTED",// The holder/user stored the credential in the wallet (If notifications are enabled)
NOTIFICATION_CREDENTIAL_DELETED = "NOTIFICATION_CREDENTIAL_DELETED",// The holder/user did not store the credential in the wallet (If notifications are enabled)
NOTIFICATION_CREDENTIAL_FAILURE = "NOTIFICATION_CREDENTIAL_FAILURE",// The holder/user encountered an error (If notifications are enabled)
ERROR = "ERROR"
}
interface CNonceState extends StateType {
cNonce: string;
issuerState?: string;
preAuthorizedCode?: string;
}
interface URIState extends StateType {
issuerState?: string;
preAuthorizedCode?: string;
uri: string;
correlationId?: string;
}
interface IssueStatusResponse {
createdAt: number;
lastUpdatedAt: number;
expiresAt?: number;
status: IssueStatus;
error?: string;
clientId?: string;
statusLists?: Array<StatusListOpts>;
}
interface IStateManager<T extends StateType> {
set(id: string, stateValue: T): Promise<void>;
get(id: string): Promise<T | undefined>;
has(id: string): Promise<boolean>;
delete(id: string): Promise<boolean>;
clearExpired(timestamp?: number): Promise<void>;
clearAll(): Promise<void>;
getAsserted(id: string): Promise<T>;
startCleanupRoutine(timeout?: number): Promise<void>;
stopCleanupRoutine(): Promise<void>;
}
interface CredentialRequestV1_0_08 {
type: string;
format: CredentialFormat;
proof?: ProofOfPossession;
}
interface IssuerMetadataV1_0_08 {
issuer?: string;
credential_endpoint: string;
credentials_supported: CredentialSupportedTypeV1_0_08;
credential_issuer?: {
display: NameAndLocale | NameAndLocale[];
};
authorization_server?: string;
token_endpoint?: string;
display?: MetadataDisplay[];
[x: string]: unknown;
}
interface CredentialOfferPayloadV1_0_08 {
issuer: string;
credential_type: string[] | string;
'pre-authorized_code'?: string;
user_pin_required?: boolean | string;
op_state?: string;
}
interface CredentialSupportedTypeV1_0_08 {
[credentialType: string]: CredentialSupportedV1_0_08;
}
interface CredentialSupportedFormatV1_0_08 extends CredentialSupportedBrief {
name?: string;
types: string[];
}
interface CredentialSupportedV1_0_08 {
display?: CredentialsSupportedDisplay[];
formats: {
[credentialFormat: string]: CredentialSupportedFormatV1_0_08;
};
claims?: IssuerCredentialSubject;
}
interface ComponentOptions {
/**
* Component options for data/ECC.
*/
data?: {
/**
* Scale factor for data/ECC dots.
* @default 1
*/
scale?: number;
};
/**
* Component options for timing patterns.
*/
timing?: {
/**
* Scale factor for timing patterns.
* @default 1
*/
scale?: number;
/**
* Protector for timing patterns.
* @default false
*/
protectors?: boolean;
};
/**
* Component options for alignment patterns.
*/
alignment?: {
/**
* Scale factor for alignment patterns.
* @default 1
*/
scale?: number;
/**
* Protector for alignment patterns.
* @default false
*/
protectors?: boolean;
};
/**
* Component options for alignment pattern on the bottom-right corner.
*/
cornerAlignment?: {
/**
* Scale factor for alignment pattern on the bottom-right corner.
* @default 1
*/
scale?: number;
/**
* Protector for alignment pattern on the bottom-right corner.
* @default true
*/
protectors?: boolean;
};
}
interface QRCodeOpts {
/**
* Size of the QR code in pixel.
*
* @defaultValue 400
*/
size?: number;
/**
* Size of margins around the QR code body in pixel.
*
* @defaultValue 20
*/
margin?: number;
/**
* Error correction level of the QR code.
*
* Accepts a value provided by _QRErrorCorrectLevel_.
*
* For more information, please refer to [https://www.qrcode.com/en/about/error_correction.html](https://www.qrcode.com/en/about/error_correction.html).
*
* @defaultValue 0
*/
correctLevel?: number;
/**
* **This is an advanced option.**
*
* Specify the mask pattern to be used in QR code encoding.
*
* Accepts a value provided by _QRMaskPattern_.
*
* To find out all eight mask patterns, please refer to [https://en.wikipedia.org/wiki/File:QR_Code_Mask_Patterns.svg](https://en.wikipedia.org/wiki/File:QR_Code_Mask_Patterns.svg)
*
* For more information, please refer to [https://en.wikiversity.org/wiki/Reed%E2%80%93Solomon_codes_for_coders#Masking](https://en.wikiversity.org/wiki/Reed%E2%80%93Solomon_codes_for_coders#Masking).
*/
maskPattern?: number;
/**
* **This is an advanced option.**
*
* Specify the version to be used in QR code encoding.
*
* Accepts an integer in range [1, 40].
*
* For more information, please refer to [https://www.qrcode.com/en/about/version.html](https://www.qrcode.com/en/about/version.html).
*/
version?: number;
/**
* Options to control components in the QR code.
*
* @deafultValue undefined
*/
components?: ComponentOptions;
/**
* Color of the blocks on the QR code.
*
* Accepts a CSS <color>.
*
* For more information about CSS <color>, please refer to [https://developer.mozilla.org/en-US/docs/Web/CSS/color_value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
*
* @defaultValue "#000000"
*/
colorDark?: string;
/**
* Color of the empty areas on the QR code.
*
* Accepts a CSS <color>.
*
* For more information about CSS <color>, please refer to [https://developer.mozilla.org/en-US/docs/Web/CSS/color_value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
*
* @defaultValue "#ffffff"
*/
colorLight?: string;
/**
* Automatically calculate the _colorLight_ value from the QR code's background.
*
* @defaultValue true
*/
autoColor?: boolean;
/**
* Background image to be used in the QR code.
*
* Accepts a `data:` string in web browsers or a Buffer in Node.js.
*
* @defaultValue undefined
*/
backgroundImage?: string | Buffer;
/**
* Color of the dimming mask above the background image.
*
* Accepts a CSS <color>.
*
* For more information about CSS <color>, please refer to [https://developer.mozilla.org/en-US/docs/Web/CSS/color_value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
*
* @defaultValue "rgba(0, 0, 0, 0)"
*/
backgroundDimming?: string;
/**
* GIF background image to be used in the QR code.
*
* @defaultValue undefined
*/
gifBackground?: ArrayBuffer;
/**
* Use a white margin instead of a transparent one which reveals the background of the QR code on margins.
*
* @defaultValue true
*/
whiteMargin?: boolean;
/**
* Logo image to be displayed at the center of the QR code.
*
* Accepts a `data:` string in web browsers or a Buffer in Node.js.
*
* When set to `undefined` or `null`, the logo is disabled.
*
* @defaultValue undefined
*/
logoImage?: string | Buffer;
/**
* Ratio of the logo size to the QR code size.
*
* @defaultValue 0.2
*/
logoScale?: number;
/**
* Size of margins around the logo image in pixels.
*
* @defaultValue 6
*/
logoMargin?: number;
/**
* Corner radius of the logo image in pixels.
*
* @defaultValue 8
*/
logoCornerRadius?: number;
/**
* @deprecated
*
* Ratio of the real size to the full size of the blocks.
*
* This can be helpful when you want to make more parts of the background visible.
*
* @deafultValue 0.4
*/
dotScale?: number;
}
interface AccessTokenRequestOptsV1_0_11 {
credentialOffer?: UniformCredentialOffer;
credentialIssuer?: string;
asOpts?: AuthorizationServerOpts;
metadata?: EndpointMetadata;
codeVerifier?: string;
code?: string;
redirectUri?: string;
pin?: string;
}
interface CredentialOfferV1_0_11 {
credential_offer?: CredentialOfferPayloadV1_0_11;
credential_offer_uri?: string;
}
interface CredentialOfferRESTRequestV1_0_11 extends CredentialOfferV1_0_11 {
baseUri?: string;
scheme?: string;
pinLength?: number;
qrCodeOpts?: QRCodeOpts;
credentialDataSupplierInput?: CredentialDataSupplierInput;
}
interface CredentialOfferRequestWithBaseUrlV1_0_11 extends UniformCredentialOfferRequest {
scheme: string;
clientId?: string;
baseUrl: string;
userPinRequired: boolean;
issuerState?: string;
preAuthorizedCode?: string;
}
interface CredentialOfferPayloadV1_0_11 {
/**
* REQUIRED. The URL of the Credential Issuer, the Wallet is requested to obtain one or more Credentials from.
*/
credential_issuer: string;
/**
* REQUIRED. A JSON array, where every entry is a JSON object or a JSON string. If the entry is an object,
* the object contains the data related to a certain credential type the Wallet MAY request.
* Each object MUST contain a format Claim determining the format of the credential to be requested and
* further parameters characterising the type of the credential to be requested as defined in Appendix E.
* If the entry is a string, the string value MUST be one of the id values in one of the objects in the
* credentials_supported Credential Issuer metadata parameter.
* When processing, the Wallet MUST resolve this string value to the respective object.
*/
credentials: (CredentialOfferFormatV1_0_11 | string)[];
/**
* OPTIONAL. A JSON object indicating to the Wallet the Grant Types the Credential Issuer's AS is prepared
* to process for this credential offer. Every grant is represented by a key and an object.
* The key value is the Grant Type identifier, the object MAY contain parameters either determining the way
* the Wallet MUST use the particular grant and/or parameters the Wallet MUST send with the respective request(s).
* If grants is not present or empty, the Wallet MUST determine the Grant Types the Credential Issuer's AS supports
* using the respective metadata. When multiple grants are present, it's at the Wallet's discretion which one to use.
*/
grants?: Grant;
/**
* Some implementations might include a client_id in the offer. For instance EBSI in a same-device flow. (Cross-device tucks it in the state JWT)
*/
client_id?: string;
}
type CredentialRequestV1_0_11 = CommonCredentialRequest & (CredentialRequestJwtVcJson | CredentialRequestJwtVcJsonLdAndLdpVc | CredentialRequestSdJwtVc);
interface CredentialIssuerMetadataV1_0_11 extends CredentialIssuerMetadataOpts, Partial<AuthorizationServerMetadata> {
authorization_servers?: string[];
credential_endpoint: string;
credential_response_encryption_alg_values_supported?: string;
credential_response_encryption_enc_values_supported?: string;
require_credential_response_encryption?: boolean;
credential_identifiers_supported?: boolean;
}
interface AuthorizationRequestV1_0_11 extends AuthorizationDetailsJwtVcJson, AuthorizationDetailsJwtVcJson {
issuer_state?: string;
}
declare function isAuthorizationRequestV1_0_11(request: CommonAuthorizationRequest): boolean;
interface EndpointMetadataResultV1_0_11 extends EndpointMetadata {
authorizationServerType: AuthorizationServerType;
authorizationServerMetadata?: AuthorizationServerMetadata;
credentialIssuerMetadata?: Partial<AuthorizationServerMetadata> & IssuerMetadataV1_0_08;
}
interface IssuerMetadataV1_0_13 {
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_13>;
credential_issuer: string;
credential_endpoint: string;
authorization_servers?: string[];
deferred_credential_endpoint?: string;
notification_endpoint?: string;
credential_response_encryption?: ResponseEncryption;
token_endpoint?: string;
display?: MetadataDisplay[];
authorization_challenge_endpoint?: string;
[x: string]: unknown;
}
type CredentialDefinitionJwtVcJsonV1_0_13 = {
type: string[];
credentialSubject?: IssuerCredentialSubject;
};
type CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_13 = {
'@context': string[];
type: string[];
credentialSubject?: IssuerCredentialSubject;
};
type CredentialConfigurationSupportedV1_0_13 = CredentialConfigurationSupportedCommonV1_0_13 & (CredentialConfigurationSupportedSdJwtVcV1_0_13 | CredentialConfigurationSupportedJwtVcJsonV1_0_13 | CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_13 | CredentialConfigurationSupportedMsoMdocV1_0_13);
type CredentialConfigurationSupportedCommonV1_0_13 = {
format: OID4VCICredentialFormat | 'string';
scope?: string;
cryptographic_binding_methods_supported?: string[];
credential_signing_alg_values_supported?: string[];
proof_types_supported?: ProofTypesSupported;
display?: CredentialsSupportedDisplay[];
[x: string]: unknown;
};
interface CredentialConfigurationSupportedSdJwtVcV1_0_13 extends CredentialConfigurationSupportedCommonV1_0_13 {
format: 'vc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
order?: string[];
}
interface CredentialConfigurationSupportedMsoMdocV1_0_13 extends CredentialConfigurationSupportedCommonV1_0_13 {
format: 'mso_mdoc';
doctype: string;
claims?: IssuerCredentialSubject;
order?: string[];
}
interface CredentialConfigurationSupportedJwtVcJsonV1_0_13 extends CredentialConfigurationSupportedCommonV1_0_13 {
format: 'jwt_vc_json' | 'jwt_vc';
credential_definition: CredentialDefinitionJwtVcJsonV1_0_13;
order?: string[];
}
interface CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_13 extends CredentialConfigurationSupportedCommonV1_0_13 {
format: 'ldp_vc' | 'jwt_vc_json-ld';
credential_definition: CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_13;
order?: string[];
}
type CredentialRequestV1_0_13ResponseEncryption = {
jwk: JWK;
alg: AlgValue;
enc: EncValue;
};
interface CredentialRequestV1_0_13Common extends ExperimentalSubjectIssuance {
credential_response_encryption?: CredentialRequestV1_0_13ResponseEncryption;
proof?: ProofOfPossession;
issuer_state?: string;
}
type CredentialRequestV1_0_13 = CredentialRequestV1_0_13Common & (CredentialRequestJwtVcJsonV1_0_13 | CredentialRequestJwtVcJsonLdAndLdpVcV1_0_13 | CredentialRequestSdJwtVc | CredentialRequestMsoMdoc | CredentialRequestV1_0_13CredentialIdentifier);
/**
* Normally a proof always needs to be present. There are exceptions for certain issuers doing strong user binding part of presentation flows
*/
type CredentialRequestWithoutProofV1_0_13 = Omit<CredentialRequestV1_0_13Common, 'proof'> & (CredentialRequestJwtVcJsonV1_0_13 | CredentialRequestJwtVcJsonLdAndLdpVcV1_0_13 | CredentialRequestSdJwtVc | CredentialRequestMsoMdoc | CredentialRequestV1_0_13CredentialIdentifier);
interface CredentialRequestV1_0_13CredentialIdentifier extends CredentialRequestV1_0_13Common {
format?: undefined;
credential_identifier: string;
}
interface CredentialRequestJwtVcJsonV1_0_13 extends CommonCredentialRequest {
format: 'jwt_vc_json' | 'jwt_vc';
credential_definition: CredentialDefinitionJwtVcJsonV1_0_13;
}
interface CredentialRequestJwtVcJsonLdAndLdpVcV1_0_13 extends CommonCredentialRequest {
format: 'ldp_vc' | 'jwt_vc_json-ld';
credential_definition: CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_13;
}
interface CredentialOfferV1_0_13 {
credential_offer?: CredentialOfferPayloadV1_0_13;
credential_offer_uri?: string;
}
interface CredentialOfferRESTRequest extends Partial<CredentialOfferPayloadV1_0_13> {
redirectUri?: string;
baseUri?: string;
scheme?: string;
correlationId?: string;
sessionLifeTimeInSec?: number;
pinLength?: number;
qrCodeOpts?: QRCodeOpts;
client_id?: string;
credentialDataSupplierInput?: CredentialDataSupplierInput;
statusListOpts?: Array<StatusListOpts>;
offerMode?: CredentialOfferMode;
}
interface CredentialOfferPayloadV1_0_13 {
/**
* REQUIRED. The URL of the Credential Issuer, as defined in Section 11.2.1, from which the Wallet is requested to
* obtain one or more Credentials. The Wallet uses it to obtain the Credential Issuer's Metadata following the steps
* defined in Section 11.2.2.
*/
credential_issuer: string;
/**
* REQUIRED. Array of unique strings that each identify one of the keys in the name/value pairs stored in
* the credential_configurations_supported Credential Issuer metadata. The Wallet uses these string values
* to obtain the respective object that contains information about the Credential being offered as defined
* in Section 11.2.3. For example, these string values can be used to obtain scope values to be used in
* the Authorization Request.
*/
credential_configuration_ids: string[];
/**
* OPTIONAL. A JSON object indicating to the Wallet the Grant Types the Credential Issuer's AS is prepared
* to process for this credential offer. Every grant is represented by a key and an object.
* The key value is the Grant Type identifier, the object MAY contain parameters either determining the way
* the Wallet MUST use the particular grant and/or parameters the Wallet MUST send with the respective request(s).
* If grants is not present or empty, the Wallet MUST determine the Grant Types the Credential Issuer's AS supports
* using the respective metadata. When multiple grants are present, it's at the Wallet's discretion which one to use.
*/
grants?: Grant;
/**
* Some implementations might include a client_id in the offer. For instance EBSI in a same-device flow. (Cross-device tucks it in the state JWT)
*/
client_id?: string;
}
interface CredentialIssuerMetadataOptsV1_0_13 {
credential_endpoint: string;
batch_credential_endpoint?: string;
deferred_credential_endpoint?: string;
notification_endpoint?: string;
credential_response_encryption?: ResponseEncryption;
credential_identifiers_supported?: boolean;
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_13>;
credential_issuer: string;
authorization_servers?: string[];
signed_metadata?: string;
display?: MetadataDisplay[];
authorization_challenge_endpoint?: string;
token_endpoint?: string;
credential_supplier_config?: CredentialSupplierConfig;
}
declare const credentialIssuerMetadataFieldNames: Array<keyof CredentialIssuerMetadataOptsV1_0_13>;
interface EndpointMetadataResultV1_0_13 extends EndpointMetadata {
authorizationServerType: AuthorizationServerType;
authorizationServerMetadata?: AuthorizationServerMetadata;
credentialIssuerMetadata?: Partial<AuthorizationServerMetadata> & IssuerMetadataV1_0_13;
}
interface CredentialIssuerMetadataV1_0_13 extends CredentialIssuerMetadataOptsV1_0_13, Partial<AuthorizationServerMetadata> {
authorization_servers?: string[];
credential_endpoint: string;
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_13>;
credential_issuer: string;
credential_response_encryption_alg_values_supported?: string;
credential_response_encryption_enc_values_supported?: string;
require_credential_response_encryption?: boolean;
credential_identifiers_supported?: boolean;
}
type InputCharSet = 'numeric' | 'text';
type KeyProofType = 'jwt' | 'cwt' | 'ldp_vp';
type PoPMode = 'pop' | 'JWT';
type CredentialOfferMode = 'VALUE' | 'REFERENCE';
/**
* Important Note: please be aware that these Common interfaces are based on versions v1_0.11 and v1_0.09
*/
interface ImageInfo {
url?: string;
alt_text?: string;
[key: string]: unknown;
}
type OID4VCICredentialFormat = 'jwt_vc_json' | 'jwt_vc_json-ld' | 'ldp_vc' | 'vc+sd-jwt' | 'jwt_vc' | 'mso_mdoc';
interface NameAndLocale {
name?: string;
locale?: string;
[key: string]: unknown;
}
interface LogoAndColor {
logo?: ImageInfo;
description?: string;
background_color?: string;
text_color?: string;
}
type CredentialsSupportedDisplay = NameAndLocale & LogoAndColor & {
name: string;
background_image?: ImageInfo;
};
type MetadataDisplay = NameAndLocale & LogoAndColor & {
name?: string;
};
interface CredentialSupplierConfig {
[key: string]: any;
}
interface CredentialIssuerMetadataOpts {
credential_endpoint?: string;
batch_credential_endpoint?: string;
credentials_supported: CredentialsSupportedLegacy[];
credential_issuer: string;
authorization_server?: string;
token_endpoint?: string;
notification_endpoint?: string;
authorization_challenge_endpoint?: string;
display?: MetadataDisplay[];
credential_supplier_config?: CredentialSupplierConfig;
}
type AlgValue = 'RS256' | 'ES256' | 'PS256' | 'HS256' | string;
type EncValue = 'A128GCM' | 'A256GCM' | 'A128CBC-HS256' | 'A256CBC-HS512' | string;
interface ResponseEncryption {
/**
* REQUIRED. Array containing a list of the JWE [RFC7516] encryption algorithms
* (alg values) [RFC7518] supported by the Credential and Batch Credential Endpoint to encode the
* Credential or Batch Credential Response in a JWT
*/
alg_values_supported: AlgValue[];
/**
* REQUIRED. Array containing a list of the JWE [RFC7516] encryption algorithms
* (enc values) [RFC7518] supported by the Credential and Batch Credential Endpoint to encode the
* Credential or Batch Credential Response in a JWT
*/
enc_values_supported: EncValue[];
/**
* REQUIRED. Boolean value specifying whether the Credential Issuer requires the
* additional encryption on top of TLS for the Credential Response. If the value is true, the Credential
* Issuer requires encryption for every Credential Response and therefore the Wallet MUST provide
* encryption keys in the Credential Request. If the value is false, the Wallet MAY chose whether it
* provides encryption keys or not.
*/
encryption_required: boolean;
}
interface CredentialIssuerMetadata extends CredentialIssuerMetadataOpts, Partial<AuthorizationServerMetadata> {
authorization_servers?: string[];
credential_endpoint: string;
credential_configurations_supported: Record<string, CredentialConfigurationSupported>;
credential_issuer: string;
credential_response_encryption_alg_values_supported?: string;
credential_response_encryption_enc_values_supported?: string;
require_credential_response_encryption?: boolean;
credential_identifiers_supported?: boolean;
}
interface CredentialSupportedBrief {
cryptographic_binding_methods_supported?: string[];
cryptographic_suites_supported?: string[];
}
interface ProofType {
proof_signing_alg_values_supported: string[];
}
type ProofTypesSupported = {
[key in KeyProofType]?: ProofType;
};
type CommonCredentialSupported = CredentialSupportedBrief & ExperimentalSubjectIssuance & {
format: OID4VCICredentialFormat | string;
id?: string;
display?: CredentialsSupportedDisplay[];
scope?: string;
proof_types_supported?: ProofTypesSupported;
};
interface CredentialSupportedJwtVcJsonLdAndLdpVc extends CommonCredentialSupported {
types: string[];
'@context': ICredentialContextType[];
credentialSubject?: IssuerCredentialSubject;
order?: string[];
format: 'ldp_vc' | 'jwt_vc_json-ld';
}
interface CredentialSupportedJwtVcJson extends CommonCredentialSupported {
types: string[];
credentialSubject?: IssuerCredentialSubject;
order?: string[];
format: 'jwt_vc_json' | 'jwt_vc';
}
interface CredentialSupportedSdJwtVc extends CommonCredentialSupported {
format: 'vc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
order?: string[];
}
interface CredentialSupportedMsoMdoc extends CommonCredentialSupported {
format: 'mso_mdoc';
doctype: string;
claims?: IssuerCredentialSubject;
order?: string[];
}
type CredentialConfigurationSupported = CredentialConfigurationSupportedV1_0_13 | (CommonCredentialSupported & (CredentialSupportedJwtVcJson | CredentialSupportedJwtVcJsonLdAndLdpVc | CredentialSupportedSdJwtVc | CredentialSupportedMsoMdoc));
type CredentialsSupportedLegacy = CommonCredentialSupported & (CredentialSupportedJwtVcJson | CredentialSupportedJwtVcJsonLdAndLdpVc | CredentialSupportedSdJwtVc | CredentialSupportedMsoMdoc);
interface CommonCredentialOfferFormat {
format: OID4VCICredentialFormat | string;
}
interface CredentialOfferFormatJwtVcJsonLdAndLdpVc extends CommonCredentialOfferFormat {
format: 'ldp_vc' | 'jwt_vc_json-ld';
credential_definition: JsonLdIssuerCredentialDefinition;
}
interface CredentialOfferFormatJwtVcJson extends CommonCredentialOfferFormat {
format: 'jwt_vc_json' | 'jwt_vc';
types: string[];
}
interface CredentialOfferFormatSdJwtVc extends CommonCredentialOfferFormat {
format: 'vc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
}
interface CredentialOfferFormatMsoMdoc extends CommonCredentialOfferFormat {
format: 'mso_mdoc';
doctype: string;
claims?: IssuerCredentialSubject;
}
type CredentialOfferFormatV1_0_11 = CommonCredentialOfferFormat & (CredentialOfferFormatJwtVcJsonLdAndLdpVc | CredentialOfferFormatJwtVcJson | CredentialOfferFormatSdJwtVc | CredentialOfferFormatMsoMdoc);
/**
* Optional storage that can help the credential Data Supplier. For instance to store credential input data during offer creation, if no additional data can be supplied later on
*/
type CredentialDataSupplierInput = any;
type CreateCredentialOfferURIResult = {
uri: string;
correlationId: string;
qrCodeDataUri?: string;
session: CredentialOfferSession;
userPin?: string;
txCode?: TxCode;
};
interface JsonLdIssuerCredentialDefinition {
'@context': ICredentialContextType[];
types: string[];
credentialSubject?: IssuerCredentialSubject;
}
interface ErrorResponse {
error: string;
error_description?: string;
error_uri?: string;
state?: string;
}
type UniformCredentialRequest = CredentialRequestV1_0_11 | CredentialRequestV1_0_13;
interface CommonCredentialRequest extends ExperimentalSubjectIssuance {
format: OID4VCICredentialFormat;
proof?: ProofOfPossession;
}
interface CredentialRequestJwtVcJson extends CommonCredentialRequest {
format: 'jwt_vc_json' | 'jwt_vc';
types: string[];
credentialSubject?: IssuerCredentialSubject;
}
interface CredentialRequestJwtVcJsonLdAndLdpVc extends CommonCredentialRequest {
format: 'ldp_vc' | 'jwt_vc_json-ld';
credential_definition: JsonLdIssuerCredentialDefinition;
}
interface CredentialRequestSdJwtVc extends CommonCredentialRequest {
format: 'vc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
}
interface CredentialRequestMsoMdoc extends CommonCredentialRequest {
format: 'mso_mdoc';
doctype: string;
claims?: IssuerCredentialSubject;
}
interface CommonCredentialResponse extends ExperimentalSubjectIssuance {
credential?: W3CVerifiableCredential;
acceptance_token?: string;
c_nonce?: string;
c_nonce_expires_in?: string;
}
interface CredentialResponseLdpVc extends CommonCredentialResponse {
credential: IVerifiableCredential;
}
interface CredentialResponseJwtVc {
credential: string;
}
interface CredentialResponseSdJwtVc {
credential: string;
}
type IssuerCredentialSubjectDisplay = CredentialSubjectDisplay & {
[key: string]: CredentialSubjectDisplay;
};
interface CredentialSubjectDisplay {
mandatory?: boolean;
value_type?: string;
display?: NameAndLocale[];
}
interface IssuerCredentialSubject {
[key: string]: IssuerCredentialSubjectDisplay;
}
interface Grant {
authorization_code?: GrantAuthorizationCode;
[PRE_AUTH_GRANT_LITERAL]?: GrantUrnIetf;
}
interface GrantAuthorizationCode {
/**
* OPTIONAL. String value created by the Credential Issuer and opaque to the Wallet that is used to bind the subsequent
* Authorization Request with the Credential Issuer to a context set up during previous steps.
*/
issuer_state?: string;
/**
* OPTIONAL string that the Wallet can use to identify the Authorization Server to use with this grant type when authorization_servers parameter in the Credential Issuer metadata has multiple entries. MUST NOT be used otherwise. The value of this parameter MUST match with one of the values in the authorization_servers array obtained from the Credential Issuer metadata
*/
authorization_server?: string;
}
interface TxCode {
/**
* OPTIONAL. String specifying the input character set. Possible values are numeric (only digits) and text (any characters). The default is numeric.
*/
input_mode?: InputCharSet;
/**
* OPTIONAL. Integer specifying the length of the Transaction Code. This helps the Wallet to render the input screen and improve the user experience.
*/
length?: number;
/**
* OPTIONAL. String containing guidance for the Holder of the Wallet on how to obtain the Transaction Code, e.g.,
* describing over which communication channel it is delivered. The Wallet is RECOMMENDED to display this description
* next to the Transaction Code input screen to improve the user experience. The length of the string MUST NOT exceed
* 300 characters. The description does not support internationalization, however the Issuer MAY detect the Holder's
* language by previous communication or an HTTP Accept-Language header within an HTTP GET request for a Credential Offer URI.
*/
description?: string;
}
interface GrantUrnIetf {
/**
* REQUIRED. The code representing the Credential Issuer's authorization for the Wallet to obtain Credentials of a certain type.
*/
'pre-authorized_code': string;
/**
* OPTIONAL. Object specifying whether the Authorization Server expects presentation of a Transaction Code by the
* End-User along with the Token Request in a Pre-Authorized Code Flow. If the Authorization Server does not expect a
* Transaction Code, this object is absent; this is the default. The Transaction Code is intended to bind the Pre-Authorized
* Code to a certain transaction to prevent replay of this code by an attacker that, for example, scanned the QR code while
* standing behind the legitimate End-User. It is RECOMMENDED to send the Transaction Code via a separate channel. If the Wallet
* decides to use the Pre-Authorized Code Flow, the Transaction Code value MUST be sent in the tx_code parameter with
* the respective Token Request as defined in Section 6.1. If no length or description is given, this object may be empty,
* indicating that a Transaction Code is required.
*/
tx_code?: TxCode;
/**
* OPTIONAL. The minimum amount of time in seconds that the Wallet SHOULD wait between polling requests to the token endpoint (in case the Authorization Server responds with error code authorization_pending - see Section 6.3). If no value is provided, Wallets MUST use 5 as the default.
*/
interval?: number;
/**
* OPTIONAL string that the Wallet can use to identify the Authorization Server to use with this grant type when authorization_servers parameter in the Credential Issuer metadata has multiple entries. MUST NOT be used otherwise. The value of this parameter MUST match with one of the values in the authorization_servers array obtained from the Credential Issuer metadata
*/
authorization_server?: string;
/**
* OPTIONAL. Boolean value specifying whether the AS
* expects presentation of the End-User PIN along with the Token Request
* in a Pre-Authorized Code Flow. Default is false. This PIN is intended
* to bind the Pre-Authorized Code to a certain transaction to prevent
* replay of this code by an attacker that, for example, scanned the QR
* code while standing behind the legitimate End-User. It is RECOMMENDED
* to send a PIN via a separate channel. If the Wallet decides to use
* the Pre-Authorized Code Flow, a PIN value MUST be sent in
* the user_pin parameter with the respective Token Request.
*/
user_pin_required?: boolean;
}
declare const PRE_AUTH_CODE_LITERAL = "pre-authorized_code";
declare const PRE_AUTH_GRANT_LITERAL = "urn:ietf:params:oauth:grant-type:pre-authorized_code";
type EndpointMetadataResult = EndpointMetadataResultV1_0_13 | EndpointMetadataResultV1_0_11;
type IssuerMetadata = IssuerMetadataV1_0_13 | IssuerMetadataV1_0_08;
type NotificationEventType = 'credential_accepted' | 'credential_failure' | 'credential_deleted';
interface NotificationRequest {
notification_id: string;
event: NotificationEventType | string;
event_description?: string;
credential?: any;
}
type NotificationError = 'invalid_notification_id' | 'invalid_notification_request';
type NotificationResponseResult = {
error: boolean;
response?: NotificationErrorResponse;
};
interface NotificationErrorResponse {
error: NotificationError | string;
}
interface StatusListOpts {
statusListId?: string;
statusListCorrelationId?: string;
statusListIndex?: number;
statusEntryCorrelationId?: string;
}
declare enum OpenId4VCIVersion {
VER_1_0_08 = 1008,
VER_1_0_09 = 1009,
VER_1_0_11 = 1011,
VER_1_0_12 = 1012,
VER_1_0_13 = 1013,
VER_UNKNOWN
}
declare enum DefaultURISchemes {
INITIATE_ISSUANCE = "openid-initiate-issuance",
CREDENTIAL_OFFER = "openid-credential-offer"
}
interface CredentialOfferV1_0_09 {
credential_offer: CredentialOfferPayloadV1_0_09;
}
interface CredentialOfferPayloadV1_0_09 {
/**
* REQUIRED. The URL of the Credential Issuer, the Wallet is requested to obtain one or more Credentials from.
*/
issuer: string;
/**
* REQUIRED. A JSON array, where every entry is a JSON object or a JSON string. If the entry is an object,
* the object contains the data related to a certain credential type the Wallet MAY request.
* Each object MUST contain a format Claim determining the format of the credential to be requested and
* further parameters characterising the type of the credential to be requested as defined in Appendix E.
* If the entry is a string, the string value MUST be one of the id values in one of the objects in the
* credentials_supported Credential Issuer metadata parameter.
* When processing, the Wallet MUST resolve this string value to the respective object.
*/
credentials: (CredentialOfferFormatV1_0_11 | string)[];
'pre-authorized_code'?: string;
user_pin_required?: boolean | string;
op_state?: string;
}
interface AuthorizationRequestV1_0_09 extends CommonAuthorizationRequest {
op_state?: string;
}
declare function isAuthorizationRequestV1_0_09(request: CommonAuthorizationRequest): boolean;
interface CredentialResponse extends ExperimentalSubjectIssuance {
credential?: IVerifiableCredential | string;
format?: OID4VCICredentialFormat;
transaction_id?: string;
acceptance_token?: string;
c_nonce?: string;
c_nonce_expires_in?: number;
notification_id?: string;
}
interface CredentialOfferRequestWithBaseUrl extends UniformCredentialOfferRequest {
scheme: string;
clientId?: string;
baseUrl: string;
txCode?: TxCode;
issuerState?: string;
preAuthorizedCode?: string;
userPinRequired: boolean;
}
type CredentialOffer = CredentialOfferV1_0_09 | CredentialOfferV1_0_11 | CredentialOfferV1_0_13;
type CredentialOfferPayloadLatest = CredentialOfferPayloadV1_0_13;
type CredentialRequest = UniformCredentialRequest | CredentialRequestV1_0_13 | CredentialRequestV1_0_11 | CredentialRequestV1_0_08;
type CredentialOfferPayload = (CredentialOfferPayloadV1_0_08 | CredentialOfferPayloadV1_0_09 | CredentialOfferPayloadV1_0_11 | CredentialOfferPayloadV1_0_13) & {
[x: string]: any;
};
interface AssertedUniformCredentialOffer extends UniformCredentialOffer {
credential_offer: UniformCredentialOfferPayload;
}
interface UniformCredentialOffer {
credential_offer?: UniformCredentialOfferPayload;
credential_offer_uri?: string;
}
interface UniformCredentialOfferRequest extends AssertedUniformCredentialOffer {
original_credential_offer: CredentialOfferPayload;
version: OpenId4VCIVersion;
supportedFlows: AuthzFlowType[];
}
type UniformCredentialOfferPayload = CredentialOfferPayloadV1_0_11 | CredentialOfferPayloadV1_0_13;
interface ProofOfPossession {
proof_type: 'jwt';
jwt: string;
[x: string]: unknown;
}
type SearchValue = {
[Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string;
};
declare enum JsonURIMode {
JSON_STRINGIFY = 0,
X_FORM_WWW_URLENCODED = 1
}
type EncodeJsonAsURIOpts = {
uriTypeProperties?: string[];
arrayTypeProperties?: string[];
baseUrl?: string;
param?: string;
mode?: JsonURIMode;
version?: OpenId4VCIVersion;
};
type DecodeURIAsJsonOpts = {
requiredProperties?: string[];
arrayTypeProperties?: string[];
};
interface Jwt {
header: JWTHeader;
payload: JWTPayload;
}
interface ProofOfPossessionCallbacks {
signCallback: JWTSignerCallback;
verifyCallback?: JWTVerifyCallback;
}
/**
* Signature algorithms.
*
* TODO: Move towards string literal unions and string type, given we do not provide signature/key implementations in this library to begin with
* @See: https://github.com/Sphereon-Opensource/OID4VC/issues/88
*/
declare enum Alg {
EdDSA = "EdDSA",
ES256 = "ES256",
ES256K = "ES256K",
PS256 = "PS256",
PS384 = "PS384",
PS512 = "PS512",
RS256 = "RS256",
RS384 = "RS384",
RS512 = "RS512"
}
type Typ = 'JWT' | 'openid4vci-proof+jwt';
interface JoseHeaderParameters {
kid?: string;
x5t?: string;
x5c?: string[];
x5u?: string;
jku?: string;
jwk?: BaseJWK;
typ?: string;
cty?: string;
}
interface JWSHeaderParameters extends JoseHeaderParameters {
alg?: Alg | string;
b64?: boolean;
crit?: string[];
[propName: string]: unknown;
}
interface CompactJWSHeaderParameters extends JWSHeaderParameters {
alg: string;
}
interface JWTHeaderParameters extends CompactJWSHeaderParameters {
b64?: true;
}
type JWTHeader = JWTHeaderParameters;
interface JWTPayload {
iss?: string;
aud?: string | string[];
iat?: number;
nonce?: string;
jti?: string;
exp?: number;
client_id?: string;
[s: string]: unknown;
}
type JWTSignerCallback = (jwt: Jwt, kid?: string) => Promise<string>;
type JWTVerifyCallback = (args: {
jwt: string;
kid?: string;
}) => Promise<JwtVerifyResult>;
interface JwtVerifyResult {
jwt: Jwt;
kid?: string;
alg?: string;
did?: string;
didDocument?: Record<string, unknown>;
x5c?: string[];
jwk?: BaseJWK;
}
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;
}
interfac