Design core models & framework interface

[bedinotti]

Design core models & framework interface

[bedinotti]

I've been toying with this in a Playground for a bit, and I'd love some feedback. While I was looking it as a functional-programming style first, I'm liking it better as an OO solution. Here's what I have for an object design:

// MARK - Object Model
struct Certificate {
    let title : String
    let subtitle : String?
    let description: String
    let image : Data
    let language : String


    let issuer : Issuer
    let recipient : Recipient
    let assertion : Assertion

    // Not a fan of this, since "verify" is a verb.
    let verify : Verify
}

struct Issuer {
    let name : String
    let email : String
    let image : Data
    let id : URL
    let url : URL

    let publicKey : String
    let publicKeyAddress : URL
    let requestUrl : URL
}

struct Recipient {
    let givenName : String
    let familyName : String

    let identity : String       // Usually, an email address
    let identityType : String   // "email" by default
    let isHashed : Bool         // false by default
    let publicKey : String      // bitcoin address of recipient
}

struct Assertion {
    let issuedOn : Date
    let signatureImage : Data
    let evidence : String
    let uid : String
    let id : URL
}

struct Verify {
    let signer : URL
    let signedAttribute : String    // default is "uid"
    let type : String               // "ECDSA(secp256k1)" is default -- what else is valid?
}

This is pretty much a destructuring of the cert format and is likely to evolve as we add and modify fields. Also, as I get more clarity about the various values some of these fields support, we'll probably settle on a few enums in place of strings in the JSON.

The more interesting bit is how methods off of these objects could look at the point of use:

// Certificates
// Here are the main means of interacting with certificates. All of the major verbs are methods on the core Certificate object.
let cert = Certicifate(fromFile: Data())    // Import

cert.verify()                               // Verify

try cert.revoke()                           // Revoke

let file = cert.toFile()                    // Export


// Key Management
// Here's how you seed the "wallet" with key management.
let seedPhrase = Keychain.generateSeedPhrase()
let keychain = Keychain(seedPhrase: seedPhrase)

// Issuer Introduction
// Here's how you make the call to send a new public key to the Issuer with some identity information.
let keyForMIT = keychain.nextPublicKey()
let alumnus = Recipient(givenName: "Chris",
                        familyName: "Downie",
                        identity: "chris@me.com",
                        identityType: "email",
                        isHashed: false,
                        publicKey: keyForMIT)
let mitMediaLab = Isseur()

mitMediaLab.introduce(recipient: alumnus)

// Key Management, pt 2
// Here's how you check if you have the public key in certificate.
keychain.has(publicKey: alumnus.publicKey)

Open questions:

• What is the Verify object mean? Can we change that to a noun, or does it mean something specific to the Cert format (or for OBI compliance?) Is there another word that would make sense in this OO model, even if the format maintained the verify attribute?
• Are there other key uses that should be considered? Something I'm missing here?

[1l2p]

You may have looked at this already, but I think Juliana tried to document a lot of the background thinking in the schema repository. https://github.com/digital-certificates/cert-schema/tree/master/docs (I hope it can help with some of the legacy naming conventions - I agree they don't always make sense, but I think it's worth sticking to the OBI conventions).

[kimdhamilton]

We will also be able to rely on the v1.1 OBI JSON LD schema for type information (https://openbadgespec.org/v1/context.json).

I'm working on migrating our v1 schema to fit OBI v1.1, and reworking digital-certs customizations as JSON LD extensions. There are minor structural changes and a few renames that will result from this.

That said, most of the names and types in your object model above will remain unchanged with that migration. The only missing part is the Certificate 'proof' data which will be used in verification. I owe you details on this. (ETA for baked versions of this and OBI v1.1 changes is EOW) Otherwise, the objects and interactions look good.

Re open questions:

• Verify has retained its name in v1.1, and we should keep it for OBI compliance.
• For the MVP, those are all the key uses we should need. Later we will want something like the ability to sign a message with a specific private key to prove ownership of a public address.

[bedinotti]

Thanks, you two.

@1l2p Yup! I was using the info on readthedocs, but I think it's the same content. It was super useful for making sure my model had all the valid fields, but it doesn't have a lot of info on why something is a certain way.

@kimdhamilton great! I'll move forward with the model outlined above, and I can iterate on it as you evolve the schema.