@sphereon/ssi-sdk.oid4vci-holder 0.32.1-next.20 → 0.32.1-next.291

package/src/agent/OID4VCIHolder.ts

@@ -4,6 +4,8 @@ import {
   AuthorizationRequestOpts,
   AuthorizationServerClientOpts,
   AuthorizationServerOpts,
+  CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_13,
+  CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_13,
   CredentialOfferRequestWithBaseUrl,
   DefaultURISchemes,
   EndpointMetadataResult,
@@ -45,7 +47,7 @@ import {
 } from '@sphereon/ssi-sdk.data-store'
 import {
   CredentialMapper,
-  Hasher,
+  HasherSync,
   IVerifiableCredential,
   JoseSignatureAlgorithm,
   JoseSignatureAlgorithmString,
@@ -70,12 +72,12 @@ import {
 import { asArray, computeEntryHash } from '@veramo/utils'
 import { decodeJWT } from 'did-jwt'
 import { v4 as uuidv4 } from 'uuid'
-import { OID4VCIMachine } from '../machine/oid4vciMachine'
+import { OID4VCIMachine } from '../machines/oid4vciMachine'
 import {
   AddContactIdentityArgs,
   AssertValidCredentialsArgs,
   Attribute,
-  createCredentialsToSelectFromArgs,
+  CreateCredentialsToSelectFromArgs,
   CredentialToAccept,
   CredentialToSelectFromResult,
   GetContactArgs,
@@ -91,6 +93,8 @@ import {
   OID4VCIHolderOptions,
   OID4VCIMachine as OID4VCIMachineId,
   OID4VCIMachineInstanceOpts,
+  OID4VCIMachineServiceDefinitions,
+  OID4VCIMachineServices,
   OnContactIdentityCreatedArgs,
   OnCredentialStoredArgs,
   OnIdentifierCreatedArgs,
@@ -98,6 +102,7 @@ import {
   RequestType,
   RequiredContext,
   SendNotificationArgs,
+  StartFirstPartApplicationMachine,
   StartResult,
   StoreCredentialBrandingArgs,
   StoreCredentialsArgs,
@@ -114,10 +119,11 @@ import {
   getIssuanceOpts,
   mapCredentialToAccept,
   selectCredentialLocaleBranding,
+  startFirstPartApplicationMachine,
   verifyCredentialToAccept,
-} from './OID4VCIHolderService'
-
+} from '../services/OID4VCIHolderService'
 import 'cross-fetch/polyfill'
+import { defaultHasher } from '@sphereon/ssi-sdk.core'
 
 /**
  * {@inheritDoc IOID4VCIHolder}
@@ -199,7 +205,7 @@ export async function verifyEBSICredentialIssuer(args: VerifyEBSICredentialIssue
 }
 
 export class OID4VCIHolder implements IAgentPlugin {
-  private readonly hasher?: Hasher
+  private readonly hasher?: HasherSync
   readonly eventTypes: Array<OID4VCIHolderEvent> = [
     OID4VCIHolderEvent.CONTACT_IDENTITY_CREATED,
     OID4VCIHolderEvent.CREDENTIAL_STORED,
@@ -261,7 +267,7 @@ export class OID4VCIHolder implements IAgentPlugin {
       didMethodPreferences,
       jwtCryptographicSuitePreferences,
       defaultAuthorizationRequestOptions,
-      hasher,
+      hasher = defaultHasher,
     } = { ...options }
 
     this.hasher = hasher
@@ -307,8 +313,8 @@ export class OID4VCIHolder implements IAgentPlugin {
    */
   private async oid4vciHolderGetMachineInterpreter(opts: OID4VCIMachineInstanceOpts, context: RequiredContext): Promise<OID4VCIMachineId> {
     const authorizationRequestOpts = { ...this.defaultAuthorizationRequestOpts, ...opts.authorizationRequestOpts }
-    const services = {
-      start: (args: PrepareStartArgs) =>
+    const services: OID4VCIMachineServiceDefinitions = {
+      [OID4VCIMachineServices.start]: (args: PrepareStartArgs) =>
         this.oid4vciHolderStart(
           {
             ...args,
@@ -316,18 +322,22 @@ export class OID4VCIHolder implements IAgentPlugin {
           },
           context,
         ),
-      createCredentialsToSelectFrom: (args: createCredentialsToSelectFromArgs) => this.oid4vciHolderCreateCredentialsToSelectFrom(args, context),
-      getContact: (args: GetContactArgs) => this.oid4vciHolderGetContact(args, context),
-      getCredentials: (args: GetCredentialsArgs) =>
+      [OID4VCIMachineServices.startFirstPartApplicationFlow]: (args: StartFirstPartApplicationMachine) =>
+        startFirstPartApplicationMachine({ ...args, stateNavigationListener: opts.firstPartyStateNavigationListener }, context),
+      [OID4VCIMachineServices.createCredentialsToSelectFrom]: (args: CreateCredentialsToSelectFromArgs) =>
+        this.oid4vciHolderCreateCredentialsToSelectFrom(args, context),
+      [OID4VCIMachineServices.getContact]: (args: GetContactArgs) => this.oid4vciHolderGetContact(args, context),
+      [OID4VCIMachineServices.getCredentials]: (args: GetCredentialsArgs) =>
         this.oid4vciHolderGetCredentials({ accessTokenOpts: args.accessTokenOpts ?? opts.accessTokenOpts, ...args }, context),
-      addContactIdentity: (args: AddContactIdentityArgs) => this.oid4vciHolderAddContactIdentity(args, context),
-      getIssuerBranding: (args: GetIssuerBrandingArgs) => this.oid4vciHolderGetIssuerBranding(args, context),
-      storeIssuerBranding: (args: StoreIssuerBrandingArgs) => this.oid4vciHolderStoreIssuerBranding(args, context),
-      assertValidCredentials: (args: AssertValidCredentialsArgs) => this.oid4vciHolderAssertValidCredentials(args, context),
-      storeCredentialBranding: (args: StoreCredentialBrandingArgs) => this.oid4vciHolderStoreCredentialBranding(args, context),
-      storeCredentials: (args: StoreCredentialsArgs) => this.oid4vciHolderStoreCredentials(args, context),
-      sendNotification: (args: SendNotificationArgs) => this.oid4vciHolderSendNotification(args, context),
-      getFederationTrust: (args: GetFederationTrustArgs) => this.getFederationTrust(args, context),
+      [OID4VCIMachineServices.addContactIdentity]: (args: AddContactIdentityArgs) => this.oid4vciHolderAddContactIdentity(args, context),
+      [OID4VCIMachineServices.getIssuerBranding]: (args: GetIssuerBrandingArgs) => this.oid4vciHolderGetIssuerBranding(args, context),
+      [OID4VCIMachineServices.storeIssuerBranding]: (args: StoreIssuerBrandingArgs) => this.oid4vciHolderStoreIssuerBranding(args, context),
+      [OID4VCIMachineServices.assertValidCredentials]: (args: AssertValidCredentialsArgs) => this.oid4vciHolderAssertValidCredentials(args, context),
+      [OID4VCIMachineServices.storeCredentialBranding]: (args: StoreCredentialBrandingArgs) =>
+        this.oid4vciHolderStoreCredentialBranding(args, context),
+      [OID4VCIMachineServices.storeCredentials]: (args: StoreCredentialsArgs) => this.oid4vciHolderStoreCredentials(args, context),
+      [OID4VCIMachineServices.sendNotification]: (args: SendNotificationArgs) => this.oid4vciHolderSendNotification(args, context),
+      [OID4VCIMachineServices.getFederationTrust]: (args: GetFederationTrustArgs) => this.getFederationTrust(args, context),
     }
 
     const oid4vciMachineInstanceArgs: OID4VCIMachineInstanceOpts = {
@@ -463,7 +473,7 @@ export class OID4VCIHolder implements IAgentPlugin {
   }
 
   private async oid4vciHolderCreateCredentialsToSelectFrom(
-    args: createCredentialsToSelectFromArgs,
+    args: CreateCredentialsToSelectFromArgs,
     context: RequiredContext,
   ): Promise<Array<CredentialToSelectFromResult>> {
     const { credentialBranding, locale, selectedCredentials /*, openID4VCIClientState*/, credentialsSupported } = args
@@ -629,7 +639,7 @@ export class OID4VCIHolder implements IAgentPlugin {
     // The VCI lib either expects a jwk or a kid
     const jwk = isManagedIdentifierJwkResult(identifier) ? identifier.jwk : undefined
 
-    const callbacks: ProofOfPossessionCallbacks<never> = {
+    const callbacks: ProofOfPossessionCallbacks = {
       signCallback: signCallback(identifier, context),
     }
 
@@ -675,7 +685,10 @@ export class OID4VCIHolder implements IAgentPlugin {
       if (!credentialTypes || credentialTypes.length === 0) {
         return Promise.reject(Error('cannot determine credential id to request'))
       }
+
+      const credentialDefinition = this.getCredentialDefinition(issuanceOpt)
       const credentialResponse = await client.acquireCredentials({
+        ...(credentialDefinition && { context: credentialDefinition['@context'] }),
         credentialTypes,
         proofCallbacks: callbacks,
         format: issuanceOpt.format,
@@ -908,7 +921,7 @@ export class OID4VCIHolder implements IAgentPlugin {
           : 'credential_deleted_holder_signed'
         logger.log(`Subject issuance/signing will be used, with event`, event)
         const issuerVC = mappedCredentialToAccept.credentialToAccept.credentialResponse.credential as OriginalVerifiableCredential
-        const wrappedIssuerVC = CredentialMapper.toWrappedVerifiableCredential(issuerVC, { hasher: this.hasher })
+        const wrappedIssuerVC = CredentialMapper.toWrappedVerifiableCredential(issuerVC, { hasher: this.hasher ?? defaultHasher })
         console.log(`Wrapped VC: ${wrappedIssuerVC.type}, ${wrappedIssuerVC.format}`)
         // We will use the subject of the VCI Issuer (the holder, as the issuer of the new credential, so the below is not a mistake!)
 
@@ -1075,6 +1088,11 @@ export class OID4VCIHolder implements IAgentPlugin {
     const params = new URLSearchParams(url.search)
     const openidFederation = params.get('openid_federation')
     const entityIdentifier = openidFederation ?? serverMetadata.issuer
+    if (entityIdentifier.startsWith('http://')) {
+      console.warn(`OpenID federation does not support http://, only https:// allowed; got: (${url.toString()})`)
+      // OIDF always needs to be https
+      return []
+    }
 
     const result = await context.agent.identifierExternalResolveByOIDFEntityId({
       method: 'entity_id',
@@ -1127,4 +1145,11 @@ export class OID4VCIHolder implements IAgentPlugin {
     }
     return undefined
   }
+
+  private getCredentialDefinition(issuanceOpt: IssuanceOpts): CredentialDefinitionJwtVcJsonLdAndLdpVcV1_0_13 | undefined {
+    if (issuanceOpt.format == 'ldp_vc' || issuanceOpt.format == 'jwt_vc_json-ld') {
+      return (issuanceOpt as CredentialConfigurationSupportedJwtVcJsonLdAndLdpVcV1_0_13).credential_definition
+    }
+    return undefined
+  }
 }

package/src/index.ts

@@ -3,7 +3,10 @@
  */
 
 export { OID4VCIHolder, oid4vciHolderContextMethods, signCallback } from './agent/OID4VCIHolder'
-export * from './agent/OID4VCIHolderService'
+export * from './mappers/OIDC4VCIBrandingMapper'
+export * from './services/OID4VCIHolderService'
+export * from './services/FirstPartyMachineServices'
 export * from './types/IOID4VCIHolder'
-export * from './machine/headlessStateNavListener'
+export * from './types/FirstPartyMachine'
+export * from './listeners/headlessStateNavListener'
 export * from './link-handler'

package/src/link-handler/index.ts

@@ -3,23 +3,26 @@ import { AuthorizationRequestOpts, AuthorizationServerClientOpts, AuthzFlowType,
 import { DefaultLinkPriorities, LinkHandlerAdapter } from '@sphereon/ssi-sdk.core'
 import { IMachineStatePersistence, interpreterStartOrResume, SerializableState } from '@sphereon/ssi-sdk.xstate-machine-persistence'
 import { IAgentContext } from '@veramo/core'
-import { GetMachineArgs, IOID4VCIHolder, OID4VCIMachineEvents, OID4VCIMachineInterpreter, OID4VCIMachineState } from '../types/IOID4VCIHolder'
+import { GetMachineArgs, IOID4VCIHolder, OID4VCIMachineEvents, OID4VCIMachineStateNavigationListener } from '../types/IOID4VCIHolder'
+import { FirstPartyMachineStateNavigationListener } from '../types/FirstPartyMachine'
 
 /**
  * This handler only handles credential offer links (either by value or by reference)
  */
 export class OID4VCIHolderLinkHandler extends LinkHandlerAdapter {
   private readonly context: IAgentContext<IOID4VCIHolder & IMachineStatePersistence>
-  private readonly stateNavigationListener:
-    | ((oid4vciMachine: OID4VCIMachineInterpreter, state: OID4VCIMachineState, navigation?: any) => Promise<void>)
-    | undefined
+  private readonly stateNavigationListener?: OID4VCIMachineStateNavigationListener
+  private readonly firstPartyStateNavigationListener?: FirstPartyMachineStateNavigationListener
   private readonly noStateMachinePersistence: boolean
   private readonly authorizationRequestOpts?: AuthorizationRequestOpts
   private readonly clientOpts?: AuthorizationServerClientOpts
   private readonly trustAnchors?: Array<string>
 
   constructor(
-    args: Pick<GetMachineArgs, 'stateNavigationListener' | 'authorizationRequestOpts' | 'clientOpts' | 'trustAnchors'> & {
+    args: Pick<
+      GetMachineArgs,
+      'stateNavigationListener' | 'authorizationRequestOpts' | 'clientOpts' | 'trustAnchors' | 'firstPartyStateNavigationListener'
+    > & {
       priority?: number | DefaultLinkPriorities
       protocols?: Array<string | RegExp>
       noStateMachinePersistence?: boolean
@@ -32,6 +35,7 @@ export class OID4VCIHolderLinkHandler extends LinkHandlerAdapter {
     this.context = args.context
     this.noStateMachinePersistence = args.noStateMachinePersistence === true
     this.stateNavigationListener = args.stateNavigationListener
+    this.firstPartyStateNavigationListener = args.firstPartyStateNavigationListener
     this.trustAnchors = args.trustAnchors
   }
 
@@ -63,6 +67,7 @@ export class OID4VCIHolderLinkHandler extends LinkHandlerAdapter {
       authorizationRequestOpts: { ...this.authorizationRequestOpts, ...opts?.authorizationRequestOpts },
       ...((clientOpts.clientId || clientOpts.clientAssertionType) && { clientOpts: clientOpts as AuthorizationServerClientOpts }),
       stateNavigationListener: this.stateNavigationListener,
+      firstPartyStateNavigationListener: this.firstPartyStateNavigationListener,
     })
 
     const interpreter = oid4vciMachine.interpreter

package/src/localization/translations/en.json

@@ -11,5 +11,9 @@
   "oid4vci_machine_initiation_error_title": "Initiate OID4VCI provider",
   "oid4vci_machine_credential_verification_failed_message": "The credential verification resulted in an error.",
   "oid4vci_machine_credential_verification_schema_failed_message": "The credential schema verification resulted in an error.",
-  "oid4vci_machine_retrieve_federation_trust_error_title": "Retrieve federation trust"
+  "oid4vci_machine_retrieve_federation_trust_error_title": "Retrieve federation trust",
+  "oid4vci_machine_first_party_error_title": "First party flow",
+  "oid4vci_machine_send_authorization_challenge_request_error_title": "Sending authorization challenge request",
+  "oid4vci_machine_create_config_error_title": "Creating siopV2 config",
+  "oid4vci_machine_get_request_error_title": "Getting siopV2 request"
 }

package/src/localization/translations/nl.json

@@ -10,5 +10,9 @@
   "oid4vci_machine_credential_selection_error_title": "Credential selectie",
   "oid4vci_machine_initiation_error_title": "Initiëren OID4VCI provider",
   "oid4vci_machine_credential_verification_failed_message": "Verificatie van de credential leidde tot een fout.",
-  "oid4vci_machine_retrieve_federation_trust_error_title": "Ophalen federatievertrouwen"
+  "oid4vci_machine_retrieve_federation_trust_error_title": "Ophalen federatievertrouwen",
+  "oid4vci_machine_first_party_error_title": "Eerste partijstroom",
+  "oid4vci_machine_send_authorization_challenge_request_error_title": "Versturen autorisatie-uitdaging aanvraag",
+  "oid4vci_machine_create_config_error_title": "SiopV2-configuratie aanmaken",
+  "oid4vci_machine_get_request_error_title": "SiopV2-verzoek ophalen"
 }

package/src/machines/firstPartyMachine.ts

@@ -0,0 +1,278 @@
+import { assign, createMachine, DoneInvokeEvent, interpret } from 'xstate'
+import { AuthorizationChallengeCodeResponse, AuthorizationChallengeError, AuthorizationChallengeErrorResponse } from '@sphereon/oid4vci-common'
+import { DidAuthConfig } from '@sphereon/ssi-sdk.data-store'
+import { CreateConfigResult } from '@sphereon/ssi-sdk.siopv2-oid4vp-op-auth'
+import { createConfig, getSiopRequest, sendAuthorizationChallengeRequest, sendAuthorizationResponse } from '../services/FirstPartyMachineServices'
+import { translate } from '../localization/Localization'
+import { ErrorDetails } from '../types/IOID4VCIHolder'
+import {
+  CreateConfigArgs,
+  CreateFirstPartyMachineOpts,
+  FirstPartyMachineContext,
+  FirstPartyMachineEvents,
+  FirstPartyMachineEventTypes,
+  FirstPartyMachineInterpreter,
+  FirstPartyMachineServices,
+  FirstPartyMachineState,
+  FirstPartyMachineStatesConfig,
+  FirstPartyMachineStateTypes,
+  FirstPartyMachineServiceDefinitions,
+  FirstPartyStateMachine,
+  GetSiopRequestArgs,
+  InstanceFirstPartyMachineOpts,
+  SiopV2AuthorizationRequestData,
+  SendAuthorizationResponseArgs,
+  FirstPartySelectCredentialsEvent,
+} from '../types/FirstPartyMachine'
+
+const firstPartyMachineStates: FirstPartyMachineStatesConfig = {
+  [FirstPartyMachineStateTypes.sendAuthorizationChallengeRequest]: {
+    id: FirstPartyMachineStateTypes.sendAuthorizationChallengeRequest,
+    invoke: {
+      src: FirstPartyMachineServices.sendAuthorizationChallengeRequest,
+      onDone: {
+        target: FirstPartyMachineStateTypes.done,
+        actions: assign({
+          authorizationCodeResponse: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<AuthorizationChallengeCodeResponse>) => _event.data,
+        }),
+      },
+      onError: [
+        {
+          target: FirstPartyMachineStateTypes.createConfig,
+          cond: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<AuthorizationChallengeErrorResponse>): boolean =>
+            _event.data.error === AuthorizationChallengeError.insufficient_authorization,
+          actions: assign({
+            authSession: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<AuthorizationChallengeErrorResponse>) => _event.data.auth_session,
+            presentationUri: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<AuthorizationChallengeErrorResponse>) =>
+              _event.data.presentation,
+          }),
+        },
+        {
+          target: FirstPartyMachineStateTypes.error,
+          actions: assign({
+            error: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<Error>): ErrorDetails => ({
+              title: translate('oid4vci_machine_send_authorization_challenge_request_error_title'),
+              message: _event.data.message,
+              stack: _event.data.stack,
+            }),
+          }),
+        },
+      ],
+    },
+  },
+  [FirstPartyMachineStateTypes.createConfig]: {
+    id: FirstPartyMachineStateTypes.createConfig,
+    invoke: {
+      src: FirstPartyMachineServices.createConfig,
+      onDone: {
+        target: FirstPartyMachineStateTypes.getSiopRequest,
+        actions: assign({
+          didAuthConfig: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<DidAuthConfig>) => _event.data,
+        }),
+      },
+      onError: {
+        target: FirstPartyMachineStateTypes.error,
+        actions: assign({
+          error: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<Error>): ErrorDetails => ({
+            title: translate('oid4vci_machine_create_config_error_title'),
+            message: _event.data.message,
+            stack: _event.data.stack,
+          }),
+        }),
+      },
+    },
+  },
+  [FirstPartyMachineStateTypes.getSiopRequest]: {
+    id: FirstPartyMachineStateTypes.getSiopRequest,
+    invoke: {
+      src: FirstPartyMachineServices.getSiopRequest,
+      onDone: {
+        target: FirstPartyMachineStateTypes.selectCredentials,
+        actions: assign({
+          authorizationRequestData: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<SiopV2AuthorizationRequestData>) => _event.data,
+        }),
+      },
+      onError: {
+        target: FirstPartyMachineStateTypes.error,
+        actions: assign({
+          error: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<Error>): ErrorDetails => ({
+            title: translate('siopV2_machine_get_request_error_title'),
+            message: _event.data.message,
+            stack: _event.data.stack,
+          }),
+        }),
+      },
+    },
+  },
+  [FirstPartyMachineStateTypes.selectCredentials]: {
+    id: FirstPartyMachineStateTypes.selectCredentials,
+    on: {
+      [FirstPartyMachineEvents.SET_SELECTED_CREDENTIALS]: {
+        actions: assign({ selectedCredentials: (_ctx: FirstPartyMachineContext, _event: FirstPartySelectCredentialsEvent) => _event.data }),
+      },
+      [FirstPartyMachineEvents.NEXT]: {
+        target: FirstPartyMachineStateTypes.sendAuthorizationResponse,
+      },
+      [FirstPartyMachineEvents.DECLINE]: {
+        target: FirstPartyMachineStateTypes.declined,
+      },
+      [FirstPartyMachineEvents.PREVIOUS]: {
+        target: FirstPartyMachineStateTypes.aborted,
+      },
+    },
+  },
+  [FirstPartyMachineStateTypes.sendAuthorizationResponse]: {
+    id: FirstPartyMachineStateTypes.sendAuthorizationResponse,
+    invoke: {
+      src: FirstPartyMachineServices.sendAuthorizationResponse,
+      onDone: {
+        target: FirstPartyMachineStateTypes.sendAuthorizationChallengeRequest,
+        actions: assign({
+          presentationDuringIssuanceSession: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<string>) => _event.data,
+        }),
+      },
+      onError: {
+        target: FirstPartyMachineStateTypes.error,
+        actions: assign({
+          error: (_ctx: FirstPartyMachineContext, _event: DoneInvokeEvent<Error>): ErrorDetails => ({
+            title: translate('oid4vci_machine_get_request_error_title'),
+            message: _event.data.message,
+            stack: _event.data.stack,
+          }),
+        }),
+      },
+    },
+  },
+  [FirstPartyMachineStateTypes.aborted]: {
+    id: FirstPartyMachineStateTypes.aborted,
+    type: 'final',
+  },
+  [FirstPartyMachineStateTypes.declined]: {
+    id: FirstPartyMachineStateTypes.declined,
+    type: 'final',
+  },
+  [FirstPartyMachineStateTypes.error]: {
+    id: FirstPartyMachineStateTypes.error,
+    type: 'final',
+  },
+  [FirstPartyMachineStateTypes.done]: {
+    id: FirstPartyMachineStateTypes.done,
+    type: 'final',
+  },
+}
+
+const createFirstPartyActivationMachine = (opts: CreateFirstPartyMachineOpts): FirstPartyStateMachine => {
+  const initialContext: FirstPartyMachineContext = {
+    openID4VCIClientState: opts.openID4VCIClientState,
+    contact: opts.contact,
+    selectedCredentials: [],
+  }
+
+  return createMachine<FirstPartyMachineContext, FirstPartyMachineEventTypes>({
+    id: opts?.machineId ?? 'FirstParty',
+    predictableActionArguments: true,
+    initial: FirstPartyMachineStateTypes.sendAuthorizationChallengeRequest,
+    context: initialContext,
+    states: firstPartyMachineStates,
+    schema: {
+      events: {} as FirstPartyMachineEventTypes,
+      services: {} as {
+        [FirstPartyMachineServices.sendAuthorizationChallengeRequest]: {
+          data: void
+        }
+        [FirstPartyMachineServices.createConfig]: {
+          data: CreateConfigResult
+        }
+        [FirstPartyMachineServices.getSiopRequest]: {
+          data: SiopV2AuthorizationRequestData
+        }
+        [FirstPartyMachineServices.sendAuthorizationResponse]: {
+          data: string
+        }
+      },
+    },
+  })
+}
+
+export class FirstPartyMachine {
+  private static _instance: FirstPartyMachineInterpreter | undefined
+
+  static hasInstance(): boolean {
+    return FirstPartyMachine._instance !== undefined
+  }
+
+  static get instance(): FirstPartyMachineInterpreter {
+    if (!FirstPartyMachine._instance) {
+      throw Error('Please initialize ESIMActivation machine first')
+    }
+    return FirstPartyMachine._instance
+  }
+
+  static clearInstance(opts: { stop: boolean }) {
+    const { stop } = opts
+    if (FirstPartyMachine.hasInstance()) {
+      if (stop) {
+        FirstPartyMachine.stopInstance()
+      }
+    }
+    FirstPartyMachine._instance = undefined
+  }
+
+  static stopInstance(): void {
+    if (!FirstPartyMachine.hasInstance()) {
+      return
+    }
+    FirstPartyMachine.instance.stop()
+    FirstPartyMachine._instance = undefined
+  }
+
+  public static newInstance(opts: InstanceFirstPartyMachineOpts): FirstPartyMachineInterpreter {
+    const { agentContext } = opts
+    const services: FirstPartyMachineServiceDefinitions = {
+      [FirstPartyMachineServices.sendAuthorizationChallengeRequest]: sendAuthorizationChallengeRequest,
+      [FirstPartyMachineServices.createConfig]: (args: CreateConfigArgs) => createConfig(args, agentContext),
+      [FirstPartyMachineServices.getSiopRequest]: (args: GetSiopRequestArgs) => getSiopRequest(args, agentContext),
+      [FirstPartyMachineServices.sendAuthorizationResponse]: (args: SendAuthorizationResponseArgs) => sendAuthorizationResponse(args, agentContext),
+    }
+
+    const newInst: FirstPartyMachineInterpreter = interpret(
+      createFirstPartyActivationMachine(opts).withConfig({
+        services: {
+          ...services,
+          ...opts?.services,
+        },
+        guards: {
+          ...opts?.guards,
+        },
+      }),
+    )
+
+    if (typeof opts?.subscription === 'function') {
+      newInst.onTransition(opts.subscription)
+    }
+
+    if (opts?.requireCustomNavigationHook !== true) {
+      newInst.onTransition((snapshot: FirstPartyMachineState): void => {
+        if (opts?.stateNavigationListener) {
+          void opts.stateNavigationListener(newInst, snapshot)
+        }
+      })
+    }
+
+    return newInst
+  }
+
+  static getInstance(
+    opts: InstanceFirstPartyMachineOpts & {
+      requireExisting?: boolean
+    },
+  ): FirstPartyMachineInterpreter {
+    if (!FirstPartyMachine._instance) {
+      if (opts?.requireExisting === true) {
+        throw Error(`Existing FirstPartyMachine instance requested, but none was created at this point!`)
+      }
+      FirstPartyMachine._instance = FirstPartyMachine.newInstance(opts)
+    }
+    return FirstPartyMachine._instance
+  }
+}