kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs | README

swiyu_taler_sequence_diagram.txt (3630B)

      1 sequenceDiagram
      2     title Swiyu-Taler Interaction
      3 
      4     participant Browser
      5     participant TalerWallet
      6     participant Exchange
      7     participant KyCH OAuth2 Gateway
      8     participant SwiyuVerifier
      9     participant SwiyuWallet
     10 
     11     TalerWallet ->> Exchange: Initiate KYC-requiring operation
     12     Exchange -->> TalerWallet: Send verification link
     13     TalerWallet ->> Browser: Open link
     14     Browser ->> Exchange: Select verification method (Swiyu)
     15 
     16     note over Exchange,KyCH OAuth2 Gateway: Exchange initiates KYC verification process
     17     Exchange ->> KyCH OAuth2 Gateway: POST /setup/{client_id}\nAuthorization: Bearer $CLIENT_SECRET
     18     KyCH OAuth2 Gateway -->> Exchange: {nonce: $NONCE}
     19     Exchange ->> Browser: Displays /authorize link to user
     20 
     21     Browser ->> KyCH OAuth2 Gateway: GET /authorize/{nonce}\n?response_type=code\n&client_id={client_id}\n&redirect_uri={redirect_uri}\n&state={state}\n&scope={scope}
     22     KyCH OAuth2 Gateway ->> SwiyuVerifier: POST /management/api/verifications\n(Creates verification request for {scope})
     23     SwiyuVerifier -->> KyCH OAuth2 Gateway: {verification_url, id, state: PENDING}
     24     KyCH OAuth2 Gateway -->> Browser: HTML page\n(verification_url, verification_id, state)\nQR code + swiyu deeplink encode verification_url
     25 
     26 
     27     loop Poll until status is "verified" or "failed"
     28         Browser ->> KyCH OAuth2 Gateway: GET /status/{verification_id}\n?state={state}
     29         KyCH OAuth2 Gateway -->> Browser: {status: "pending" | "authorized"}
     30     end
     31 
     32     Browser ->> SwiyuWallet: Open $VERIFICATION_URL\n(scan QR or open swiyu wallet deeplink)
     33     SwiyuWallet ->> SwiyuVerifier: GET /oid4vp/api/request-object/{request_id} (DCQL Query)
     34     SwiyuVerifier -->> SwiyuWallet: Verification Presentation definition
     35     SwiyuWallet ->> SwiyuVerifier: GET verifier_metadata
     36     SwiyuVerifier -->> SwiyuWallet: return metadata
     37     SwiyuWallet ->> SwiyuWallet: User grants permission
     38     SwiyuWallet ->> SwiyuVerifier: POST /oid4vp/api/request-object/{request_id}/response-data\n(VP Token)
     39 
     40     note over KyCH OAuth2 Gateway,SwiyuVerifier: KyCH OAuth2 Gateway receives webhook\nand retrieves wallet response
     41     SwiyuVerifier ->> KyCH OAuth2 Gateway: POST /notification\n{verification_id, timestamp}
     42     KyCH OAuth2 Gateway ->> SwiyuVerifier: GET /management/api/verifications/{verification_id}
     43     SwiyuVerifier -->> KyCH OAuth2 Gateway: {status: SUCCESS/FAILED,\nwallet_response}
     44 
     45     note over Browser,KyCH OAuth2 Gateway: /authorize page detects completion and redirects
     46     Browser ->> KyCH OAuth2 Gateway: GET /status/{verification_id}\n?state={state}
     47     KyCH OAuth2 Gateway -->> Browser: {status: "verified"}
     48     Browser ->> Browser: /authorize JS redirects to /finalize
     49     Browser ->> KyCH OAuth2 Gateway: GET /finalize/{verification_id}\n?state={state}
     50     KyCH OAuth2 Gateway -->> Browser: HTTP 302 Redirect\nLocation: {redirect_uri}?code={auth_code}&state={state}
     51     Browser ->> Exchange: GET {redirect_uri}\n?code={auth_code}\n&state={state}
     52 
     53     note over Exchange,KyCH OAuth2 Gateway: Exchange retrieves the Verifiable Credential
     54     Exchange ->> KyCH OAuth2 Gateway: POST /token\nContent-Type: application/x-www-form-urlencoded\ngrant_type=authorization_code\n&code={auth_code}\n&client_id={client_id}\n&client_secret={client_secret}
     55     KyCH OAuth2 Gateway -->> Exchange: {access_token,\ntoken_type: "Bearer",\nexpires_in}
     56     Exchange ->> KyCH OAuth2 Gateway: GET /info\nAuthorization: Bearer $ACCESS_TOKEN
     57     KyCH OAuth2 Gateway -->> Exchange: $VERIFIABLE_CREDENTIAL
     58 
     59     Exchange -->> TalerWallet: Notify success
     60     TalerWallet ->> Exchange: Retry KYC-requiring original operation