Design developer surface

[KendallWeihe]

Original ideation concluded with this

Use this ticket to design what the precise DX will look like here

[KendallWeihe]

Ultimately we hope what is built here to drive an exemplar project, similar to what we have with the tbdex exemplar but with respect to the KCC issuance flow. I wrote a very primitive KCC end-to-end, which can be supportive of what's designed in this ticket.

JSON Schema for KCC https://github.com/TBD54566975/known-customer-credential/blob/main/kcc-schema.json

First and foremost, let's on the KCC and not the SIOPv2 and OID4VCI. For KCC we want:

• Strongly typed KCC
• sign() function which returns a VC-JWT
  • Implied in this is the usage of BearerDid or BearerDidSigner in the function params
  • TODO: consider defining the @web5/* dependencies as peerDependencies (reference)
• verify() function which takes a VC-JWT string as the parameter, and returns an instance of the KCC
• Validation of instance against the JSON schema
  • Current thinking:
    • Add a parse() function which accepts a JSON string and performs validation during parsing
    • Add a toJSON() function which also performs validation (so that a call to JSON.stringify(instanceOfKcc) will automatically validate
    • Perform validation during sign() function
    • Perform validation during verify() function

[KendallWeihe]

Relevant question posed here about the evidence property https://github.com/TBD54566975/known-customer-credential/pull/24/files#r1575276233

[KendallWeihe]

Refining this (from previous comment)

• Current thinking:
  • Add a parse() function which accepts a JSON string and performs validation during parsing
  • Add a toJSON() function which also performs validation (so that a call to JSON.stringify(instanceOfKcc) will automatically validate
  • Perform validation during sign() function
  • Perform validation during verify() function

Too cute with the parse() and toJSON(). We need 3 functions:

Create

KccCreateOptions has everything necessary to create a valid KCC

export class Kcc {
  public static async create(options: KccCreateOptions): Promise<Kcc> {
    // ...
  }
}

let kcc = Kcc.create(options)

☝️ this does perform JSON Schema validation

Sign

KccSignOptions probably includes a BearerDid or a BearerDidSigner

export class Kcc {
  public async sign(options: KccSignOptions): Promise<string> {
    // ...
  }
}

let kcc = Kcc.create(createOptions)
let vcJwt = kcc.sign(signOptions)

☝️ this does not perform JSON Schema validation

Verify

export class Kcc {
  public static async verify(vcJwt: string): Promise<Kcc> {
    // ...
  }
}

let vcJwt = "..."
let kcc = Kcc.verify(vcJwt)

☝️ this does perform JSON Schema validation

[nitro-neal]

so I'm still wondering why a whole new repo needs to be built for this, we handle 99% of this today in web5-js credentials package and we have issues for updates to credentialSchema validation

here is an example of a full kyc cred (credSchema resolution and verifiaction not implemented yet but coming soon(tm))- https://github.com/TBD54566975/web5-js/pull/491/files#diff-dca2114c947eccff38e8509d221b1eeae0de4510f4081ab01588d528d34a0989R94

so to create a kcc:

      const vc = await VerifiableCredential.create({
        type           : 'KnowYourCustomerCred',
        subject        : subjectDid.uri,
        issuer         : issuerDid.uri,
        issuanceDate   : '2023-05-19T08:02:04Z',
        expirationDate : `2055-05-19T08:02:04Z`,
        data           : {
          id                   : subjectDid.uri,
          country_of_residence : 'US',
          tier                 : 'Tier 1'
        },
        credentialSchema: {
          id   : ' https://github.com/TBD54566975/known-customer-credential/blob/main/kcc-schema.json',
          type : 'JsonSchema'
        },
        evidence: [
          { kind: 'document_verification', checks: ['passport', 'utility_bill'] },
          { kind: 'sanctions_check', checks: ['daily'] }
        ]
      });

to sign

const vcJwt = await vc.sign({ did: issuerDid });

to verify

await VerifiableCredential.verify({ vcJwt });

now currently there is no hard verification of the credentialSchema (which is wrong, but its the next issue on the list) issue here - https://github.com/TBD54566975/web5-js/issues/425

so this will split out the verify with verify options which they can include to verify the credentialSchema or not

It seems like the only thing this repo can gain at least for these 3 functions is minimal, could just as easilly have a helper function for "well known credentials" like kcc

Am I missing the mark? Will there be a lot more KCC specific stuff? Thoughts?

[KendallWeihe]

@nitro-neal It's a totally valid point! I wonder if perhaps it would be more wise to start with building the exemplar, and using that to drive whether or not a KCC-dedicated library is valuable or not. We know for sure we need an exemplar to share with newcomers. Two points come to mind...

1. The developer doesn't have KCC-specific types on your vc variable (the KCC-specific fields such as credentialSubject.countryOfResidence)
2. We still have a need for the SIOPv2 and OID4VCI parts of this

The SIOPv2+OID4VCI+OID4VP interactions are where 99% of the initial DX hurdle is, but since those pieces are so tightly integrated into the given client/server code, it's a challenge to make tooling which is valuable. For example, we could write custom express JS code, like we do in @tbdex/http-server but that would only be applicable for the narrow set of consumers who use express JS in their solution.

[KendallWeihe]

@nitro-neal has there been any discovery/consideration/work for adding generics to web5-js's VerifiableCredential? Thinking about item (1) in the list above.

[nitro-neal]

I dont know if implementing generics adds much value and just adds complexity:

A user can create a concrete type KnowYourCustomerData and just add it to the Data field and call it a day.

Example:

// Create a Know Your Customer Credential
const kycData: KnowYourCustomerData = {
    id: "subject123",
    country_of_residence: "US",
    tier: "Tier 1"
};

const kycCredential = await VerifiableCredential.create({
    type: 'KnowYourCustomerCred',
    subject: 'subjectDid.uri',
    issuer: 'issuerDid.uri',
    issuanceDate: '2023-05-19T08:02:04Z',
    expirationDate: '2055-05-19T08:02:04Z',
    data: kycData,
    credentialSchema: {
        id: 'https://github.com/TBD54566975/known-customer-credential/blob/main/kcc-schema.json',
        type: 'JsonSchema'
    },
    evidence: [
        { kind: 'document_verification', checks: ['passport', 'utility_bill'] }
    ]
});

We can possible add a "WellKnownCredentialTypes" file or something to get most of the functionality if we really wanted this.

But if others feel we need yet another repo for a wrapper around our VC lib I'm happy to disagree and commit and go full steam ahead with this repo 👍

[kirahsapong]

My only two cents here is that I think kcc would be one of those things that benefits from the facade pattern as it feels a bit adjacent to web5, which is more general while kcc is vary narrow. Like web5 is the wood and steel and kcc is the hammer. so for that reason i'm pro 2 separate repos but i'm even more pro whatever you like best