# KnownCredential Issuance via Widget

## Direct Issuance

sequenceDiagram
autonumber

participant D as DIDPay
participant W as Widget
participant I as Issuance Server


D->>D: Generate DID. Store private key securely
D->>I: Get Challenge
I->>D: Challenge
D->>D: use challenge to compute ID Token
D->>D: sign ID Token
D->>W: Open Widget
W->>W: Renders KYC Form
W->>I: Submit Form
I->>W: KCC Cred or Reject
W->>D: callback with KCC Cred

### Example Widget URL

https://kyc.yellowcard.com?proof=${signed_id_token}&id_token=${id_token}&callback_uri=didpay://whatever

### Query Params

| Param | Value |
| -------------- | ---------------------------------- |
| `proof` | Signed ID token |
| `id_token` | ID Token |
| `callback_uri` | `didpay://something?vc=${kccCred}` |

## Deferred Issuance

sequenceDiagram
autonumber

participant D as DIDPay
participant W as Widget
participant I as Issuance Server


D->>D: Generate DID. Store private key securely
D->>I: Get Challenge
I->>D: Challenge
D->>D: use challenge to compute ID Token
D->>D: sign ID Token
D->>W: Open Widget
W->>W: Renders KYC Form
W->>I: Submit Form
I->>W: some token that can be used to request cred
W->>D: callback with credential request token
D->>I: indefinitely poll credential issuance server until a credential response is received

## Example Widget URL

https://kyc.yellowcard.com?proof=${signed_id_token}&id_token=${id_token}&callback_uri=didpay://whatever

### Query Params

| Param | Value |
| -------------- | ---------------------------------- |
| `proof` | Signed ID token |
| `id_token` | ID Token |
| `callback_uri` | `didpay://something?vc=${kccCred}` |

## Open Questions
* how do we get the Verifiable Credential? is it returned by the issuance server as a response to form submission? or do we need to go through some OID4VP flow directly in the mobile app?

## SIOPv2 + OID4VCI flow

We leverage [SIOPv2](https://openid.github.io/SIOPv2/openid-connect-self-issued-v2-wg-draft.html) to authenticate the end user and proivde proof of control over their DID. Next, we leverage the [OID4VCI](https://openid.github.io/OpenID4VCI/openid-4-verifiable-credential-issuance-wg-draft.html) protocol to perform credential issuance, after submitting a text-based web form.

### SIOPv2

* Builds upon the OAuth 2.0 flow [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce)
* We are leveraging the "Same Device Flow"
* Registration is static and uses the [Pre-Registered RP](https://openid.github.io/SIOPv2/openid-connect-self-issued-v2-wg-draft.html#pre-registered-rp)

### OID4VCI

* We leverage the [Authorization Code Flow](https://openid.github.io/OpenID4VCI/openid-4-verifiable-credential-issuance-wg-draft.html#name-authorization-code-flow)
* The form submission is step (1)
* Using specifically the [Issuer Initiated flow here](https://openid.github.io/OpenID4VCI/openid-4-verifiable-credential-issuance-wg-draft.html#section-3.4)

sequenceDiagram
autonumber

actor A as Alice
participant D as DIDPay
participant W as Widget
participant I as Issuance Server

critical Setup
A->>D: Open app for the first time
D->>D: Generate DID. Store private key securely
end

critical SIOPv2
A->>D: Navigate to Widget
D->>W: Navigate to Widget
I->>D: Request to auth (contains nonce)
D->>A: AuthN & AuthZ?
A->>D: Consent given
D->>D: Generate Self-Issued ID Token w/nonce
D->>W: Provide Self-Issued ID Token
W->>I: Validate & Store Self-Issued ID Token
end

W->>W: Renders KYC Form
W->>D: Renders KYC Form
A->>D: Fill out KYC Form
D->>W: Submit Form
W->>I: Submit Form

critical OID4VCI
I->>D: Credential Offer (Issuer Initiatied)
D->>I: Obtains Issuer's Credential Issuer Metadata (e.g. supported algs, deferred endpoint)
D->>I: Token request w/Pre-Authorized Code
I->>I: Validate token request
I->>D: Bearer Token
D->>I: Credential Request (e.g. credential format)
I->>I: Validate credential request
I->>W: Presenter credential or deffered notice
W->>D: Send credential response
end

A->>D: Sees credential