Add doc comments for credentials (#355)

* Add doc comments to APID * Add rust doc comments for vc * Add doc comments for vp * Add doc comments to relevant kt code * Update bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt * Update bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt * Update bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt * Update bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt * Update crates/web5/src/credentials/status_list_credential.rs * Update crates/web5/src/credentials/status_list_credential.rs * Update crates/web5/src/credentials/status_list_credential.rs * Update crates/web5/src/credentials/verifiable_credential_1_1.rs * Update crates/web5/src/credentials/verifiable_credential_1_1.rs * Update crates/web5/src/credentials/verifiable_credential_1_1.rs * Update crates/web5/src/credentials/verifiable_presentation_1_1.rs * add ignore --------- Co-authored-by: nitro-neal <[email protected]> Co-authored-by: Neal <[email protected]>
decentralized-identity · Sep 16, 2024 · a565623 · a565623
1 parent 26466e2
commit a565623
Show file tree

Hide file tree

Showing 9 changed files with 1,179 additions and 217 deletions.
diff --git a/Justfile b/Justfile
@@ -12,6 +12,9 @@ setup:
     rustup target add aarch64-apple-darwin
   fi
 
+docs: setup
+  cargo doc --open --no-deps
+
 build: setup
   cargo build --workspace
 

diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt
@@ -5,11 +5,51 @@ import web5.sdk.Web5Exception
 import web5.sdk.rust.Web5Exception.Exception as RustCoreException
 import web5.sdk.rust.StatusListCredential as RustCoreStatusListCredential
 
+/**
+ * Represents a Status List Credential, which is used to maintain the revocation or suspension status of multiple Verifiable Credentials.
+ * A Status List Credential is a special type of Verifiable Credential that tracks the status of other credentials.
+ *
+ * @property base The base Verifiable Credential associated with the Status List.
+ */
 data class StatusListCredential(
     val base: VerifiableCredential,
     internal val rustCoreStatusListCredential: RustCoreStatusListCredential
 ) {
     companion object {
+        /**
+         * Creates a new Status List Credential with the specified issuer, status purpose,
+         * and the list of disabled credentials.
+         *
+         * @param issuer The entity issuing the Status List Credential.
+         * @param statusPurpose The purpose of the status (e.g., "revocation").
+         * @param credentialsToDisable A list of Verifiable Credentials that are disabled (revoked or suspended).
+         * @return A new [StatusListCredential] instance.
+         * @throws Web5Exception if there is an error in creating the Status List Credential.
+         *
+         * Example usage:
+         * ```
+         * val issuerBearerDid = DidJwk.create()
+         * val subjectDidUri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"
+         * val verifiableCredential = VerifiableCredential.create(
+         *     Issuer.StringIssuer(issuerBearerDid.did.uri),
+         *     CredentialSubject(id = subjectDidUri),
+         *     VerifiableCredentialCreateOptions(
+         *         credentialStatus = CredentialStatus(
+         *             id = "https://example.com/status/1",
+         *             type = "StatusList2021Entry",
+         *             statusPurpose = "revocation",
+         *             statusListIndex = "3",
+         *             statusListCredential = "https://example.com/status/1"
+         *         )
+         *     )
+         * )
+         * val statusListCredential = StatusListCredential.create(
+         *     Issuer.StringIssuer(issuerBearerDid.did.uri),
+         *     "revocation",
+         *     listOf(verifiableCredential)
+         * )
+         * ```
+         */
         fun create(
             issuer: Issuer,
             statusPurpose: String,
@@ -30,6 +70,20 @@ data class StatusListCredential(
         }
     }
 
+    /**
+     * Checks if a given credential is disabled according to this Status List Credential.
+     *
+     * @param credential The [VerifiableCredential] to check.
+     * @return `true` if the credential is disabled, `false` otherwise.
+     * @throws Web5Exception if there is an error while checking the status of the credential.
+     *
+     * Example usage:
+     * ```
+     
+     *
+     * val isDisabled = statusListCredential.isDisabled(verifiableCredential)
+     * ```
+     */
     fun isDisabled(credential: VerifiableCredential): Boolean {
         try {
             return rustCoreStatusListCredential.isDisabled(credential.rustCoreVerifiableCredential)

diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt
@@ -20,6 +20,16 @@ import web5.sdk.rust.VerifiableCredentialCreateOptionsData as RustCoreVerifiable
 import web5.sdk.rust.CredentialSchemaData as RustCoreCredentialSchema
 import web5.sdk.rust.Web5Exception.Exception as RustCoreException
 
+/**
+ * Represents the status information of a Verifiable Credential.
+ * CredentialStatus is used to indicate the revocation or suspension status of a credential.
+ *
+ * @property id The unique identifier for the credential status.
+ * @property type The type(s) of the credential status.
+ * @property statusPurpose The purpose of the status (e.g., "revocation" or "suspension").
+ * @property statusListIndex The index in the status list indicating the credential's position.
+ * @property statusListCredential The unique identifier for the Verifiable Credential that lists the status of the credential.
+ */
 data class CredentialStatus(
     var id: String,
     var type: String,
@@ -28,6 +38,20 @@ data class CredentialStatus(
     var statusListCredential: String
 )
 
+/**
+ * Represents the options available when creating a Verifiable Credential.
+ * These options allow customization of various attributes of the credential during its creation.
+ *
+ * @property id The unique identifier for the Verifiable Credential. Optional. Defaults to `urn:uuid:{uuid}` if not provided.
+ * @property context The context(s) defining the meaning of terms within the credential.
+ * Defaults to `https://www.w3.org/2018/credentials/v1` if not provided.
+ * @property type The type(s) of the Verifiable Credential, where "VerifiableCredential" is always included as the base type.
+ * @property issuanceDate The issuance date of the credential. Defaults to the current date and time if not provided.
+ * @property expirationDate The optional expiration date of the credential.
+ * @property credentialStatus Optional status information of the credential (e.g., revocation or suspension).
+ * @property credentialSchema Optional schema used to validate the credential's data structure.
+ * @property evidence Optional array of evidence supporting the claims made in the credential.
+ */
 data class VerifiableCredentialCreateOptions(
     val id: String? = null,
     val context: List<String>? = null,
@@ -39,6 +63,22 @@ data class VerifiableCredentialCreateOptions(
     val evidence: List<Map<String, Any>>? = null
 )
 
+/**
+ * Represents a Verifiable Credential according to the W3C Verifiable Credentials Data Model v1.1
+ * and conformant to the Web5 specification.
+ * A Verifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified.
+ *
+ * @property context A list of contexts used to define the semantic meaning of the data contained in the Verifiable Credential.
+ * @property type The type(s) of the Verifiable Credential.
+ * @property id The unique identifier for the Verifiable Credential.
+ * @property issuer The entity (either a string or an object) that issued the credential.
+ * @property credentialSubject The subject of the credential, containing claims about the entity described by the credential.
+ * @property issuanceDate The date and time when the credential was issued.
+ * @property expirationDate The optional expiration date after which the credential is no longer valid.
+ * @property credentialStatus The credential status information, if applicable (e.g., revoked or suspended).
+ * @property credentialSchema The schema used to validate the data structure of the credential.
+ * @property evidence An array of evidence supporting the claims made in the credential.
+ */
 data class VerifiableCredential private constructor(
     val context: List<String>,
     val type: List<String>,
@@ -75,6 +115,27 @@ data class VerifiableCredential private constructor(
             )
         }
 
+        /**
+         * Creates a new Verifiable Credential with the specified issuer, subject, and optional creation options.
+         *
+         * @param issuer The entity issuing the credential. The `issuer` must be a valid DID.
+         * @param credentialSubject The subject of the credential containing claims. The subject must be a valid DID.
+         * @param options Optional parameters for creating the credential, such as schema or status.
+         * @return The newly created Verifiable Credential.
+         * @throws Web5Exception if the creation fails due to validation or other errors.
+         *
+         * Example usage:
+         * ```
+         * val issuerBearerDid = DidJwk.create()
+         * val subjectDidUri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"
+         * val verifiableCredential = VerifiableCredential.create(
+         *     Issuer.StringIssuer(issuerBearerDid.did.uri),
+         *     CredentialSubject(id = subjectDidUri),
+         *         )
+         *     )
+         * )
+         * ```
+         */
         fun create(
             issuer: Issuer,
             credentialSubject: CredentialSubject,
@@ -120,6 +181,20 @@ data class VerifiableCredential private constructor(
             }
         }
 
+        /**
+         * Constructs a Verifiable Credential from a VC JWT (JSON Web Token).
+         *
+         * @param vcJwt The Verifiable Credential in JWT format, serialized as a compact JWS.
+         * @param verify If true, verifies the integrity of the JWT by performing cryptographic verification against the signature, validating the VC Data Model, and validating the JSON Schema if present.
+         * @return The deserialized and validated Verifiable Credential.
+         * @throws Web5Exception if the JWT is invalid or verification fails.
+         *
+         * Example usage:
+         * ```
+         * val vcJwt = "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"
+         * val verifiableCredential = VerifiableCredential.fromVcJwt(vcJwt, true)
+         * ```
+         */
         fun fromVcJwt(vcJwt: String, verify: Boolean): VerifiableCredential {
             try {
                 val rustCoreVerifiableCredential = RustCoreVerifiableCredential.fromVcJwt(vcJwt, verify)
@@ -148,6 +223,28 @@ data class VerifiableCredential private constructor(
         }
     }
 
+    /**
+     * Signs the Verifiable Credential using the specified Bearer DID and optional verification method.
+     *
+     * @param bearerDid The DID used to sign the credential.
+     * @param verificationMethodId Optional identifier of the Verification Method for which to sign with.
+     * @return A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Credential.
+     * @throws Web5Exception if the signing process fails.
+     *
+     * Example usage:
+     * ```
+     * val issuerBearerDid = DidJwk.create()
+     * val subjectDidUri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"
+     * val verifiableCredential = VerifiableCredential.create(
+     *     Issuer.StringIssuer(issuerBearerDid.did.uri),
+     *     CredentialSubject(id = subjectDidUri),
+     *         )
+     *     )
+     * )
+     *
+     * val vcJwt = verifiableCredential.sign(issuerBearerDid)
+     * ```
+     */
     fun sign(bearerDid: BearerDid, verificationMethodId: String? = null): String {
         try {
             return rustCoreVerifiableCredential.sign(bearerDid.rustCoreBearerDid, verificationMethodId)
@@ -157,13 +254,22 @@ data class VerifiableCredential private constructor(
     }
 }
 
+/**
+ * Represents the issuer of the Verifiable Credential. It can be a string identifier or an object with additional properties.
+ */
 @JsonDeserialize(using = IssuerDeserializer::class)
 sealed class Issuer {
+    /**
+     * Represents an issuer identified by a string (e.g., a DID or URL).
+     */
     data class StringIssuer(val value: String) : Issuer() {
         @JsonValue
         fun toJson(): String = value
     }
 
+    /**
+     * Represents an issuer as an object, containing an ID, name, and additional properties.
+     */
     data class ObjectIssuer(
         val id: String,
         val name: String,
@@ -195,6 +301,12 @@ class IssuerDeserializer : JsonDeserializer<Issuer>() {
     }
 }
 
+/**
+ * Represents the subject of the Verifiable Credential, containing claims about the entity being described by the credential.
+ *
+ * @property id The identifier of the credential subject.
+ * @property additionalProperties Additional properties associated with the credential subject.
+ */
 data class CredentialSubject(
     val id: String,
     @JsonIgnore
@@ -216,6 +328,12 @@ data class CredentialSubject(
     }
 }
 
+/**
+ * Represents the credential schema, used to validate the data structure of the credential.
+ *
+ * @property id The unique identifier of the schema.
+ * @property type The type of schema used for validation.
+ */
 data class CredentialSchema(
     val id: String,
     val type: String