@sphereon/oid4vci-common
Version:
OpenID 4 Verifiable Credential Issuance Common Types
1,257 lines (1,247 loc) • 83.7 kB
TypeScript
import * as _sphereon_ssi_types from '@sphereon/ssi-types';
import { ICredentialContextType, W3CVerifiableCredential, IVerifiableCredential, CredentialFormat, 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;
nonce_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;
notification_endpoint?: string;
authorization_server?: string;
authorization_endpoint?: string;
authorization_challenge_endpoint?: string;
}
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 IssuerMetadataV1_0_15 {
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_15>;
credential_issuer: string;
credential_endpoint: string;
nonce_endpoint?: string;
authorization_servers?: string[];
deferred_credential_endpoint?: string;
notification_endpoint?: string;
credential_response_encryption?: ResponseEncryption;
batch_credential_issuance?: BatchCredentialIssuance;
token_endpoint?: string;
display?: MetadataDisplay[];
authorization_challenge_endpoint?: string;
signed_metadata?: string;
[x: string]: unknown;
}
interface BatchCredentialIssuance {
batch_size: number;
}
type CredentialDefinitionJwtVcJsonV1_0_15 = {
type: string[];
credentialSubject?: IssuerCredentialSubject;
};
type CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_15 = {
'@context': string[];
type: string[];
credentialSubject?: IssuerCredentialSubject;
};
type CredentialConfigurationSupportedV1_0_15 = CredentialConfigurationSupportedCommonV1_0_15 & (CredentialConfigurationSupportedSdJwtVcV1_0_15 | CredentialConfigurationSupportedJwtVcJsonV1_0_15 | CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_15 | CredentialConfigurationSupportedMsoMdocV1_0_15);
type CredentialConfigurationSupportedCommonV1_0_15 = {
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_15 extends CredentialConfigurationSupportedCommonV1_0_15 {
format: 'dc+sd-jwt' | 'vc+sd-jwt';
vct: string;
claims?: ClaimsDescriptionV1_0_15[];
order?: string[];
}
interface CredentialConfigurationSupportedMsoMdocV1_0_15 extends CredentialConfigurationSupportedCommonV1_0_15 {
format: 'mso_mdoc';
doctype: string;
claims?: ClaimsDescriptionV1_0_15[];
order?: string[];
}
interface CredentialConfigurationSupportedJwtVcJsonV1_0_15 extends CredentialConfigurationSupportedCommonV1_0_15 {
format: 'jwt_vc_json' | 'jwt_vc';
credential_definition: CredentialDefinitionJwtVcJsonV1_0_15;
claims?: ClaimsDescriptionV1_0_15[];
order?: string[];
}
interface CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_15 extends CredentialConfigurationSupportedCommonV1_0_15 {
format: 'ldp_vc' | 'jwt_vc_json-ld';
credential_definition: CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_15;
claims?: ClaimsDescriptionV1_0_15[];
order?: string[];
}
interface ClaimsDescriptionV1_0_15 {
path: (string | number | null)[];
mandatory?: boolean;
display?: CredentialsSupportedDisplay[];
}
type CredentialRequestV1_0_15ResponseEncryption = {
jwk: JWK;
alg: AlgValue;
enc: EncValue;
};
interface CredentialRequestV1_0_15Common extends ExperimentalSubjectIssuance {
credential_response_encryption?: CredentialRequestV1_0_15ResponseEncryption;
proof?: ProofOfPossession;
proofs?: ProofOfPossessionMap;
issuer_state?: string;
}
interface ProofOfPossessionMap {
[proofType: string]: ProofOfPossession[];
}
type CredentialRequestV1_0_15 = CredentialRequestV1_0_15Common & (CredentialRequestV1_0_15CredentialIdentifier | CredentialRequestV1_0_15CredentialConfigurationId);
interface CredentialRequestV1_0_15CredentialIdentifier extends CredentialRequestV1_0_15Common {
credential_identifier: string;
credential_configuration_id?: undefined;
}
interface CredentialRequestV1_0_15CredentialConfigurationId extends CredentialRequestV1_0_15Common {
credential_configuration_id: string;
credential_identifier?: undefined;
}
interface CredentialOfferV1_0_15 {
credential_offer?: CredentialOfferPayloadV1_0_15;
credential_offer_uri?: string;
}
interface CredentialOfferRESTRequestV1_0_15 extends Partial<CredentialOfferPayloadV1_0_15> {
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_15 {
/**
* 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. Object indicating to the Wallet the Grant Types the Credential Issuer's Authorization Server is prepared
* to process for this Credential Offer. Every grant is represented by a name/value pair. The name is the Grant Type identifier;
* the value is an object that contains 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 is empty, the Wallet MUST determine
* the Grant Types the Credential Issuer's Authorization Server supports using the respective metadata. When multiple grants are present,
* it is at the Wallet's discretion which one to use.
*/
grants?: Grant;
/**
* OPTIONAL. 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 CredentialResponseV1_0_15 extends ExperimentalSubjectIssuance {
credentials?: CredentialResponseCredentialV1_0_15[];
transaction_id?: string;
notification_id?: string;
}
interface CredentialResponseCredentialV1_0_15 {
credential: string | object;
}
interface DeferredCredentialResponseV1_0_15 {
credentials: CredentialResponseCredentialV1_0_15[];
notification_id?: string;
}
interface TokenResponseV1_0_15 {
access_token: string;
token_type: string;
expires_in?: number;
refresh_token?: string;
scope?: string;
authorization_details?: AuthorizationDetailsV1_0_15[];
}
interface AuthorizationDetailsV1_0_15 {
type: 'openid_credential';
credential_configuration_id?: string;
credential_identifiers?: string[];
locations?: string[];
[x: string]: unknown;
}
interface NonceRequestV1_0_15 {
}
interface NonceResponseV1_0_15 {
c_nonce: string;
}
interface CredentialErrorResponseV1_0_15 {
error: string;
error_description?: string;
error_uri?: string;
}
interface ProofTypesV1_0_15 {
jwt?: ProofTypeV1_0_15;
ldp_vp?: ProofTypeV1_0_15;
attestation?: ProofTypeV1_0_15;
}
interface ProofTypeV1_0_15 {
proof_signing_alg_values_supported: string[];
key_attestations_required?: KeyAttestationsRequiredV1_0_15;
}
interface KeyAttestationsRequiredV1_0_15 {
key_storage?: string[];
user_authentication?: string[];
}
interface KeyAttestationJWT {
alg: string;
typ: 'keyattestation+jwt';
kid?: string;
x5c?: string[];
trust_chain?: string[];
iss?: string;
iat: number;
exp?: number;
attested_keys: JWK[];
key_storage?: string[];
user_authentication?: string[];
certification?: string;
nonce?: string;
status?: object;
}
interface WalletAttestationJWT {
typ: 'oauth-client-attestation+jwt';
alg: string;
kid?: string;
iss: string;
sub: string;
wallet_name?: string;
wallet_link?: string;
nbf?: number;
exp?: number;
cnf: {
jwk: JWK;
};
status?: object;
}
interface CredentialIssuerMetadataOptsV1_0_15 {
credential_endpoint: string;
nonce_endpoint?: string;
deferred_credential_endpoint?: string;
notification_endpoint?: string;
credential_response_encryption?: ResponseEncryption;
batch_credential_issuance?: BatchCredentialIssuance;
credential_identifiers_supported?: boolean;
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_15>;
credential_issuer: string;
authorization_servers?: string[];
signed_metadata?: string;
display?: MetadataDisplay[];
authorization_challenge_endpoint?: string;
token_endpoint?: string;
credential_supplier_config?: CredentialSupplierConfig;
}
declare const credentialIssuerMetadataFieldNamesV1_0_15: Array<keyof CredentialIssuerMetadataOptsV1_0_15>;
interface EndpointMetadataResultV1_0_15 extends EndpointMetadata {
authorizationServerType: AuthorizationServerType;
authorizationServerMetadata?: AuthorizationServerMetadata;
credentialIssuerMetadata?: Partial<AuthorizationServerMetadata> & IssuerMetadataV1_0_15;
}
interface CredentialIssuerMetadataV1_0_15 extends CredentialIssuerMetadataOptsV1_0_15, Partial<AuthorizationServerMetadata> {
authorization_servers?: string[];
credential_endpoint: string;
credential_configurations_supported: Record<string, CredentialConfigurationSupportedV1_0_15>;
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;
nonce_endpoint?: string;
}
interface NotificationResponseV1_0_15 {
}
interface NotificationErrorResponseV1_0_15 {
error: 'invalid_notification_id' | 'invalid_notification_request';
error_description?: string;
}
interface AuthorizationServerMetadataV1_0_15 extends AuthorizationServerMetadata {
'pre-authorized_grant_anonymous_access_supported'?: boolean;
}
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>;
authorizationDetails?: AuthorizationDetailsV1_0_15[];
}
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;
}
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>;
}
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 {
uri?: string;
alt_text?: string;
[key: string]: unknown;
}
type OID4VCICredentialFormat = 'jwt_vc_json' | 'jwt_vc_json-ld' | 'ldp_vc' | 'dc+sd-jwt' | 'vc+sd-jwt' | 'jwt_vc' | 'mso_mdoc';
declare const supportedOID4VCICredentialFormat: readonly (OID4VCICredentialFormat | string)[];
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: 'dc+sd-jwt' | 'vc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
order?: string[];
}
interface CredentialSupportedSdJwtVcV13 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_15 | (CommonCredentialSupported & (CredentialSupportedJwtVcJson | CredentialSupportedJwtVcJsonLdAndLdpVc | CredentialSupportedSdJwtVc | CredentialSupportedMsoMdoc));
type CredentialsSupportedLegacy = CommonCredentialSupported & (CredentialSupportedJwtVcJson | CredentialSupportedJwtVcJsonLdAndLdpVc | CredentialSupportedSdJwtVc | CredentialSupportedSdJwtVcV13 | 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: 'dc+sd-jwt';
vct: string;
claims?: IssuerCredentialSubject;
}
interface CredentialOfferFormatSdJwtVcv13 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 | CredentialOfferFormatSdJwtVcv13 | 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 CredentialRequest = CredentialRequestV1_0_15;
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: 'dc+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_15;
type IssuerMetadata = IssuerMetadataV1_0_15;
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_15 = 1015,
VER_UNKNOWN
}
declare enum DefaultURISchemes {
INITIATE_ISSUANCE = "openid-initiate-issuance",
CREDENTIAL_OFFER = "openid-credential-offer"
}
interface CredentialResponse extends ExperimentalSubjectIssuance {
credentials?: Array<CredentialResponseCredentialV1_0_15>;
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_15;
type CredentialOfferPayloadLatest = CredentialOfferPayloadV1_0_15;
type CredentialOfferPayload = CredentialOfferPayloadV1_0_15 & {
[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_15;
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, noIssPayloadUpdate?: boolean) => 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?: AuthorizationDetailsV1_0_15[] | AuthorizationDetailsV1_0_15;
/**
* 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;
}
interface CommonAuthorizationChallengeRequest {
/**
* REQUIRED if the client is not authenticating with the authorization server and if no auth_session is included..
*/
client_id?: 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. This request parameter is used to pass the
* issuer_state value back to the Credential Issuer.
*/
issuer_state?: string;
/**
* The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.
*/
scope?: string;
/**
* OPTIONAL. A random string or a JWE. The auth session allows the authorization server to associate subsequent
* requests by this client with an ongoing authorization request sequence. The client MUST include the
* auth_session in follow-up requests to the authorization challenge endpoint if it receives one along with
* the error response.
*/
auth_session?: string;
/**
* OPTIONAL. 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;
/**
* OPTIONAL. value must be set either to "S256" or a value defined by a cryptographically secure
*/
code_challenge_method?: CodeChallengeMethod;
/**
* OPTIONAL. String containing information about the session when credential presentation is happening during issuance of another
* credential. The content of this parameter is opaque to the wallet. When this parameter is present the Wallet MUST use this parameter in
* the subsequent Authorization Challenge Request. This allows the Issuer to determine which it can be used by to prevent session
* fixation attacks. The Response URI MAY return this parameter in response to successful Authorization Responses or for Error
* Responses.
*/
presentation_during_issuance_session?: string;
}
interface AuthorizationChallengeRequestOpts {
clientId?: string;
issuerState?: string;
authSession?: string;
scope?: string;
codeChallenge?: string;
codeChallengeMethod?: CodeChallengeMethod;
presentationDuringIssuanceSession?: string;
metadata?: EndpointMetadata;
credentialIssuer?: string;
}
interface AuthorizationChallengeErrorResponse {
/**
* A single ASCII error code of type AuthorizationChallengeError.
*/
error: AuthorizationChallengeError;
/**
* OPTIONAL. OPTIONAL. Human-readable ASCII text providing additional information, used
* to assist the client developer in understanding the error that occurred. Values for the error_description
* parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
*/
error_description?: string;
/**
* OPTIONAL. A URI identifying a human-readable web page with information about the error, used
* to provide the client developer with additional information about the error. Values for the error_uri
* parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the
* set %x21 / %x23-5B / %x5D-7E.
*/
error_uri?: string;
/**
* OPTIONAL. A random string or a JWE. The auth session allows the authorization server to associate subsequent
* requests by this client with a