From e02a8027baf78f45897bd33db5ea1a3a175d9cd3 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 12 Sep 2024 14:04:39 -0400 Subject: [PATCH 01/16] Add doc comments to APID --- docs/API_DESIGN.md | 825 +++++++++++++++++++++++++++++++++------------ 1 file changed, 615 insertions(+), 210 deletions(-) diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index a0637173..4ea11fd2 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -27,6 +27,11 @@ - [`Field`](#field) - [`Optionality`](#optionality) - [`Filter`](#filter) + - [`PresentationResult`](#presentationresult) + - [`PresentationSubmission`](#presentationsubmission) + - [`InputDescriptorMapping`](#inputdescriptormapping) + - [`SubmissionRequirement`](#submissionrequirement) + - [`SubmissionRequirementRule`](#submissionrequirementrule) - [Crypto](#crypto) - [`Jwk`](#jwk) - [Key Managers](#key-managers) @@ -44,9 +49,6 @@ - [`Secp256k1Signer`](#secp256k1signer) - [`Secp256k1Verifier`](#secp256k1verifier) - [`X25519Generator`](#x25519generator) - - [`Secp256r1Generator`](#secp256r1generator) - - [`Secp256r1Signer`](#secp256r1signer) - - [`Secp256r1Verifier`](#secp256r1verifier) - [Decentralized Identifier's (DIDs)](#decentralized-identifiers-dids) - [`Did`](#did) - [Example: Instantiate from a `did:dht`](#example-instantiate-from-a-diddht) @@ -56,7 +58,6 @@ - [`Service`](#service) - [Resolution](#resolution) - [`ResolutionResult`](#resolutionresult) - - [`ResolutionResultResolveOptions`](#resolutionresultresolveoptions) - [`ResolutionMetadataError`](#resolutionmetadataerror) - [`ResolutionMetadata`](#resolutionmetadata) - [`DocumentMetadata`](#documentmetadata) @@ -86,21 +87,58 @@ #### `VerifiableCredential` ```pseudocode! +/// Represents a Verifiable Credential according to the W3C Verifiable Credentials Data Model. +/// A Verifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified. CLASS VerifiableCredential + + /// A list of contexts used to define the semantic meaning of the data contained in the Verifiable Credential. PUBLIC DATA @context: []string + + /// The unique identifier for the Verifiable Credential. PUBLIC DATA id: string + + /// The type(s) of the Verifiable Credential, typically includes "VerifiableCredential". PUBLIC DATA type: []string + + /// The entity (either a string or an object) that issued the credential. PUBLIC DATA issuer: Issuer + + /// The subject of the credential, containing claims about the entity being described by the credential. PUBLIC DATA credential_subject: CredentialSubject + + /// The date and time when the credential was issued. PUBLIC DATA issuance_date: datetime + + /// The optional expiration date and time after which the credential is no longer valid. PUBLIC DATA expiration_date: datetime? + + /// The credential status information, if applicable (e.g., revoked or suspended). PUBLIC DATA credential_status: CredentialStatus? + + /// The credential schema, used to validate the data structure of the credential. PUBLIC DATA credential_schema: CredentialSchema? + + /// An array of evidence supporting the claims made in the credential. PUBLIC DATA evidence: []Evidence? + /// Creates a new Verifiable Credential with the specified issuer, subject, and optional creation options. + /// + /// @param issuer The entity issuing the credential. + /// @param credential_subject The subject of the credential containing claims. + /// @param options Optional parameters for creating the credential, such as schema or status. CONSTRUCTOR create(issuer: Issuer, credential_subject: CredentialSubject, options: VerifiableCredentialCreateOptions?) + + /// Constructs a Verifiable Credential from a VC JWT (JSON Web Token). + /// + /// @param vc_jwt The Verifiable Credential in JWT format. + /// @param verify If true, verifies the integrity of the JWT before creating the credential. CONSTRUCTOR from_vc_jwt(vc_jwt: string, verify: bool) + /// Signs the Verifiable Credential using the specified Bearer DID and optional verification method. + /// + /// @param bearer_did The DID used to sign the credential. + /// @param verification_method_id Optional identifier for the verification method. + /// @returns A string representing the signed JWT of the Verifiable Credential. METHOD sign(bearer_did: BearerDid, verification_method_id: String?): string ``` @@ -119,24 +157,52 @@ CLASS VerifiableCredential ##### `CredentialStatus` ```pseudocode! +/// Represents the status information of a Verifiable Credential. +/// CredentialStatus is used to indicate the revocation or suspension status of a credential. CLASS CredentialStatus + + /// The unique identifier for the credential status. PUBLIC DATA id: string + + /// The type(s) of the credential status, typically includes "CredentialStatus". PUBLIC DATA type: []string + + /// The purpose of the status (e.g., "revocation" or "suspension"). PUBLIC DATA status_purpose: string + + /// The index in the status list indicating the credential's position. PUBLIC DATA status_list_index: string + + /// The unique identifier for the Verifiable Credential that lists the status of the credential. PUBLIC DATA status_list_credential: string ``` ##### `VerifiableCredentialCreateOptions` ```psuedocode! +/// Represents the options available when creating a Verifiable Credential. +/// These options allow customization of various attributes of the credential during its creation. CLASS VerifiableCredentialCreateOptions + + /// The unique identifier for the Verifiable Credential. This is optional. PUBLIC DATA id: string? + + /// The context(s) for the Verifiable Credential, which define the meaning of terms within the credential. PUBLIC DATA context: []string? + + /// The type(s) of the Verifiable Credential. Typically includes "VerifiableCredential". PUBLIC DATA type: []string? + + /// The issuance date of the credential. If not provided, defaults to the current date and time. PUBLIC DATA issuance_date: datetime? + + /// The optional expiration date for the credential, after which it is no longer valid. PUBLIC DATA expiration_date: datetime? + + /// The optional credential status, which indicates revocation or suspension information. PUBLIC DATA credential_status: CredentialStatus? + + /// An optional array of evidence supporting the claims made in the credential. PUBLIC DATA evidence: []Evidence? ``` @@ -145,11 +211,24 @@ CLASS VerifiableCredentialCreateOptions #### `StatusListCredential` ```pseudocode! +/// 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. CLASS StatusListCredential + + /// The base Verifiable Credential associated with the Status List. PUBLIC DATA base: VerifiableCredential + /// 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 status_purpose The purpose of the status (e.g., "revocation"). + /// @param disabled_credentials A list of Verifiable Credentials that are disabled (revoked or suspended). CONSTRUCTOR create(issuer: Issuer, status_purpose: string, disabled_credentials: []VerifiableCredential) + /// Checks whether the specified Verifiable Credential is disabled in the Status List. + /// + /// @param credential The Verifiable Credential to check. + /// @returns A boolean value indicating whether the credential is disabled (true if disabled, false otherwise). METHOD is_disabled(credential VerifiableCredential): bool ``` @@ -158,31 +237,78 @@ CLASS StatusListCredential #### `VerifiablePresentation` ```pseudocode! +/// Represents a Verifiable Presentation according to the W3C Verifiable Credentials Data Model. +/// A Verifiable Presentation allows a holder to present one or more Verifiable Credentials to a verifier. CLASS VerifiablePresentation + + /// A list of contexts used to define the semantic meaning of the data contained in the presentation. PUBLIC DATA @context: []string + + /// The unique identifier for the Verifiable Presentation. PUBLIC DATA id: string + + /// The type(s) of the Verifiable Presentation, typically includes "VerifiablePresentation". PUBLIC DATA type: []string + + /// The holder of the Verifiable Presentation, identified by a DID or other identifier. PUBLIC DATA holder: string + + /// The date and time when the presentation was issued. PUBLIC DATA issuance_date: datetime + + /// The optional expiration date and time after which the presentation is no longer valid. PUBLIC DATA expiration_date: datetime? + + /// A list of Verifiable Credentials contained within the presentation. PUBLIC DATA verifiable_credential: []string + + /// Additional data that may be included in the presentation, represented as a key-value map. PUBLIC DATA additional_data: Map? + /// Creates a new Verifiable Presentation with the specified holder, Verifiable Credential JWTs, and optional creation options. + /// + /// @param holder The entity holding and presenting the Verifiable Presentation. + /// @param vc_jwts A list of Verifiable Credential JWTs to include in the presentation. + /// @param options Optional parameters for creating the presentation, such as context or expiration. CONSTRUCTOR create(holder: string, vc_jwts: []string, options: VerifiablePresentationCreateOptions?) + + /// Constructs a Verifiable Presentation from a VP JWT (JSON Web Token). + /// + /// @param vp_jwt The Verifiable Presentation in JWT format. + /// @param verify If true, verifies the integrity of the JWT before creating the presentation. CONSTRUCTOR from_vp_jwt(vp_jwt: string, verify: bool) + /// Signs the Verifiable Presentation using the specified Bearer DID and optional verification method. + /// + /// @param bearer_did The DID used to sign the presentation. + /// @param verification_method_id Optional identifier for the verification method. + /// @returns A string representing the signed JWT of the Verifiable Presentation. METHOD sign(bearer_did: BearerDid, verification_method_id: String?): string ``` #### `VerifiablePresentationCreateOptions` ```pseudocode! +/// Represents the options available when creating a Verifiable Presentation. +/// These options allow customization of various attributes of the presentation during its creation. CLASS VerifiablePresentationCreateOptions + + /// The unique identifier for the Verifiable Presentation. This is optional. PUBLIC DATA id: string? + + /// The context(s) for the Verifiable Presentation, which define the meaning of terms within the presentation. PUBLIC DATA context: []string? + + /// The type(s) of the Verifiable Presentation. Typically includes "VerifiablePresentation". PUBLIC DATA type: []string? + + /// The issuance date of the presentation. If not provided, defaults to the current date and time. PUBLIC DATA issuance_date: datetime? + + /// The optional expiration date for the presentation, after which it is no longer valid. PUBLIC DATA expiration_date: datetime? + + /// Additional data that may be included in the presentation, represented as a key-value map. PUBLIC DATA additional_data: Map? ``` @@ -191,110 +317,222 @@ CLASS VerifiablePresentationCreateOptions ### `PresentationDefinition` ```pseudocode! +/// Represents a Presentation Definition in the context of Presentation Exchange. +/// A Presentation Definition specifies the requirements for Verifiable Credentials to be presented. CLASS PresentationDefinition + + /// The unique identifier for the Presentation Definition. PUBLIC DATA id: string + + /// The name of the Presentation Definition. This is optional. PUBLIC DATA name: string? + + /// The purpose of the Presentation Definition, explaining its intent. This is optional. PUBLIC DATA purpose: string? + + /// A list of input descriptors defining the Verifiable Credentials required for the presentation. PUBLIC DATA input_descriptors: []InputDescriptor + /// Selects the Verifiable Credentials from the provided list of Verifiable Credential JWTs that satisfy the input descriptors. + /// + /// @param vc_jwts A list of Verifiable Credential JWTs to select from. + /// @returns A list of Verifiable Credential JWTs that match the input descriptors. METHOD select_credentials(vc_jwts: []string): []string + + /// Creates a Verifiable Presentation from the selected Verifiable Credentials based on the input descriptors. + /// + /// @param vc_jwts A list of Verifiable Credential JWTs to include in the presentation. + /// @returns A PresentationResult containing the created Verifiable Presentation. METHOD create_presentation_from_credentials(vc_jwts: []string): PresentationResult ``` ### `InputDescriptor` ```pseudocode! +/// Represents an Input Descriptor, which defines the required properties of Verifiable Credentials +/// for inclusion in a presentation as part of a Presentation Definition. CLASS InputDescriptor + + /// The unique identifier for the Input Descriptor. PUBLIC DATA id: string + + /// The name of the Input Descriptor. This is optional. PUBLIC DATA name: string? + + /// The purpose of the Input Descriptor, explaining its intent. This is optional. PUBLIC DATA purpose: string? + + /// The constraints defining the required properties and structure of the Verifiable Credentials. PUBLIC DATA constraints: Constraints ``` ### `Constraints` ```pseudocode! +/// Represents the constraints that define the required properties of Verifiable Credentials +/// for inclusion in a presentation as part of an Input Descriptor. CLASS Constraints + + /// A list of fields that define the required structure and values of the Verifiable Credentials. PUBLIC DATA fields: []Field ``` ### `Field` ```pseudocode! +/// Represents a field within the constraints of an Input Descriptor. +/// Defines the required structure and values for a specific attribute of a Verifiable Credential. CLASS Field + + /// The unique identifier for the field. This is optional. PUBLIC DATA id: string? + + /// The name of the field. This is optional. PUBLIC DATA name: string? + + /// The JSON paths to the data in the Verifiable Credential that must satisfy the field's constraints. PUBLIC DATA path: []string + + /// The purpose of the field, explaining its intent. This is optional. PUBLIC DATA purpose: string? + + /// An optional filter to apply additional constraints on the values of the field. PUBLIC DATA filter: Filter? + + /// Indicates whether the field is optional or required. PUBLIC DATA optional: bool? + + /// Specifies whether the field should be treated as a predicate (for comparison purposes). PUBLIC DATA predicate: Optionality? ``` ### `Optionality` ```pseudocode! +/// Represents the optionality of a field in an Input Descriptor. +/// Defines whether a field is required or preferred. ENUM Optionality + + /// The field is required. Required + + /// The field is preferred but not mandatory. Preferred ``` ### `Filter` ```pseudocode! +/// Represents a filter applied to a field in an Input Descriptor. +/// Defines additional constraints that the field's values must satisfy. CLASS Filter + + /// The type of the value expected for the field. PUBLIC DATA type: string? + + /// A regular expression pattern that the field's value must match. This is optional. PUBLIC DATA pattern: string? + + /// A constant value that the field's value must equal. This is optional. PUBLIC DATA const_value: string? + + /// A nested filter to apply further constraints on the field. This is optional. PUBLIC DATA contains: Filter? ``` ### `PresentationResult` ```pseudocode! +/// Represents the result of creating a Verifiable Presentation based on a Presentation Definition. +/// Contains the presentation submission and the matched Verifiable Credentials. CLASS PresentationResult + + /// The submission of the presentation, containing the mapping between input descriptors and Verifiable Credentials. PUBLIC DATA presentation_submission: PresentationSubmission + + /// A list of the Verifiable Credential JWTs that matched the input descriptors. PUBLIC DATA matched_vc_jwts: []string ``` ### `PresentationSubmission` ```pseudocode! +/// Represents the submission of a Verifiable Presentation in response to a Presentation Definition. +/// Contains the mapping between input descriptors and the Verifiable Credentials used in the presentation. CLASS PresentationSubmission + + /// The unique identifier for the presentation submission. PUBLIC DATA id: string + + /// The identifier of the Presentation Definition that this submission satisfies. PUBLIC DATA definition_id: string + + /// A list of mappings between input descriptors and the Verifiable Credentials provided. PUBLIC DATA descriptor_map: []InputDescriptorMapping ``` ### `InputDescriptorMapping` ```pseudocode! +/// Represents a mapping between an Input Descriptor and a Verifiable Credential in a Presentation Submission. +/// Defines how the credentials satisfy the input descriptors in the Presentation Definition. CLASS InputDescriptorMapping + + /// The unique identifier for the Input Descriptor being satisfied. PUBLIC DATA id: string + + /// The format of the Verifiable Credential (e.g., JWT or JSON-LD). PUBLIC DATA format: string + + /// The JSON path to the credential that satisfies the Input Descriptor. PUBLIC DATA path: string + + /// An optional nested mapping for further structuring of the credential. PUBLIC DATA path_nested: InputDescriptorMapping? ``` ### `SubmissionRequirement` ```pseudocode! +/// Represents a submission requirement in a Presentation Definition. +/// Specifies rules for how Verifiable Credentials must be selected and combined in a presentation. CLASS SubmissionRequirement + + /// The rule defining how the credentials must be selected (e.g., "all" or "pick"). PUBLIC DATA rule: SubmissionRequirementRule + + /// The identifier of the source from which credentials should be selected. This is optional. PUBLIC DATA from: string? + + /// A list of nested submission requirements, allowing for more complex selection rules. This is optional. PUBLIC DATA from_nested: []SubmissionRequirement? + + /// The name of the submission requirement. This is optional. PUBLIC DATA name: string? + + /// The purpose of the submission requirement, explaining its intent. This is optional. PUBLIC DATA purpose: string? + + /// The exact number of credentials required to satisfy this submission requirement. This is optional. PUBLIC DATA count: uint32? + + /// The minimum number of credentials required to satisfy this submission requirement. This is optional. PUBLIC DATA min: uint32? + + /// The maximum number of credentials allowed to satisfy this submission requirement. This is optional. PUBLIC DATA max: uint32? ``` ### `SubmissionRequirementRule` ```pseudocode! +/// Defines the rule for how Verifiable Credentials must be selected in a submission requirement. ENUM SubmissionRequirementRule + + /// All credentials that match the requirement must be selected. All + + /// A subset of the credentials that match the requirement may be selected. Pick ``` # Crypto @@ -305,26 +543,26 @@ ENUM SubmissionRequirementRule > Public & private *key material* are currently strictly represented as [Jwk](#jwk-object-oriented-class), but as the requirement for additional representations (ex: CBOR) present themselves, key material will need to be disintermediated via a polymorphic base class such as `PublicKeyMaterial` (which would expose an instance method for `get_verifier_bytes()`) and `PrivateKeyMaterial` (which would expose instance methods for `to_public_jwk_material()` and `get_signer_bytes()`), both of which would implement `as_jwk()`, `as_cbor()` and any other concrete representations as instance methods. ```pseudocode! -/// Partial representation of a [JSON Web Key as per RFC7517](https://tools.ietf.org/html/rfc7517). -/// Note that this is a subset of the spec. +/// Represents a JSON Web Key (JWK) as defined by RFC 7517. +/// A JWK is a JSON representation of a cryptographic key used for signing, verification, encryption, or decryption. CLASS Jwk - /// Identifies the algorithm intended for use with the key. - PUBLIC DATA alg: string? - /// Represents the key type. e.g. EC for elliptic curve, OKP for Edwards curve + /// Identifies the algorithm intended for use with the key (e.g., "EdDSA", "ES256"). + PUBLIC DATA alg: string? + + /// The key type (e.g., "EC" for elliptic curve, "OKP" for Edwards curve). PUBLIC DATA kty: string - - /// curve name for Elliptic Curve (EC) and Edwards Curve (Ed) keys. - /// e.g. secp256k1, Ed25519 + + /// The curve name for Elliptic Curve (EC) and Edwards Curve (OKP) keys (e.g., "secp256k1", "Ed25519"). PUBLIC DATA crv: string - - /// X coordinate for EC keys, or the public key for OKP. + + /// The X coordinate for EC keys, or the public key for OKP. PUBLIC DATA x: string - - /// Y coordinate for EC keys. + + /// The Y coordinate for EC keys. This is optional and used for certain types of keys. PUBLIC DATA y: string? - - /// Private key component for EC or OKP keys. + + /// The private key component for EC or OKP keys. This is optional. PUBLIC DATA d: string? ``` @@ -333,11 +571,20 @@ CLASS Jwk ### `KeyManager` ```pseudocode! +/// Represents a Key Manager interface for managing cryptographic keys. +/// Provides methods for retrieving signers and importing private keys. INTERFACE KeyManager - /// Returns the signer for the given public key. + + /// Returns the signer for the given public JWK. + /// + /// @param public_jwk The public JWK used to retrieve the corresponding signer. + /// @returns A Signer instance for the provided public JWK. METHOD get_signer(public_jwk: Jwk): Signer - /// For importing keys which may be stored somewhere such as environment variables. Return Jwk is the public key for the given private key. + /// Imports a private JWK and returns the corresponding public JWK. + /// + /// @param private_jwk The private JWK to be imported. + /// @returns The public JWK corresponding to the imported private JWK. METHOD import_private_jwk(private_jwk: Jwk): Jwk ``` @@ -348,8 +595,13 @@ INTERFACE KeyManager > Exporting private key material is an unsafe practice and should be constrained to development settings. ```pseudocode! +/// Represents a Key Exporter interface for exporting private key material. +/// Provides methods to safely export private JWKs. Intended for development and testing environments only. INTERFACE KeyExporter - /// Returns the full set of private keys represented as JWK's + + /// Exports the full set of private keys as JWKs. + /// + /// @returns An array of JWKs representing the private keys. METHOD export_private_jwks(): []Jwk ``` @@ -358,17 +610,30 @@ INTERFACE KeyExporter The `InMemoryKeyManager` manages private keys in working memory, and so therefore any production utilization of the instance may be exposed to memory safety vulnerabilities; the `InMemoryKeyManager` is primarily intended for development & testing environments. For cases wherein this is unacceptable, [`KeyManager`](#keymanager) & [`Signer`](#signer) are both polymorphic bases classes which can be implemented and utilized in the dependent areas. ```pseudocode! -/// An encapsulation of key material stored in-memory. +/// Represents an in-memory key manager that stores cryptographic key material in memory. +/// This class is primarily intended for development and testing environments due to memory safety concerns. CLASS InMemoryKeyManager IMPLEMENTS KeyManager, KeyExporter + + /// Creates a new in-memory key manager with the specified private JWKs. + /// + /// @param private_jwks A list of private JWKs to be managed in memory. CONSTRUCTOR(private_jwks: []Jwk) - /// Returns the signer for the given public key. + /// Returns the signer for the given public JWK. + /// + /// @param public_jwk The public JWK used to retrieve the corresponding signer. + /// @returns A Signer instance for the provided public JWK. METHOD get_signer(public_jwk: Jwk): Signer - /// For importing keys which may be stored somewhere such as environment variables. Return Jwk is the public key for the given private key. + /// Imports a private JWK and returns the corresponding public JWK. + /// + /// @param private_jwk The private JWK to be imported. + /// @returns The public JWK corresponding to the imported private JWK. METHOD import_private_jwk(private_jwk: Jwk): Jwk - /// Returns the full set of private keys represented as JWK's + /// Exports the full set of private keys as JWKs. + /// + /// @returns An array of JWKs representing the private keys. METHOD export_private_jwks(): []Jwk ``` @@ -377,174 +642,202 @@ CLASS InMemoryKeyManager IMPLEMENTS KeyManager, KeyExporter ### `Dsa` ```pseudocode! -/// The set of Digital Signature Algorithms natively supported within this SDK. +/// Represents the set of Digital Signature Algorithms (DSA) supported by the SDK. +/// Used to indicate the algorithm used for signing and verification. ENUM Dsa + + /// Ed25519 digital signature algorithm. Ed25519 + + /// Secp256k1 elliptic curve digital signature algorithm. Secp256k1 ``` -> We must add support for `X25519`, `secp256k1`, and `secp256r1` for [full did:dht conformance](https://did-dht.com/registry/index.html#key-type-index). +> We must add support for `X25519` and `secp256r1` for [full did:dht conformance](https://did-dht.com/registry/index.html#key-type-index). ### `Signer` ```pseudocode! -/// Set of functionality required to implement to be a compatible DSA signer. +/// Represents a signer interface for digital signatures using a private key. +/// Provides methods for signing data. INTERFACE Signer - /// Signs the given payload by using the encapsulated private key material. + + /// Signs the given payload using the encapsulated private key material. + /// + /// @param payload The data to be signed. + /// @returns The signature as a byte array. METHOD sign(payload: []byte): []byte ``` ### `Verifier` ```pseudocode! -/// Set of functionality required to implement to be a compatible DSA verifier. +/// Represents a verifier interface for verifying digital signatures using public key material. +/// Provides methods for verifying data against a signature. INTERFACE Verifier - /// Execute the verification of the signature against the payload by using the encapsulated public key material. - METHOD verify(payload: []byte, signature: []byte) + + /// Verifies the given signature against the payload using the encapsulated public key material. + /// + /// @param payload The original data that was signed. + /// @param signature The signature to be verified. + /// @returns A boolean indicating whether the verification was successful. + METHOD verify(payload: []byte, signature: []byte): bool ``` ### `Ed25519Generator` ```pseudocode! -/// Generates private key material for Ed25519. +/// Represents a generator for creating Ed25519 key pairs. +/// Provides a method to generate private key material for the Ed25519 digital signature algorithm. CLASS Ed25519Generator - /// Generate the private key material; return Jwk includes private key material. + + /// Generates a new Ed25519 key pair, returning the JWK containing both the private and public key material. + /// + /// @returns A JWK representing the Ed25519 private and public keys. STATIC METHOD generate(): Jwk ``` ### `Ed25519Signer` ```pseudocode! -/// Implementation of [`Signer`](#signer) for Ed25519. +/// Represents a signer implementation for the Ed25519 digital signature algorithm. +/// Provides methods for signing data using an Ed25519 private key. CLASS Ed25519Signer IMPLEMENTS Signer + + /// Creates a new Ed25519Signer with the given private JWK. + /// + /// @param private_jwk The private JWK used for signing. CONSTRUCTOR(private_jwk: Jwk) - /// Implementation of Signer's sign instance method for Ed25519. + /// Signs the given payload using the Ed25519 private key. + /// + /// @param payload The data to be signed. + /// @returns The signature as a byte array. METHOD sign(payload: []byte): []byte ``` ### `Ed25519Verifier` ```pseudocode! -/// Implementation of [`Verifier`](#verifier) for Ed25519. +/// Represents a verifier implementation for the Ed25519 digital signature algorithm. +/// Provides methods for verifying data using an Ed25519 public key. CLASS Ed25519Verifier IMPLEMENTS Verifier + + /// Creates a new Ed25519Verifier with the given public JWK. + /// + /// @param public_jwk The public JWK used for verification. CONSTRUCTOR(public_jwk: Jwk) - /// Implementation of Verifier's dsa_verify instance method for Ed25519. + /// Verifies the given signature against the payload using the Ed25519 public key. + /// + /// @param payload The original data that was signed. + /// @param signature The signature to be verified. + /// @returns A boolean indicating whether the verification was successful. METHOD verify(payload: []byte): bool ``` ### `Secp256k1Generator` ```pseudocode! -/// Generates private key material for Secp256k1. +/// Represents a generator for creating Secp256k1 key pairs. +/// Provides a method to generate private key material for the Secp256k1 elliptic curve digital signature algorithm. CLASS Secp256k1Generator - /// Generate the private key material; return Jwk includes private key material. + + /// Generates a new Secp256k1 key pair, returning the JWK containing both the private and public key material. + /// + /// @returns A JWK representing the Secp256k1 private and public keys. STATIC METHOD generate(): Jwk ``` ### `Secp256k1Signer` ```pseudocode! -/// Implementation of [`Signer`](#signer) for Secp256k1. +/// Represents a signer implementation for the Secp256k1 elliptic curve digital signature algorithm. +/// Provides methods for signing data using a Secp256k1 private key. CLASS Secp256k1Signer IMPLEMENTS Signer + + /// Creates a new Secp256k1Signer with the given private JWK. + /// + /// @param private_jwk The private JWK used for signing. CONSTRUCTOR(private_jwk: Jwk) - /// Implementation of Signer's sign instance method for Secp256k1. + /// Signs the given payload using the Secp256k1 private key. + /// + /// @param payload The data to be signed. + /// @returns The signature as a byte array. METHOD sign(payload: []byte): []byte ``` ### `Secp256k1Verifier` ```pseudocode! -/// Implementation of [`Verifier`](#verifier) for Secp256k1. +/// Represents a verifier implementation for the Secp256k1 elliptic curve digital signature algorithm. +/// Provides methods for verifying data using a Secp256k1 public key. CLASS Secp256k1Verifier IMPLEMENTS Verifier + + /// Creates a new Secp256k1Verifier with the given public JWK. + /// + /// @param public_jwk The public JWK used for verification. CONSTRUCTOR(public_jwk: Jwk) - /// Implementation of Verifier's dsa_verify instance method for Secp256k1. + /// Verifies the given signature against the payload using the Secp256k1 public key. + /// + /// @param payload The original data that was signed. + /// @param signature The signature to be verified. + /// @returns A boolean indicating whether the verification was successful. METHOD verify(payload: []byte): bool ``` - ### `X25519Generator` ```pseudocode! -/// Generates private key material for X25519. -CLASS Ed25519Generator - /// Generate the private key material; return Jwk includes private key material. - STATIC METHOD generate(): Jwk -``` +/// Represents a generator for creating X25519 key pairs. +/// Provides a method to generate private key material for the X25519 key exchange algorithm. +CLASS X25519Generator -### `Secp256r1Generator` - -```pseudocode! -/// Generates private key material for Secp256r1. -CLASS Secp256r1Generator - /// Generate the private key material; return Jwk includes private key material. + /// Generates a new X25519 key pair, returning the JWK containing both the private and public key material. + /// + /// @returns A JWK representing the X25519 private and public keys. STATIC METHOD generate(): Jwk ``` -### `Secp256r1Signer` - -```pseudocode! -/// Implementation of [`Signer`](#signer) for Secp256r1. -CLASS Secp256r1Signer IMPLEMENTS Signer - CONSTRUCTOR(private_jwk: Jwk) - - /// Implementation of Signer's sign instance method for Secp256r1. - METHOD sign(payload: []byte): []byte -``` - -### `Secp256r1Verifier` - -```pseudocode! -/// Implementation of [`Verifier`](#verifier) for Secp256r1. -CLASS Secp256r1Verifier IMPLEMENTS Verifier - CONSTRUCTOR(public_jwk: Jwk) - - /// Implementation of Verifier's dsa_verify instance method for Secp256r1. - METHOD verify(payload: []byte): bool -``` - # Decentralized Identifier's (DIDs) ## `Did` ```pseudocode! -/// Representation of a [DID Core Identifier](https://www.w3.org/TR/did-core/#identifiers). +/// Represents a Decentralized Identifier (DID) according to the W3C DID Core Specification. +/// A DID is a globally unique identifier that enables verifiable, decentralized digital identity. CLASS Did - /// URI represents the complete Decentralized Identifier (DID) URI. - /// Spec: https://www.w3.org/TR/did-core/#did-syntax. - PUBLIC DATA uri: string - /// URL represents the DID URI + A network location identifier for a specific resource. - /// Spec: https://www.w3.org/TR/did-core/#did-url-syntax. + /// The complete Decentralized Identifier (DID) URI. + /// Specifies the DID syntax as per the W3C DID Core specification. + PUBLIC DATA uri: string + + /// The DID URI plus a network location identifier for a specific resource. PUBLIC DATA url: string - - /// Method specifies the DID method in the URI, which indicates the underlying method-specific identifier scheme (e.g., jwk, dht, key, etc.). - /// Spec: https://www.w3.org/TR/did-core/#method-schemes. + + /// The method component of the DID URI, indicating the identifier scheme (e.g., "jwk", "dht"). PUBLIC DATA method: string - - /// ID is the method-specific identifier in the DID URI. - /// Spec: https://www.w3.org/TR/did-core/#method-specific-id. + + /// The method-specific identifier component in the DID URI. PUBLIC DATA id: string - - /// Params is a map containing optional parameters present in the DID URI. These parameters are method-specific. - /// Spec: https://www.w3.org/TR/did-core/#did-parameters. + + /// A map containing optional parameters present in the DID URI, which are method-specific. PUBLIC DATA params: Map? - - /// Path is an optional path component in the DID URI. - /// Spec: https://www.w3.org/TR/did-core/#path. + + /// An optional path component in the DID URI. PUBLIC DATA path: string? - - /// Query is an optional query component in the DID URI, used to express a request for a specific representation or resource related to the DID. - /// Spec: https://www.w3.org/TR/did-core/#query. + + /// An optional query component in the DID URI, used to express a request for a specific representation or resource. PUBLIC DATA query: string? - - /// Fragment is an optional fragment component in the DID URI, used to reference a specific part of a DID document. - /// Spec: https://www.w3.org/TR/did-core/#fragment. + + /// An optional fragment component in the DID URI, used to reference a specific part of a DID document. PUBLIC DATA fragment: string? - + + /// Parses a DID URI and constructs a new Did object. + /// + /// @param uri The DID URI to parse. CONSTRUCTOR parse(uri: string) ``` @@ -560,108 +853,88 @@ did = new Did(uri) ### `Document` ```pseudocode! -/// Representation of a [DID Document](https://github.com/TBD54566975/web5-spec/blob/main/spec/did.md) +/// Represents a DID Document according to the W3C DID Core Specification. +/// A DID Document contains the public keys, services, and other metadata associated with a DID. CLASS Document - /// The DID URI for a particular DID subject is expressed using the id property in the DID document. - PUBLIC DATA id: string + /// The DID URI for the subject of the DID Document. + PUBLIC DATA id: string + + /// An optional array of contexts defining the semantic meaning of the properties within the document. PUBLIC DATA @context: []string? - - /// A DID controller is an entity that is authorized to make changes to a - /// DID document. The process of authorizing a DID controller is defined - /// by the DID method. + + /// An optional array of DIDs that are authorized to control the DID Document. PUBLIC DATA controller: []string? - - /// A DID subject can have multiple identifiers for different purposes, or at - /// different times. The assertion that two or more DIDs (or other types of URI) - /// refer to the same DID subject can be made using the alsoKnownAs property. + + /// An optional array of other identifiers associated with the DID subject. PUBLIC DATA alsoKnownAs: []string? - - /// Cryptographic public keys, which can be used to authenticate or authorize - /// interactions with the DID subject or associated parties. - /// [spec reference](https://www.w3.org/TR/did-core/#verification-methods) + + /// An array of verification methods (e.g., public keys) associated with the DID subject. PUBLIC DATA verificationMethod: []VerificationMethod - - /// The authentication verification relationship is used to specify how the - /// DID subject is expected to be authenticated, for purposes such as logging - /// into a website or engaging in any sort of challenge-response protocol. - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#key-agreement) + + /// An optional array of methods for authenticating the DID subject. PUBLIC DATA authentication: []string? - - /// The assertionMethod verification relationship is used to specify how the - /// DID subject is expected to express claims, such as for the purposes of - /// issuing a Verifiable Credential - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#assertion) + + /// An optional array of methods for asserting claims on behalf of the DID subject. PUBLIC DATA assertionMethod: []string? - - /// The keyAgreement verification relationship is used to specify how an - /// entity can generate encryption material in order to transmit confidential - /// information intended for the DID subject, such as for the purposes of - /// establishing a secure communication channel with the recipient - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#key-agreement) + + /// An optional array of methods for establishing secure communication channels with the DID subject. PUBLIC DATA keyAgreement: []string? - - /// The capabilityInvocation verification relationship is used to specify a - /// verification method that might be used by the DID subject to invoke a - /// cryptographic capability, such as the authorization to update the - /// DID Document - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#capability-invocation) + + /// An optional array of methods for invoking cryptographic capabilities on behalf of the DID subject. PUBLIC DATA capabilityInvocation: []string? - - /// The capabilityDelegation verification relationship is used to specify a - /// mechanism that might be used by the DID subject to delegate a - /// cryptographic capability to another party, such as delegating the - /// authority to access a specific HTTP API to a subordinate. - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#capability-delegation) + + /// An optional array of methods for delegating cryptographic capabilities on behalf of the DID subject. PUBLIC DATA capabilityDelegation: []string? - - /// Services are used in DID documents to express ways of communicating with - /// the DID subject or associated entities. - /// A service can be any type of service the DID subject wants to advertise. - /// - /// [Specification Reference](https://www.w3.org/TR/did-core/#services) + + /// An optional array of services associated with the DID subject. PUBLIC DATA service: []Service? - + + /// Constructs a DID Document from a JSON string. + /// + /// @param json The JSON string representing the DID Document. CONSTRUCTOR from_json_string(json: string) + /// Converts the DID Document to a JSON string. + /// + /// @returns A JSON string representation of the DID Document. METHOD to_json_string(): string ``` ### `VerificationMethod` ```pseudocode! -/// Representation of a DID Document's [Verification Method](https://www.w3.org/TR/did-core/#verification-methods). +/// Represents a verification method in a DID Document. +/// A verification method is typically a cryptographic public key used for authenticating or authorizing actions. CLASS VerificationMethod - /// 🚧 - PUBLIC DATA id: string - /// 🚧 + /// The unique identifier for the verification method. + PUBLIC DATA id: string + + /// The type of the verification method (e.g., "JsonWebKey2020"). PUBLIC DATA type: string - - /// 🚧 + + /// The controller of the verification method, typically the DID subject or another authorized entity. PUBLIC DATA controller: string - - /// 🚧 + + /// The public key in JWK format associated with the verification method. PUBLIC DATA publicKeyJwk: Jwk ``` ### `Service` ```pseudocode! -/// Representation of a DID Document's [Service](https://www.w3.org/TR/did-core/#service). +/// Represents a service in a DID Document. +/// Services define ways to interact with the DID subject, such as communication endpoints or capabilities. CLASS Service - /// 🚧 - PUBLIC DATA id: string - /// 🚧 + /// The unique identifier for the service. + PUBLIC DATA id: string + + /// The type of the service (e.g., "MessagingService"). PUBLIC DATA type: string - - /// 🚧 + + /// The service endpoint, which can be a URL or other communication protocol. PUBLIC DATA serviceEndpoint: []string ``` @@ -670,78 +943,95 @@ CLASS Service ### `ResolutionResult` ```pseudocode! -/// Representation of the result of a DID (Decentralized Identifier) resolution. +/// Represents the result of resolving a Decentralized Identifier (DID). +/// Contains the resolved DID Document and associated metadata. CLASS ResolutionResult - /// The resolved DID document, if available. - PUBLIC DATA document: Document? - /// The metadata associated with the DID document. + /// The resolved DID Document, if available. + PUBLIC DATA document: Document? + + /// The metadata associated with the resolved DID Document. PUBLIC DATA document_metadata: DocumentMetadata? - - /// The metadata associated with the DID resolution process. + + /// The metadata associated with the resolution process. PUBLIC DATA resolution_metadata: ResolutionMetadata - - /// Resolve via a DID URI. - STATIC METHOD resolve(uri: string) -``` - -### `ResolutionResultResolveOptions` - -```pseudocode! -CLASS ResolutionResultResolveOptions: - PUBLIC DATA did_dht_gateway_url string? + + /// Resolves a DID and returns the corresponding ResolutionResult. + /// + /// @param uri The DID URI to resolve. + /// @returns The result of the DID resolution process. + CONSTRUCTOR resolve(uri: string) ``` ### `ResolutionMetadataError` ```pseudocode! -/// The error code from the resolution process. +/// Represents error codes from the DID resolution process. +/// Used to indicate specific issues encountered during resolution. ENUM ResolutionMetadataError + + /// The DID provided was invalid and resolution could not proceed. invalidDid + + /// The DID was not found during resolution. notFound + + /// The requested representation of the DID payload is not supported. representationNotSupported + + /// The DID method used is not supported by the resolver. methodNotSupported + + /// The DID Document found was invalid or not conformant. invalidDidDocument + + /// The DID Document length exceeded acceptable limits. invalidDidDocumentLength + + /// An internal error occurred during the DID resolution process. internalError ``` ### `ResolutionMetadata` ```pseudocode! -/// Metadata about the given resolution. +/// Represents the metadata associated with the resolution of a Decentralized Identifier (DID). +/// Provides information about the resolution process, including errors if any occurred. CLASS ResolutionMetadata - /// The error code from the resolution process. + + /// The error code from the resolution process, if an error occurred. PUBLIC DATA error: ResolutionMetadataError? ``` ### `DocumentMetadata` ```pseudocode! -/// Metadata about the DID Document. +/// Represents the metadata associated with a resolved DID Document. +/// Contains information about the lifecycle and versioning of the DID Document. CLASS DocumentMetadata - /// 🚧 - PUBLIC DATA created: string? - /// 🚧 + /// The timestamp when the DID Document was created. This is optional. + PUBLIC DATA created: string? + + /// The timestamp when the DID Document was last updated. This is optional. PUBLIC DATA updated: string? - - /// 🚧 + + /// Indicates whether the DID has been deactivated. This is optional. PUBLIC DATA deactivated: bool? - - /// 🚧 + + /// The timestamp for when the DID Document is scheduled for the next update. This is optional. PUBLIC DATA nextUpdate: string? - - /// 🚧 + + /// The identifier for the version of the DID Document. This is optional. PUBLIC DATA versionId: string? - - /// 🚧 + + /// The identifier for the next version of the DID Document. This is optional. PUBLIC DATA nextVersionId: string? - - /// 🚧 + + /// A list of equivalent DIDs, indicating alternative identifiers for the DID subject. This is optional. PUBLIC DATA equivalentId: []string? - - /// 🚧 + + /// The canonical identifier for the DID, representing its authoritative form. This is optional. PUBLIC DATA canonicalId: string? ``` @@ -750,16 +1040,34 @@ CLASS DocumentMetadata ### `DidJwk` ```pseudocode! +/// Represents a DID using the JWK (JSON Web Key) method. +/// Provides methods for creating and resolving DIDs based on JWKs. CLASS DidJwk + + /// Creates a new DID based on a JWK with the specified options. + /// + /// @param options Optional parameters for creating the DID. + /// @returns A BearerDid instance representing the created DID. STATIC METHOD create(options: DidJwkCreateOptions?): BearerDid + + /// Resolves a DID JWK URI and returns the corresponding ResolutionResult. + /// + /// @param uri The DID JWK URI to resolve. + /// @returns The result of the DID resolution process. STATIC METHOD resolve(uri: string): ResolutionResult ``` #### `DidJwkCreateOptions` ```pseudocode! +/// Represents the options available when creating a DID using the JWK method. +/// Allows customization of key management and signature algorithms. CLASS DidJwkCreateOptions + + /// The key manager responsible for handling key material. This is optional. PUBLIC DATA key_manager: KeyManager? + + /// The digital signature algorithm to be used (e.g., "Ed25519", "Secp256k1"). This is optional. PUBLIC DATA dsa: Dsa? ``` @@ -770,29 +1078,74 @@ CLASS DidJwkCreateOptions > The `create` does not publish the DID Document to a host, but creates the instance of the `did:web` `BearerDid` in the local scope. ```pseudocode! +/// Represents a DID using the Web method. +/// Provides methods for creating and resolving DIDs based on domain names. CLASS DidWeb + + /// Creates a new DID based on a domain name with the specified options. + /// + /// @param domain The domain name to associate with the DID. + /// @param options Optional parameters for creating the DID. + /// @returns A BearerDid instance representing the created DID. STATIC METHOD create(domain: string, options: DidWebCreateOptions?): BearerDid + + /// Resolves a DID Web URI and returns the corresponding ResolutionResult. + /// + /// @param uri The DID Web URI to resolve. + /// @returns The result of the DID resolution process. STATIC METHOD resolve(uri: string): ResolutionResult ``` #### `DidWebCreateOptions` ```pseudocode! +/// Represents the options available when creating a DID using the Web method. +/// Allows customization of the DID's services, controllers, and verification methods. CLASS DidWebCreateOptions + + /// The key manager responsible for handling key material. This is optional. PUBLIC DATA key_manager: KeyManager? + + /// The digital signature algorithm to be used (e.g., "Ed25519", "Secp256k1"). This is optional. PUBLIC DATA dsa: Dsa? + + /// An optional array of services associated with the DID. PUBLIC DATA service: []Service? + + /// An optional array of controllers authorized to manage the DID. PUBLIC DATA controller: []string? + + /// An optional array of additional DIDs associated with the subject. PUBLIC DATA also_known_as: []string? + + /// An optional array of verification methods (e.g., public keys) associated with the DID. PUBLIC DATA verification_method: []VerificationMethod? ``` ### `DidDht` ```pseudocode! +/// Represents a DID using the DHT (Distributed Hash Table) method. +/// Provides methods for creating, publishing, and resolving DIDs on a DHT network. CLASS DidDht + + /// Creates a new DID using the DHT method with the specified options. + /// + /// @param options Optional parameters for creating the DID. + /// @returns A BearerDid instance representing the created DID. STATIC METHOD create(options: DidDhtCreateOptions?): BearerDid + + /// Publishes the DID Document to the specified DHT gateway. + /// + /// @param bearer_did The DID to be published. + /// @param gateway_url Optional URL of the DHT gateway where the DID Document will be published. STATIC METHOD publish(bearer_did: BearerDid, gateway_url: string?) + + /// Resolves a DID DHT URI and returns the corresponding ResolutionResult. + /// + /// @param uri The DID DHT URI to resolve. + /// @param gateway_url Optional URL of the DHT gateway to use for resolving the DID. + /// @returns The result of the DID resolution process. STATIC METHOD resolve(uri: string, gateway_url: string?): ResolutionResult ``` @@ -802,27 +1155,63 @@ CLASS DidDht #### `DidDhtCreateOptions` ```pseudocode! +/// Represents the options available when creating a DID using the DHT method. +/// Allows customization of the DID's services, controllers, and verification methods. CLASS DidDhtCreateOptions + + /// The key manager responsible for handling key material. This is optional. PUBLIC DATA key_manager: KeyManager? + + /// An optional array of services associated with the DID. PUBLIC DATA service: []Service? + + /// An optional array of controllers authorized to manage the DID. PUBLIC DATA controller: []string? + + /// An optional array of additional DIDs associated with the subject. PUBLIC DATA also_known_as: []string? + + /// An optional array of verification methods (e.g., public keys) associated with the DID. PUBLIC DATA verification_method: []VerificationMethod? + + /// A flag indicating whether the DID should be published upon creation. Defaults to true. PUBLIC DATA publish: bool? = true + + /// The URL of the DHT gateway to use for publishing or resolving the DID. This is optional. PUBLIC DATA gateway_url: string? ``` ## `BearerDid` ```pseudocode! +/// Represents a Bearer Decentralized Identifier (DID). +/// A BearerDid contains both the DID and the associated DID Document along with the key management logic. CLASS BearerDid + + /// The DID associated with this BearerDid instance. PUBLIC DATA did: Did + + /// The DID Document associated with this BearerDid instance. PUBLIC DATA document: Document + + /// The key manager responsible for handling cryptographic operations for this DID. PUBLIC DATA key_manager: KeyManager + /// Creates a new BearerDid from a PortableDid instance. + /// + /// @param portable_did The PortableDid instance to convert into a BearerDid. CONSTRUCTOR from_portable_did(portable_did: PortableDid) + /// Converts the BearerDid into a PortableDid by exporting the private key material. + /// + /// @param key_exporter The KeyExporter instance used to export private key material. + /// @returns A PortableDid instance representing the BearerDid. METHOD to_portable_did(key_exporter: KeyExporter): PortableDid + + /// Retrieves a signer for the specified verification method associated with this BearerDid. + /// + /// @param verification_method_id The identifier of the verification method to retrieve the signer for. + /// @returns A Signer instance for the specified verification method. METHOD get_signer(verification_method_id: string): Signer ``` @@ -835,12 +1224,28 @@ The `PortableDid` is a JSON serialized representation of a `BearerDid`. > The `PortableDid` contains **serialized private key material** and it is therefore **NOT SAFE** for production environments; the `PortableDid` is primarily intended for usage in development & testing environments. ```pseudocode! +/// Represents a Portable Decentralized Identifier (DID). +/// A PortableDid is a JSON-serialized representation of a BearerDid, including private key material. +/// This format is primarily intended for development and testing environments. CLASS PortableDid - DATA MEMBER uri: string - DATA MEMBER private_jwks: []Jwk - DATA MEMBER document: Document + + /// The URI representing the PortableDid. + PUBLIC DATA uri: string + + /// An array of private JWKs (JSON Web Keys) associated with the PortableDid. + PUBLIC DATA private_jwks: []Jwk + /// The DID Document associated with the PortableDid. + PUBLIC DATA document: Document + + /// Creates a new PortableDid from a JSON string. + /// + /// @param json The JSON string representing the PortableDid. CONSTRUCTOR from_json_string(json: string) + + /// Converts the PortableDid to a JSON string. + /// + /// @returns A JSON string representation of the PortableDid. METHOD to_json_string(): string ``` From 10406e3622fe8273a1b56746c4f984483e9e84f7 Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Thu, 12 Sep 2024 18:36:59 -0400 Subject: [PATCH 02/16] Add rust doc comments for vc --- .../src/credentials/status_list_credential.rs | 11 +++ .../credentials/verifiable_credential_1_1.rs | 74 ++++++++++++++++++- docs/API_DESIGN.md | 3 + 3 files changed, 86 insertions(+), 2 deletions(-) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index 9a4908e6..a22eeb35 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -13,11 +13,22 @@ pub const STATUS_LIST_2021: &str = "StatusList2021"; pub const STATUS_LIST_2021_ENTRY: &str = "StatusList2021Entry"; +/// 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. pub struct StatusListCredential { + /// The base Verifiable Credential associated with the Status List. pub base: VerifiableCredential, } impl StatusListCredential { + /// Creates a new Status List Credential with the specified issuer, status purpose, + /// and the list of disabled credentials. + /// + /// # Arguments + /// + /// * `issuer` - The entity issuing the Status List Credential. + /// * `status_purpose` - The purpose of the status (e.g., "revocation"). + /// * `disabled_credentials` - A list of Verifiable Credentials that are disabled (revoked or suspended). pub fn create( issuer: Issuer, status_purpose: String, diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index 3204b16f..bb9176d4 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -4,7 +4,6 @@ use super::data_model_validation::validate_vc_data_model; use super::decode::decode; use super::CredentialSubject; use super::Issuer; - use crate::datetime::{ deserialize_optional_rfc3339, deserialize_rfc3339, serialize_optional_rfc3339, serialize_rfc3339, @@ -20,22 +19,37 @@ use std::time::SystemTime; pub const BASE_CONTEXT: &str = "https://www.w3.org/2018/credentials/v1"; pub const BASE_TYPE: &str = "VerifiableCredential"; +/// Represents a Verifiable Credential according to the W3C Verifiable Credentials Data Model. +/// A Verifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified. #[derive(Serialize, Deserialize, Debug, Clone)] pub struct VerifiableCredential { + /// A list of contexts used to define the semantic meaning of the data contained in the Verifiable Credential. #[serde(rename = "@context")] pub context: Vec, + + /// The unique identifier for the Verifiable Credential. pub id: String, + + /// The type(s) of the Verifiable Credential, typically includes "VerifiableCredential". #[serde(rename = "type")] pub r#type: Vec, + + /// The entity (either a string or an object) that issued the credential. pub issuer: Issuer, + + /// The subject of the credential, containing claims about the entity being described by the credential. #[serde(rename = "credentialSubject")] pub credential_subject: CredentialSubject, + + /// The date and time when the credential was issued. #[serde( rename = "issuanceDate", serialize_with = "serialize_rfc3339", deserialize_with = "deserialize_rfc3339" )] pub issuance_date: SystemTime, + + /// The optional expiration date and time after which the credential is no longer valid. #[serde( rename = "expirationDate", serialize_with = "serialize_optional_rfc3339", @@ -44,10 +58,16 @@ pub struct VerifiableCredential { default )] pub expiration_date: Option, + + /// The credential status information, if applicable (e.g., revoked or suspended). #[serde(rename = "credentialStatus", skip_serializing_if = "Option::is_none")] pub credential_status: Option, + + /// The credential schema, used to validate the data structure of the credential. #[serde(rename = "credentialSchema", skip_serializing_if = "Option::is_none")] pub credential_schema: Option, + + /// An array of evidence supporting the claims made in the credential. #[serde(skip_serializing_if = "Option::is_none")] pub evidence: Option>, } @@ -55,32 +75,67 @@ pub struct VerifiableCredential { impl FromJson for VerifiableCredential {} impl ToJson for VerifiableCredential {} +/// Represents the options available when creating a Verifiable Credential. +/// These options allow customization of various attributes of the credential during its creation. #[derive(Default, Clone)] pub struct VerifiableCredentialCreateOptions { + /// The unique identifier for the Verifiable Credential. This is optional. pub id: Option, + + /// The context(s) for the Verifiable Credential, which define the meaning of terms within the credential. pub context: Option>, + + /// The type(s) of the Verifiable Credential. Typically includes "VerifiableCredential". pub r#type: Option>, + + /// The issuance date of the credential. If not provided, defaults to the current date and time. pub issuance_date: Option, + + /// The optional expiration date for the credential, after which it is no longer valid. pub expiration_date: Option, + + /// The optional credential status, which indicates revocation or suspension information. pub credential_status: Option, + + /// The credential schema, used to validate the data structure of the credential. This is optional. pub credential_schema: Option, + + /// An optional array of evidence supporting the claims made in the credential. pub evidence: Option>, } +/// Represents the status information of a Verifiable Credential. +/// CredentialStatus is used to indicate the revocation or suspension status of a credential. #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] pub struct CredentialStatus { + /// The unique identifier for the credential status. pub id: String, + + /// The type(s) of the credential status, typically includes "CredentialStatus". #[serde(rename = "type")] pub r#type: String, + + /// The purpose of the status (e.g., "revocation" or "suspension"). #[serde(rename = "statusPurpose")] pub status_purpose: String, + + /// The index in the status list indicating the credential's position. #[serde(rename = "statusListIndex")] pub status_list_index: String, + + /// The unique identifier for the Verifiable Credential that lists the status of the credential. #[serde(rename = "statusListCredential")] pub status_list_credential: String, } impl VerifiableCredential { + /// Creates a new Verifiable Credential with the specified issuer, subject, and optional creation options. + /// + /// # Arguments + /// + /// * `issuer` - The entity issuing the credential. + /// * `credential_subject` - The subject of the credential containing claims. + /// * `options` - Optional parameters for creating the credential, such as schema or status. pub fn create( issuer: Issuer, credential_subject: CredentialSubject, @@ -89,7 +144,12 @@ impl VerifiableCredential { super::create::create_vc(issuer, credential_subject, options) } - // this function currently only supports Ed25519 + /// Constructs a Verifiable Credential from a VC JWT (JSON Web Token). + /// + /// # Arguments + /// + /// * `vc_jwt` - The Verifiable Credential in JWT format. + /// * `verify` - If true, verifies the integrity of the JWT before creating the credential. pub fn from_vc_jwt(vc_jwt: &str, verify: bool) -> Result { let verifiable_credential = decode(vc_jwt, verify)?; @@ -101,6 +161,16 @@ impl VerifiableCredential { Ok(verifiable_credential) } + /// Signs the Verifiable Credential using the specified Bearer DID and optional verification method. + /// + /// # Arguments + /// + /// * `bearer_did` - The DID used to sign the credential. + /// * `verification_method_id` - Optional identifier for the verification method. + /// + /// # Returns + /// + /// A string representing the signed JWT of the Verifiable Credential. pub fn sign( &self, bearer_did: &BearerDid, diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index 4ea11fd2..1b42e128 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -201,6 +201,9 @@ CLASS VerifiableCredentialCreateOptions /// The optional credential status, which indicates revocation or suspension information. PUBLIC DATA credential_status: CredentialStatus? + + /// The credential schema, used to validate the data structure of the credential. This is optional. + PUBLIC DATA credential_schema: CredentialSchema? /// An optional array of evidence supporting the claims made in the credential. PUBLIC DATA evidence: []Evidence? From 3ee519e124d84e414d937c24634d8cad173a741f Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Fri, 13 Sep 2024 09:28:43 -0400 Subject: [PATCH 03/16] Add doc comments for vp --- Justfile | 3 + .../credentials/presentation_definition.rs | 2 +- .../credentials/verifiable_credential_1_1.rs | 80 +++++++++++-- .../verifiable_presentation_1_1.rs | 105 ++++++++++++++++++ docs/API_DESIGN.md | 48 +++++--- 5 files changed, 209 insertions(+), 29 deletions(-) diff --git a/Justfile b/Justfile index 084cadb0..b21c8ef5 100644 --- 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/crates/web5/src/credentials/presentation_definition.rs b/crates/web5/src/credentials/presentation_definition.rs index 1351b506..fc78c9a1 100644 --- a/crates/web5/src/credentials/presentation_definition.rs +++ b/crates/web5/src/credentials/presentation_definition.rs @@ -188,7 +188,7 @@ impl PresentationDefinition { /// * `presentation_definition` - The Presentation Definition V2 object against which VCs are validated. /// /// # Returns - /// A `PresentationResult` which holds the `PresentationSubmission` and a Vec which has the vc_jwts that were used + /// A `PresentationResult` which holds the `PresentationSubmission` and a `Vec` which has the vc_jwts that were used /// A `PresentationSubmission` object. /// A `Vec` which contains the chosen vc_jwts pub fn create_presentation_from_credentials( diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index bb9176d4..282dc9bf 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -19,7 +19,8 @@ use std::time::SystemTime; pub const BASE_CONTEXT: &str = "https://www.w3.org/2018/credentials/v1"; pub const BASE_TYPE: &str = "VerifiableCredential"; -/// Represents a Verifiable Credential according to the W3C Verifiable Credentials Data Model. +/// Represents a Verifiable Credential according to the [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) +/// and conformant to the [Web5 specification](https://tbd54566975.github.io/web5-spec/#verifiable-credentials-vcs). /// A Verifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified. #[derive(Serialize, Deserialize, Debug, Clone)] pub struct VerifiableCredential { @@ -30,7 +31,7 @@ pub struct VerifiableCredential { /// The unique identifier for the Verifiable Credential. pub id: String, - /// The type(s) of the Verifiable Credential, typically includes "VerifiableCredential". + /// The type(s) of the Verifiable Credential. #[serde(rename = "type")] pub r#type: Vec, @@ -80,12 +81,17 @@ impl ToJson for VerifiableCredential {} #[derive(Default, Clone)] pub struct VerifiableCredentialCreateOptions { /// The unique identifier for the Verifiable Credential. This is optional. + /// If not provided then the default value will be of format urn:uuid:{uuid}. pub id: Option, /// The context(s) for the Verifiable Credential, which define the meaning of terms within the credential. + /// The base context `` is always the first value whereafter values provided here will be appended onto. + /// If the base context is also provided here then it will be de-duplicated against the base context referred to above. pub context: Option>, - /// The type(s) of the Verifiable Credential. Typically includes "VerifiableCredential". + /// The type(s) of the Verifiable Credential. + /// The base type VerifiableCredential will always be the first value whereafter values provided here will be appeneded onto. + /// If the base type is also provided here then it will be de-duplicated against the base type referred to above. pub r#type: Option>, /// The issuance date of the credential. If not provided, defaults to the current date and time. @@ -94,10 +100,11 @@ pub struct VerifiableCredentialCreateOptions { /// The optional expiration date for the credential, after which it is no longer valid. pub expiration_date: Option, - /// The optional credential status, which indicates revocation or suspension information. + /// The optional credential status, which may indicate revocation or suspension information. pub credential_status: Option, /// The credential schema, used to validate the data structure of the credential. This is optional. + /// JSON Schema validation is performed if the value is provided, and creation will fail if validation fails. pub credential_schema: Option, /// An optional array of evidence supporting the claims made in the credential. @@ -133,9 +140,29 @@ impl VerifiableCredential { /// /// # Arguments /// - /// * `issuer` - The entity issuing the credential. - /// * `credential_subject` - The subject of the credential containing claims. + /// * `issuer` - The entity issuing the credential. The `issuer` must be a valid DID. + /// * `credential_subject` - The subject of the credential containing claims. The subject must be a valid DID. /// * `options` - Optional parameters for creating the credential, such as schema or status. + /// + /// # Example + /// ``` + /// use web5::credentials::VerifiableCredential; + /// use web5::credentials::CredentialSubject; + /// use web5::credentials::Issuer; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let issuer_bearer_did = DidJwk::create(None).unwrap(); + /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; + /// + /// let verifiable_credential = VerifiableCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// CredentialSubject { + /// id: subject_did_uri.to_string(), + /// additional_properties: None, + /// }, + /// None, + /// ).unwrap(); + /// ``` pub fn create( issuer: Issuer, credential_subject: CredentialSubject, @@ -148,8 +175,17 @@ impl VerifiableCredential { /// /// # Arguments /// - /// * `vc_jwt` - The Verifiable Credential in JWT format. - /// * `verify` - If true, verifies the integrity of the JWT before creating the credential. + /// * `vc_jwt` - The Verifiable Credential in JWT format, serialized as a compact JWS. + /// * `verify` - If true, verifies the integrity of the JWT by performing cryptographic verification against the signature, validating the VC Data Model, and validates the JSON Schema if present. + /// + /// # Example + /// ``` + /// use web5::credentials::VerifiableCredential; + /// + /// let vc_jwt = r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"#; + /// let verifiable_credential = + /// VerifiableCredential::from_vc_jwt(vc_jwt, true).unwrap(); + /// ``` pub fn from_vc_jwt(vc_jwt: &str, verify: bool) -> Result { let verifiable_credential = decode(vc_jwt, verify)?; @@ -166,11 +202,35 @@ impl VerifiableCredential { /// # Arguments /// /// * `bearer_did` - The DID used to sign the credential. - /// * `verification_method_id` - Optional identifier for the verification method. + /// * `verification_method_id` - Optional identifier of the Verification Method for which to sign with. /// /// # Returns /// - /// A string representing the signed JWT of the Verifiable Credential. + /// A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Credential. + /// + /// # Example + /// ``` + /// use web5::credentials::VerifiableCredential; + /// use web5::credentials::CredentialSubject; + /// use web5::credentials::Issuer; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let issuer_bearer_did = DidJwk::create(None).unwrap(); + /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; + /// + /// let verifiable_credential = VerifiableCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// CredentialSubject { + /// id: subject_did_uri.to_string(), + /// additional_properties: None, + /// }, + /// None, + /// ).unwrap(); + /// + /// let vc_jwt = verifiable_credential + /// .sign(&issuer_bearer_did, None) + /// .unwrap(); + /// ``` pub fn sign( &self, bearer_did: &BearerDid, diff --git a/crates/web5/src/credentials/verifiable_presentation_1_1.rs b/crates/web5/src/credentials/verifiable_presentation_1_1.rs index 2a7d2704..b3ed3334 100644 --- a/crates/web5/src/credentials/verifiable_presentation_1_1.rs +++ b/crates/web5/src/credentials/verifiable_presentation_1_1.rs @@ -18,20 +18,34 @@ use uuid::Uuid; pub const BASE_PRESENTATION_CONTEXT: &str = "https://www.w3.org/2018/credentials/v1"; pub const BASE_PRESENTATION_TYPE: &str = "VerifiablePresentation"; +/// Represents a Verifiable Presentation according to the [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/#presentations-0) +/// and conformant to the [Web5 specification](https://tbd54566975.github.io/web5-spec/#verifiable-presentation-v11-data-model). +/// A Verifiable Presentation allows a holder to present one or more #[derive(Serialize, Deserialize, Debug, Clone)] pub struct VerifiablePresentation { + /// A list of contexts used to define the semantic meaning of the data contained in the presentation. #[serde(rename = "@context")] pub context: Vec, + + /// The unique identifier for the Verifiable Presentation. pub id: String, + + /// The type(s) of the Verifiable Presentation. #[serde(rename = "type")] pub r#type: Vec, + + /// The holder of the Verifiable Presentation, identified by a DID or other identifier. pub holder: String, + + /// The date and time when the presentation was issued. #[serde( rename = "issuanceDate", serialize_with = "serialize_rfc3339", deserialize_with = "deserialize_rfc3339" )] pub issuance_date: SystemTime, + + /// The optional expiration date and time after which the presentation is no longer valid. #[serde( rename = "expirationDate", serialize_with = "serialize_optional_rfc3339", @@ -40,19 +54,41 @@ pub struct VerifiablePresentation { default )] pub expiration_date: Option, + + /// A list of Verifiable Credentials contained within the presentation. #[serde(rename = "verifiableCredential")] pub verifiable_credential: Vec, + + /// Additional data that may be included in the presentation, represented as a key-value map. #[serde(flatten)] pub additional_data: Option>, } +/// Represents the options available when creating a Verifiable Presentation. +/// These options allow customization of various attributes of the presentation during its creation. #[derive(Default, Clone)] pub struct VerifiablePresentationCreateOptions { + /// The unique identifier for the Verifiable Presentation. This is optional. + /// If not provided then the default value will be of format urn:uuid:{uuid}. pub id: Option, + + /// The context(s) for the Verifiable Presentation, which define the meaning of terms within the presentation. + /// The base context `` is always the first value whereafter values provided here will be appended onto. + /// If the base context is also provided here then it will be de-duplicated against the base context referred to above. pub context: Option>, + + /// The type(s) of the Verifiable Presentation. + /// The base type VerifiablePresentation will always be the first value whereafter values provided here will be appeneded onto. + /// If the base type is also provided here then it will be de-duplicated against the base type referred to above. pub r#type: Option>, + + /// The issuance date of the presentation. If not provided, defaults to the current date and time. pub issuance_date: Option, + + /// The optional expiration date for the presentation, after which it is no longer valid. pub expiration_date: Option, + + /// Additional data that may be included in the presentation, represented as a key-value map. pub additional_data: Option>, } @@ -112,6 +148,30 @@ impl ToJsonValue for JwtPayloadVerifiablePresentation { } impl VerifiablePresentation { + /// Creates a new Verifiable Presentation with the specified holder, Verifiable Credential JWTs, + /// and optional creation options. + /// + /// # Arguments + /// + /// * `holder` - The entity holding and presenting the Verifiable Presentation. The holder must be a valid DID. + /// * `vc_jwts` - A list of Verifiable Credential JWTs to include in the presentation. All `vc_jwt` values are verified, and the call will fail if any fail verification. + /// * `options` - Optional parameters for creating the presentation, such as context or expiration. + /// + /// # Example + /// ```rust + /// use web5::credentials::VerifiablePresentation; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let holder_bearer_did = DidJwk::create(None).unwrap(); + /// let vc_jwts = vec![String::from( + /// r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"# + /// )]; + /// let verifiable_presentation = VerifiablePresentation::create( + /// holder_bearer_did.did.uri.clone(), + /// vc_jwts, + /// None, + /// ).unwrap(); + /// ``` pub fn create( holder: String, vc_jwts: Vec, @@ -150,6 +210,21 @@ impl VerifiablePresentation { Ok(verifiable_presentation) } + /// Constructs a Verifiable Presentation from a VP JWT (JSON Web Token). + /// + /// # Arguments + /// + /// * `vp_jwt` - The Verifiable Presentation in JWT format, serialized as a compact JWS. + /// * `verify` - If true, verifies the integrity of the JWT by performing cryptographic verification + /// against the signature and validating the Data Model. + /// + /// # Example + /// ```rust + /// use web5::credentials::VerifiablePresentation; + /// + /// let vp_jwt = r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKYWNUaFJaR05XYlRrMlluZGpRa3R3WVhwV2RGQmlkekJ6U1c4NE0wbG9XRXAyVGtoV1VIUnpWWFYzSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUphY1RoUlpHTldiVGsyWW5kalFrdHdZWHBXZEZCaWR6QnpTVzg0TTBsb1dFcDJUa2hXVUhSelZYVjNJbjAiLCJqdGkiOiJ1cm46dXVpZDowZDg5YTcxMS0zNTdjLTQzNTQtOWYzMS02OWQ0NDE1NWQ1ZTMiLCJuYmYiOjE3MjYyMzQwODEsImlhdCI6MTcyNjIzNDA4MSwidnAiOnsiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMzoyODowMVoiLCJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50YXRpb24iXSwidmVyaWZpYWJsZUNyZWRlbnRpYWwiOlsiZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKRlpESTFOVEU1SWl3aWEybGtJam9pWkdsa09tcDNhenBsZVVwb1lrZGphVTlwU2taYVJFa3hUbFJGTlVscGQybGhNMUkxU1dwdmFWUXdkRkZKYVhkcFdUTktNa2xxYjJsU1YxRjVUbFJWZUU5VFNYTkpibWRwVDJsS1VWRnNiRTVTYlRreFdUQnpOVk16WkZCVFNGSjZUbXBvVTA1RlZuZGpiVmw1VFhwT1RFNVVVazFOVmxaSlRqRlNTV05VVW1aaE1HaE9TVzR3SXpBaWZRLmV5SnBjM01pT2lKa2FXUTZhbmRyT21WNVNtaGlSMk5wVDJsS1JscEVTVEZPVkVVMVNXbDNhV0V6VWpWSmFtOXBWREIwVVVscGQybFpNMG95U1dwdmFWSlhVWGxPVkZWNFQxTkpjMGx1WjJsUGFVcFJVV3hzVGxKdE9URlpNSE0xVXpOa1VGTklVbnBPYW1oVFRrVldkMk50V1hsTmVrNU1UbFJTVFUxV1ZrbE9NVkpKWTFSU1ptRXdhRTVKYmpBaUxDSnFkR2tpT2lKMWNtNDZkWFZwWkRwaE1UaGlOREppWVMwMk1UVTVMVFExWVRrdFlXTXpZaTB5TnpaaVlqQmtORGRpWmpZaUxDSnpkV0lpT2lKa2FXUTZaR2gwT201bk5HaHRjWFJ5WjNWcWIzZzBZV2R3WmpodmEzaHBhRzU1ZVRGNmNXNXhPVGR4Wm1WeE1UVjRPRzloY2pkNVpYQjZhSGtpTENKdVltWWlPakUzTWpZeU16RTVOeklzSW1saGRDSTZNVGN5TmpJek1UazNNaXdpZG1NaU9uc2lRR052Ym5SbGVIUWlPbHNpYUhSMGNITTZMeTkzZDNjdWR6TXViM0puTHpJd01UZ3ZZM0psWkdWdWRHbGhiSE12ZGpFaVhTd2lZM0psWkdWdWRHbGhiRk4xWW1wbFkzUWlPbnNpYVdRaU9pSmthV1E2WkdoME9tNW5OR2h0Y1hSeVozVnFiM2cwWVdkd1pqaHZhM2hwYUc1NWVURjZjVzV4T1RkeFptVnhNVFY0T0c5aGNqZDVaWEI2YUhraWZTd2lhWE56ZFdWeUlqb2laR2xrT21wM2F6cGxlVXBvWWtkamFVOXBTa1phUkVreFRsUkZOVWxwZDJsaE0xSTFTV3B2YVZRd2RGRkphWGRwV1ROS01rbHFiMmxTVjFGNVRsUlZlRTlUU1hOSmJtZHBUMmxLVVZGc2JFNVNiVGt4V1RCek5WTXpaRkJUU0ZKNlRtcG9VMDVGVm5kamJWbDVUWHBPVEU1VVVrMU5WbFpKVGpGU1NXTlVVbVpoTUdoT1NXNHdJaXdpYVhOemRXRnVZMlZFWVhSbElqb2lNakF5TkMwd09TMHhNMVF4TWpvMU1qbzFNbG9pTENKMGVYQmxJanBiSWxabGNtbG1hV0ZpYkdWRGNtVmtaVzUwYVdGc0lsMHNJbWxrSWpvaWRYSnVPblYxYVdRNllURTRZalF5WW1FdE5qRTFPUzAwTldFNUxXRmpNMkl0TWpjMlltSXdaRFEzWW1ZMkluMTkuaUNkN1FsQWlCTkxDZnZ0VWJCdGstOVBUcUZmdWNxWjQ0S3hoRnZqR2NSU2prR0pyNjEwLTBqTFZzTlNBX0NQOGdibFljZncxZTVqeDNwR2VFckMtQnciXSwiaG9sZGVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKYWNUaFJaR05XYlRrMlluZGpRa3R3WVhwV2RGQmlkekJ6U1c4NE0wbG9XRXAyVGtoV1VIUnpWWFYzSW4wIiwiaWQiOiJ1cm46dXVpZDowZDg5YTcxMS0zNTdjLTQzNTQtOWYzMS02OWQ0NDE1NWQ1ZTMifX0.f-kdfbIIms3Gg2dMKUMayeU1rQnaO_o0io33kLzy-uPqI6vsdsJZvSmDIilx7scRqlia7Pmnnj6bnF2x8F2fAw"#; + /// let verifiable_presentation = VerifiablePresentation::from_vp_jwt(vp_jwt, true).unwrap(); + /// ``` pub fn from_vp_jwt(vp_jwt: &str, verify: bool) -> Result { let verifiable_presentation = decode_vp_jwt(vp_jwt, verify)?; @@ -160,6 +235,36 @@ impl VerifiablePresentation { Ok(verifiable_presentation) } + /// Signs the Verifiable Presentation using the specified Bearer DID and optional verification method. + /// + /// # Arguments + /// + /// * `bearer_did` - The DID used to sign the presentation. + /// * `verification_method_id` - Optional identifier of the Verification Method to sign with. + /// + /// # Returns + /// + /// A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Presentation. + /// + /// # Example + /// ```rust + /// use web5::credentials::VerifiablePresentation; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let holder_bearer_did = DidJwk::create(None).unwrap(); + /// let vc_jwts = vec![String::from( + /// r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"# + /// )]; + /// let verifiable_presentation = VerifiablePresentation::create( + /// holder_bearer_did.did.uri.clone(), + /// vc_jwts, + /// None, + /// ).unwrap(); + /// + /// let vp_jwt = verifiable_presentation + /// .sign(&holder_bearer_did, None) + /// .unwrap(); + /// ``` pub fn sign( &self, bearer_did: &BearerDid, diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index 1b42e128..fba2d745 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -87,7 +87,7 @@ #### `VerifiableCredential` ```pseudocode! -/// Represents a Verifiable Credential according to the W3C Verifiable Credentials Data Model. +/// Represents a Verifiable Credential according to the [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) and conformant to the [Web5 specification](https://tbd54566975.github.io/web5-spec/#verifiable-credentials-vcs). /// A Verifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified. CLASS VerifiableCredential @@ -97,7 +97,7 @@ CLASS VerifiableCredential /// The unique identifier for the Verifiable Credential. PUBLIC DATA id: string - /// The type(s) of the Verifiable Credential, typically includes "VerifiableCredential". + /// The type(s) of the Verifiable Credential. PUBLIC DATA type: []string /// The entity (either a string or an object) that issued the credential. @@ -123,22 +123,22 @@ CLASS VerifiableCredential /// Creates a new Verifiable Credential with the specified issuer, subject, and optional creation options. /// - /// @param issuer The entity issuing the credential. - /// @param credential_subject The subject of the credential containing claims. + /// @param issuer The entity issuing the credential. The issuer must be a valid DID. + /// @param credential_subject 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. CONSTRUCTOR create(issuer: Issuer, credential_subject: CredentialSubject, options: VerifiableCredentialCreateOptions?) /// Constructs a Verifiable Credential from a VC JWT (JSON Web Token). /// - /// @param vc_jwt The Verifiable Credential in JWT format. - /// @param verify If true, verifies the integrity of the JWT before creating the credential. + /// @param vc_jwt 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 validates the JSON Schema if present. CONSTRUCTOR from_vc_jwt(vc_jwt: string, verify: bool) /// Signs the Verifiable Credential using the specified Bearer DID and optional verification method. /// /// @param bearer_did The DID used to sign the credential. - /// @param verification_method_id Optional identifier for the verification method. - /// @returns A string representing the signed JWT of the Verifiable Credential. + /// @param verification_method_id Optional identifier of the Verification Method for which to sign with. + /// @returns A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Credential. METHOD sign(bearer_did: BearerDid, verification_method_id: String?): string ``` @@ -185,12 +185,17 @@ CLASS CredentialStatus CLASS VerifiableCredentialCreateOptions /// The unique identifier for the Verifiable Credential. This is optional. + /// If not provided the default value will be of format urn:uuid:{uuid}. PUBLIC DATA id: string? /// The context(s) for the Verifiable Credential, which define the meaning of terms within the credential. + /// The base context https://www.w3.org/2018/credentials/v1 is always the first value whereafter values provided here will be appended. + /// If the base context is also provided here it will be de-duplicated against the base context already applied by default. PUBLIC DATA context: []string? - /// The type(s) of the Verifiable Credential. Typically includes "VerifiableCredential". + /// The type(s) of the Verifiable Credential. + /// The base type VerifiableCredential will always be the first value whereafter values provided here will be appeneded onto. + /// If the base type is also provided here then it will be de-duplicated against the base type referred to above. PUBLIC DATA type: []string? /// The issuance date of the credential. If not provided, defaults to the current date and time. @@ -203,6 +208,7 @@ CLASS VerifiableCredentialCreateOptions PUBLIC DATA credential_status: CredentialStatus? /// The credential schema, used to validate the data structure of the credential. This is optional. + /// JSON Schema validation is performed if the value is provided, and creation will fail if validation fails. PUBLIC DATA credential_schema: CredentialSchema? /// An optional array of evidence supporting the claims made in the credential. @@ -240,7 +246,8 @@ CLASS StatusListCredential #### `VerifiablePresentation` ```pseudocode! -/// Represents a Verifiable Presentation according to the W3C Verifiable Credentials Data Model. +/// Represents a Verifiable Presentation according to the [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/#presentations-0) +/// and conformant to the [Web5 specification](https://tbd54566975.github.io/web5-spec/#verifiable-presentation-v11-data-model). /// A Verifiable Presentation allows a holder to present one or more Verifiable Credentials to a verifier. CLASS VerifiablePresentation @@ -250,7 +257,7 @@ CLASS VerifiablePresentation /// The unique identifier for the Verifiable Presentation. PUBLIC DATA id: string - /// The type(s) of the Verifiable Presentation, typically includes "VerifiablePresentation". + /// The type(s) of the Verifiable Presentation. PUBLIC DATA type: []string /// The holder of the Verifiable Presentation, identified by a DID or other identifier. @@ -270,22 +277,22 @@ CLASS VerifiablePresentation /// Creates a new Verifiable Presentation with the specified holder, Verifiable Credential JWTs, and optional creation options. /// - /// @param holder The entity holding and presenting the Verifiable Presentation. - /// @param vc_jwts A list of Verifiable Credential JWTs to include in the presentation. + /// @param holder The entity holding and presenting the Verifiable Presentation. The holder must be a valid DID. + /// @param vc_jwts A list of Verifiable Credential JWTs to include in the presentation. All `vc_jwt` values are verified and the call will will if any fail verification. /// @param options Optional parameters for creating the presentation, such as context or expiration. CONSTRUCTOR create(holder: string, vc_jwts: []string, options: VerifiablePresentationCreateOptions?) /// Constructs a Verifiable Presentation from a VP JWT (JSON Web Token). /// - /// @param vp_jwt The Verifiable Presentation in JWT format. - /// @param verify If true, verifies the integrity of the JWT before creating the presentation. + /// @param vp_jwt The Verifiable Presentation 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 and validating the Data Model. CONSTRUCTOR from_vp_jwt(vp_jwt: string, verify: bool) /// Signs the Verifiable Presentation using the specified Bearer DID and optional verification method. /// /// @param bearer_did The DID used to sign the presentation. - /// @param verification_method_id Optional identifier for the verification method. - /// @returns A string representing the signed JWT of the Verifiable Presentation. + /// @param verification_method_id Optional identifier of the Verification Method for which to sign with. + /// @returns A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Presentation. METHOD sign(bearer_did: BearerDid, verification_method_id: String?): string ``` @@ -297,12 +304,17 @@ CLASS VerifiablePresentation CLASS VerifiablePresentationCreateOptions /// The unique identifier for the Verifiable Presentation. This is optional. + /// If not provided then the default value will be of format urn:uuid:{uuid}. PUBLIC DATA id: string? /// The context(s) for the Verifiable Presentation, which define the meaning of terms within the presentation. + /// The base context https://www.w3.org/2018/credentials/v1 is always the first value whereafter values provided here will be appended onto. + /// If the base context is also provided here then it will be de-duplicated against the base context referred to above. PUBLIC DATA context: []string? - /// The type(s) of the Verifiable Presentation. Typically includes "VerifiablePresentation". + /// The type(s) of the Verifiable Presentation. + /// The base type VerifiablePresentation will always be the first value whereafter values provided here will be appeneded onto. + /// If the base type is also provided here then it will be de-duplicated against the base type referred to above. PUBLIC DATA type: []string? /// The issuance date of the presentation. If not provided, defaults to the current date and time. From 4cfc4f417746fee091c4b6b31254b63ec16be6de Mon Sep 17 00:00:00 2001 From: Kendall Weihe Date: Fri, 13 Sep 2024 10:19:16 -0400 Subject: [PATCH 04/16] Add doc comments to relevant kt code --- .../web5/sdk/vc/StatusListCredential.kt | 75 ++++++++++ .../web5/sdk/vc/VerifiableCredential.kt | 132 ++++++++++++++++++ .../web5/sdk/vc/VerifiablePresentation.kt | 78 +++++++++++ .../src/credentials/status_list_credential.rs | 84 ++++++++++- .../credentials/verifiable_credential_1_1.rs | 2 +- docs/API_DESIGN.md | 2 +- 6 files changed, 367 insertions(+), 6 deletions(-) diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt index d1ace6a3..37c40c4d 100644 --- 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(null) + * 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,41 @@ 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 issuerBearerDid = DidJwk.create(null) + * 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) + * ) + * + * 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 index 3a4b112b..faa55dbe 100644 --- 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? = null, @@ -39,6 +63,22 @@ data class VerifiableCredentialCreateOptions( val evidence: List>? = 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, val type: List, @@ -75,6 +115,34 @@ 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), + * VerifiableCredentialCreateOptions( + * credentialStatus = CredentialStatus( + * id = "https://example.com/status/1", + * type = "StatusList2021Entry", + * statusPurpose = "revocation", + * statusListIndex = "3", + * statusListCredential = "https://example.com/status/1" + * ) + * ) + * ) + * ``` + */ fun create( issuer: Issuer, credentialSubject: CredentialSubject, @@ -120,6 +188,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 +230,35 @@ 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), + * VerifiableCredentialCreateOptions( + * credentialStatus = CredentialStatus( + * id = "https://example.com/status/1", + * type = "StatusList2021Entry", + * statusPurpose = "revocation", + * statusListIndex = "3", + * statusListCredential = "https://example.com/status/1" + * ) + * ) + * ) + * + * val vcJwt = verifiableCredential.sign(issuerBearerDid) + * ``` + */ fun sign(bearerDid: BearerDid, verificationMethodId: String? = null): String { try { return rustCoreVerifiableCredential.sign(bearerDid.rustCoreBearerDid, verificationMethodId) @@ -157,13 +268,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 +315,12 @@ class IssuerDeserializer : JsonDeserializer() { } } +/** + * 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 +342,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 diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiablePresentation.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiablePresentation.kt index bf4ed514..5c73f17a 100644 --- a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiablePresentation.kt +++ b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiablePresentation.kt @@ -9,6 +9,17 @@ import web5.sdk.rust.VerifiablePresentation as RustCoreVerifiablePresentation import web5.sdk.rust.VerifiablePresentationCreateOptionsData as RustCoreVerifiablePresentationCreateOptions import web5.sdk.rust.Web5Exception.Exception as RustCoreException +/** + * Represents the options available when creating a Verifiable Presentation. + * These options allow customization of various attributes of the presentation during its creation. + * + * @property id The unique identifier for the Verifiable Presentation. This is optional. Defaults to `urn:uuid:{uuid}` if not provided. + * @property context The context(s) defining the meaning of terms within the presentation. The base context `https://www.w3.org/2018/credentials/v1` is always included. + * @property type The type(s) of the Verifiable Presentation, where "VerifiablePresentation" is always included as the base type. + * @property issuanceDate The issuance date of the presentation. Defaults to the current date and time if not provided. + * @property expirationDate The optional expiration date for the presentation. + * @property additionalProperties Additional data included in the presentation, represented as a key-value map. + */ data class VerifiablePresentationCreateOptions( val id: String? = null, val context: List? = null, @@ -18,6 +29,20 @@ data class VerifiablePresentationCreateOptions( val additionalProperties: Map? = null ) +/** + * Represents a Verifiable Presentation according to the [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/#presentations-0) + * and conformant to the [Web5 specification](https://tbd54566975.github.io/web5-spec/#verifiable-presentation-v11-data-model). + * A Verifiable Presentation allows a holder to present one or more credentials. + * + * @property context A list of contexts used to define the semantic meaning of the data contained in the presentation. + * @property type The type(s) of the Verifiable Presentation. + * @property id The unique identifier for the Verifiable Presentation. + * @property holder The entity holding and presenting the Verifiable Presentation, identified by a DID or other identifier. + * @property issuanceDate The date and time when the presentation was issued. + * @property expirationDate The optional expiration date and time after which the presentation is no longer valid. + * @property verifiableCredential A list of Verifiable Credentials contained within the presentation. + * @property additionalProperties Additional data that may be included in the presentation, represented as a key-value map. + */ data class VerifiablePresentation private constructor( val context: List, val type: List, @@ -30,6 +55,26 @@ data class VerifiablePresentation private constructor( internal val rustCoreVerifiablePresentation: RustCoreVerifiablePresentation, ) { companion object { + /** + * Creates a new Verifiable Presentation with the specified holder, Verifiable Credential JWTs, + * and optional creation options. + * + * @param holder The entity holding and presenting the Verifiable Presentation. The holder must be a valid DID. + * @param verifiableCredential A list of Verifiable Credential JWTs to include in the presentation. + * @param options Optional parameters for creating the presentation, such as context or expiration. + * @return The newly created Verifiable Presentation. + * @throws Web5Exception if the creation fails due to invalid parameters or verification issues. + * + * Example usage: + * ``` + * val holderBearerDid = DidJwk.create() + * val vcJwts = listOf("eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw") + * val presentation = VerifiablePresentation.create( + * holderBearerDid.did.uri, + * vcJwts + * ) + * ``` + */ fun create( holder: String, verifiableCredential: List, @@ -69,6 +114,20 @@ data class VerifiablePresentation private constructor( } } + /** + * Constructs a Verifiable Presentation from a VP JWT (JSON Web Token). + * + * @param vpJwt The Verifiable Presentation 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 and validating the Data Model. + * @return The deserialized and validated Verifiable Presentation. + * @throws Web5Exception if the JWT is invalid or verification fails. + * + * Example usage: + * ``` + * val vpJwt = "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKYWNUaFJaR05XYlRrMlluZGpRa3R3WVhwV2RGQmlkekJ6U1c4NE0wbG9XRXAyVGtoV1VIUnpWWFYzSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUphY1RoUlpHTldiVGsyWW5kalFrdHdZWHBXZEZCaWR6QnpTVzg0TTBsb1dFcDJUa2hXVUhSelZYVjNJbjAiLCJqdGkiOiJ1cm46dXVpZDowZDg5YTcxMS0zNTdjLTQzNTQtOWYzMS02OWQ0NDE1NWQ1ZTMiLCJuYmYiOjE3MjYyMzQwODEsImlhdCI6MTcyNjIzNDA4MSwidnAiOnsiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMzoyODowMVoiLCJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50YXRpb24iXSwidmVyaWZpYWJsZUNyZWRlbnRpYWwiOlsiZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKRlpESTFOVEU1SWl3aWEybGtJam9pWkdsa09tcDNhenBsZVVwb1lrZGphVTlwU2taYVJFa3hUbFJGTlVscGQybGhNMUkxU1dwdmFWUXdkRkZKYVhkcFdUTktNa2xxYjJsU1YxRjVUbFJWZUU5VFNYTkpibWRwVDJsS1VWRnNiRTVTYlRreFdUQnpOVk16WkZCVFNGSjZUbXBvVTA1RlZuZGpiVmw1VFhwT1RFNVVVazFOVmxaSlRqRlNTV05VVW1aaE1HaE9TVzR3SXpBaWZRLmV5SnBjM01pT2lKa2FXUTZhbmRyT21WNVNtaGlSMk5wVDJsS1JscEVTVEZPVkVVMVNXbDNhV0V6VWpWSmFtOXBWREIwVVVscGQybFpNMG95U1dwdmFWSlhVWGxPVkZWNFQxTkpjMGx1WjJsUGFVcFJVV3hzVGxKdE9URlpNSE0xVXpOa1VGTklVbnBPYW1oVFRrVldkMk50V1hsTmVrNU1UbFJTVFUxV1ZrbE9NVkpKWTFSU1ptRXdhRTVKYmpBaUxDSnFkR2tpT2lKMWNtNDZkWFZwWkRwaE1UaGlOREppWVMwMk1UVTVMVFExWVRrdFlXTXpZaTB5TnpaaVlqQmtORGRpWmpZaUxDSnpkV0lpT2lKa2FXUTZaR2gwT201bk5HaHRjWFJ5WjNWcWIzZzBZV2R3WmpodmEzaHBhRzU1ZVRGNmNXNXhPVGR4Wm1WeE1UVjRPRzloY2pkNVpYQjZhSGtpTENKdVltWWlPakUzTWpZeU16RTVOeklzSW1saGRDSTZNVGN5TmpJek1UazNNaXdpZG1NaU9uc2lRR052Ym5SbGVIUWlPbHNpYUhSMGNITTZMeTkzZDNjdWR6TXViM0puTHpJd01UZ3ZZM0psWkdWdWRHbGhiSE12ZGpFaVhTd2lZM0psWkdWdWRHbGhiRk4xWW1wbFkzUWlPbnNpYVdRaU9pSmthV1E2WkdoME9tNW5OR2h0Y1hSeVozVnFiM2cwWVdkd1pqaHZhM2hwYUc1NWVURjZjVzV4T1RkeFptVnhNVFY0T0c5aGNqZDVaWEI2YUhraWZTd2lhWE56ZFdWeUlqb2laR2xrT21wM2F6cGxlVXBvWWtkamFVOXBTa1phUkVreFRsUkZOVWxwZDJsaE0xSTFTV3B2YVZRd2RGRkphWGRwV1ROS01rbHFiMmxTVjFGNVRsUlZlRTlUU1hOSmJtZHBUMmxLVVZGc2JFNVNiVGt4V1RCek5WTXpaRkJUU0ZKNlRtcG9VMDVGVm5kamJWbDVUWHBPVEU1VVVrMU5WbFpKVGpGU1NXTlVVbVpoTUdoT1NXNHdJaXdpYVhOemRXRnVZMlZFWVhSbElqb2lNakF5TkMwd09TMHhNMVF4TWpvMU1qbzFNbG9pTENKMGVYQmxJanBiSWxabGNtbG1hV0ZpYkdWRGNtVmtaVzUwYVdGc0lsMHNJbWxrSWpvaWRYSnVPblYxYVdRNllURTRZalF5WW1FdE5qRTFPUzAwTldFNUxXRmpNMkl0TWpjMlltSXdaRFEzWW1ZMkluMTkuaUNkN1FsQWlCTkxDZnZ0VWJCdGstOVBUcUZmdWNxWjQ0S3hoRnZqR2NSU2prR0pyNjEwLTBqTFZzTlNBX0NQOGdibFljZncxZTVqeDNwR2VFckMtQnciXSwiaG9sZGVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKYWNUaFJaR05XYlRrMlluZGpRa3R3WVhwV2RGQmlkekJ6U1c4NE0wbG9XRXAyVGtoV1VIUnpWWFYzSW4wIiwiaWQiOiJ1cm46dXVpZDowZDg5YTcxMS0zNTdjLTQzNTQtOWYzMS02OWQ0NDE1NWQ1ZTMifX0.f-kdfbIIms3Gg2dMKUMayeU1rQnaO_o0io33kLzy-uPqI6vsdsJZvSmDIilx7scRqlia7Pmnnj6bnF2x8F2fAw" + * val presentation = VerifiablePresentation.fromVpJwt(vpJwt, true) + * ``` + */ fun fromVpJwt(vpJwt: String, verify: Boolean): VerifiablePresentation { try { val rustCoreVerifiablePresentation = RustCoreVerifiablePresentation.fromVpJwt(vpJwt, verify) @@ -93,6 +152,25 @@ data class VerifiablePresentation private constructor( } } + /** + * Signs the Verifiable Presentation using the specified Bearer DID and optional verification method. + * + * @param bearerDid The DID used to sign the presentation. + * @param verificationMethodId Optional identifier of the Verification Method to sign with. + * @return A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Presentation. + * @throws Web5Exception if the signing process fails. + * + * Example usage: + * ``` + * val holderBearerDid = DidJwk.create() + * val vcJwts = listOf("eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw") + * val presentation = VerifiablePresentation.create( + * holderBearerDid.did.uri, + * vcJwts + * ) + * val vpJwt = presentation.sign(holderBearerDid) + * ``` + */ fun sign(bearerDid: BearerDid, verificationMethodId: String? = null): String { try { return rustCoreVerifiablePresentation.sign(bearerDid.rustCoreBearerDid, verificationMethodId) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index a22eeb35..54291ba3 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -1,11 +1,10 @@ -use std::io::{Read, Write}; - use super::verifiable_credential_1_1::{VerifiableCredential, VerifiableCredentialCreateOptions}; use crate::credentials::{CredentialSubject, Issuer}; use crate::errors::{Result, Web5Error}; use crate::json::{JsonObject, JsonValue}; use base64::Engine; use flate2::{read::GzDecoder, write::GzEncoder, Compression}; +use std::io::{Read, Write}; pub const STATUS_LIST_CREDENTIAL_CONTEXT: &str = "https://w3id.org/vc/status-list/2021/v1"; pub const STATUS_LIST_CREDENTIAL_TYPE: &str = "StatusList2021Credential"; @@ -29,6 +28,45 @@ impl StatusListCredential { /// * `issuer` - The entity issuing the Status List Credential. /// * `status_purpose` - The purpose of the status (e.g., "revocation"). /// * `disabled_credentials` - A list of Verifiable Credentials that are disabled (revoked or suspended). + /// + /// # Example + /// ```rust + /// use web5::credentials::CredentialStatus; + /// use web5::credentials::CredentialSubject; + /// use web5::credentials::Issuer; + /// use web5::credentials::STATUS_LIST_2021_ENTRY; + /// use web5::credentials::StatusListCredential; + /// use web5::credentials::VerifiableCredential; + /// use web5::credentials::VerifiableCredentialCreateOptions; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let issuer_bearer_did = DidJwk::create(None).unwrap(); + /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; + /// + /// let verifiable_credential = VerifiableCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// CredentialSubject { + /// id: subject_did_uri.to_string(), + /// additional_properties: None, + /// }, + /// Some(VerifiableCredentialCreateOptions { + /// credential_status: Some(CredentialStatus { + /// id: "https://example.com/status/1".to_string(), + /// r#type: STATUS_LIST_2021_ENTRY.to_string(), + /// status_purpose: "revocation".to_string(), + /// status_list_index: "3".to_string(), + /// status_list_credential: "https://example.com/status/1".to_string(), + /// }), + /// ..Default::default() + /// }), + /// ).unwrap(); + /// + /// let status_list_credential = StatusListCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// "revocation".to_string(), + /// Some(vec![verifiable_credential.clone()]), + /// ).unwrap(); + /// ``` pub fn create( issuer: Issuer, status_purpose: String, @@ -95,9 +133,47 @@ impl StatusListCredential { /// * `Err` if the credential status is invalid or incompatible. /// /// # Example + /// ```rust + /// use web5::credentials::CredentialStatus; + /// use web5::credentials::CredentialSubject; + /// use web5::credentials::Issuer; + /// use web5::credentials::STATUS_LIST_2021_ENTRY; + /// use web5::credentials::StatusListCredential; + /// use web5::credentials::VerifiableCredential; + /// use web5::credentials::VerifiableCredentialCreateOptions; + /// use web5::dids::methods::did_jwk::DidJwk; + /// + /// let issuer_bearer_did = DidJwk::create(None).unwrap(); + /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; + /// + /// let verifiable_credential = VerifiableCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// CredentialSubject { + /// id: subject_did_uri.to_string(), + /// additional_properties: None, + /// }, + /// Some(VerifiableCredentialCreateOptions { + /// credential_status: Some(CredentialStatus { + /// id: "https://example.com/status/1".to_string(), + /// r#type: STATUS_LIST_2021_ENTRY.to_string(), + /// status_purpose: "revocation".to_string(), + /// status_list_index: "3".to_string(), + /// status_list_credential: "https://example.com/status/1".to_string(), + /// }), + /// ..Default::default() + /// }), + /// ).unwrap(); + /// + /// let status_list_credential = StatusListCredential::create( + /// Issuer::String(issuer_bearer_did.did.uri.clone()), + /// "revocation".to_string(), + /// Some(vec![verifiable_credential.clone()]), + /// ).unwrap(); /// - /// let is_disabled = status_list_credential.is_disabled(&credential_to_check)?; - /// println!("Credential is disabled: {}", is_disabled); + /// let is_disabled = status_list_credential + /// .is_disabled(&verifiable_credential) + /// .unwrap(); + /// ``` pub fn is_disabled(&self, credential: &VerifiableCredential) -> Result { let status = credential.credential_status.as_ref().ok_or_else(|| { Web5Error::Parameter("no credential status found in credential".to_string()) diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index 282dc9bf..a8a03646 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -118,7 +118,7 @@ pub struct CredentialStatus { /// The unique identifier for the credential status. pub id: String, - /// The type(s) of the credential status, typically includes "CredentialStatus". + /// The type(s) of the credential status. #[serde(rename = "type")] pub r#type: String, diff --git a/docs/API_DESIGN.md b/docs/API_DESIGN.md index fba2d745..0f1200e6 100644 --- a/docs/API_DESIGN.md +++ b/docs/API_DESIGN.md @@ -164,7 +164,7 @@ CLASS CredentialStatus /// The unique identifier for the credential status. PUBLIC DATA id: string - /// The type(s) of the credential status, typically includes "CredentialStatus". + /// The type(s) of the credential status. PUBLIC DATA type: []string /// The purpose of the status (e.g., "revocation" or "suspension"). From 9b7b867e23a79dbe3aa61eba451898454470a96d Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:48:29 -0700 Subject: [PATCH 05/16] Update bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt --- bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt index 37c40c4d..c9e6f723 100644 --- a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt +++ b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt @@ -28,7 +28,7 @@ data class StatusListCredential( * * Example usage: * ``` - * val issuerBearerDid = DidJwk.create(null) + * val issuerBearerDid = DidJwk.create() * val subjectDidUri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy" * val verifiableCredential = VerifiableCredential.create( * Issuer.StringIssuer(issuerBearerDid.did.uri), From 5a1f9f58383179fb1759536ab145de9ae11c8870 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:48:47 -0700 Subject: [PATCH 06/16] Update bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt --- .../web5/sdk/vc/StatusListCredential.kt | 23 +------------------ 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt index c9e6f723..7f353c43 100644 --- a/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt +++ b/bound/kt/src/main/kotlin/web5/sdk/vc/StatusListCredential.kt @@ -79,28 +79,7 @@ data class StatusListCredential( * * Example usage: * ``` - * val issuerBearerDid = DidJwk.create(null) - * 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) - * ) + * * val isDisabled = statusListCredential.isDisabled(verifiableCredential) * ``` From 99b6c379d784790027534d79cd9cdbb446d03f27 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:48:56 -0700 Subject: [PATCH 07/16] Update bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt --- .../kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt | 7 ------- 1 file changed, 7 deletions(-) diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt index faa55dbe..3847d64b 100644 --- a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt +++ b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt @@ -131,13 +131,6 @@ data class VerifiableCredential private constructor( * 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" * ) * ) * ) From b67c883f48bce36eb74da87b2162d69b41287e8a Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:05 -0700 Subject: [PATCH 08/16] Update bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt --- .../kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt | 7 ------- 1 file changed, 7 deletions(-) diff --git a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt index 3847d64b..19a14919 100644 --- a/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt +++ b/bound/kt/src/main/kotlin/web5/sdk/vc/VerifiableCredential.kt @@ -238,13 +238,6 @@ data class VerifiableCredential private constructor( * 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" * ) * ) * ) From 41c380d988dae6df5f7d5d80821a8e3ec5c52685 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:11 -0700 Subject: [PATCH 09/16] Update crates/web5/src/credentials/status_list_credential.rs --- crates/web5/src/credentials/status_list_credential.rs | 9 --------- 1 file changed, 9 deletions(-) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index 54291ba3..df27e4af 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -31,15 +31,6 @@ impl StatusListCredential { /// /// # Example /// ```rust - /// use web5::credentials::CredentialStatus; - /// use web5::credentials::CredentialSubject; - /// use web5::credentials::Issuer; - /// use web5::credentials::STATUS_LIST_2021_ENTRY; - /// use web5::credentials::StatusListCredential; - /// use web5::credentials::VerifiableCredential; - /// use web5::credentials::VerifiableCredentialCreateOptions; - /// use web5::dids::methods::did_jwk::DidJwk; - /// /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// From f8fc439e89dc4fe3888f36ffa010accc7db06515 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:17 -0700 Subject: [PATCH 10/16] Update crates/web5/src/credentials/status_list_credential.rs --- crates/web5/src/credentials/status_list_credential.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index df27e4af..565bfb34 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -21,7 +21,7 @@ pub struct StatusListCredential { impl StatusListCredential { /// Creates a new Status List Credential with the specified issuer, status purpose, - /// and the list of disabled credentials. + /// and the encoded bitstring list of disabled credentials. /// /// # Arguments /// From 99aba5325cf104abdcfea976a26218267c98f7d2 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:23 -0700 Subject: [PATCH 11/16] Update crates/web5/src/credentials/status_list_credential.rs --- crates/web5/src/credentials/status_list_credential.rs | 9 --------- 1 file changed, 9 deletions(-) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index 565bfb34..0931bb4e 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -125,15 +125,6 @@ impl StatusListCredential { /// /// # Example /// ```rust - /// use web5::credentials::CredentialStatus; - /// use web5::credentials::CredentialSubject; - /// use web5::credentials::Issuer; - /// use web5::credentials::STATUS_LIST_2021_ENTRY; - /// use web5::credentials::StatusListCredential; - /// use web5::credentials::VerifiableCredential; - /// use web5::credentials::VerifiableCredentialCreateOptions; - /// use web5::dids::methods::did_jwk::DidJwk; - /// /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// From f3e1c75e5b0dc4201afabe53f7d290bbd6b00587 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:30 -0700 Subject: [PATCH 12/16] Update crates/web5/src/credentials/verifiable_credential_1_1.rs --- crates/web5/src/credentials/verifiable_credential_1_1.rs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index a8a03646..8ee0b918 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -146,11 +146,6 @@ impl VerifiableCredential { /// /// # Example /// ``` - /// use web5::credentials::VerifiableCredential; - /// use web5::credentials::CredentialSubject; - /// use web5::credentials::Issuer; - /// use web5::dids::methods::did_jwk::DidJwk; - /// /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// From 33cd3923c518e7e8652d883bdbd726c5a8cb8a30 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:36 -0700 Subject: [PATCH 13/16] Update crates/web5/src/credentials/verifiable_credential_1_1.rs --- crates/web5/src/credentials/verifiable_credential_1_1.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index 8ee0b918..815d52bf 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -175,8 +175,6 @@ impl VerifiableCredential { /// /// # Example /// ``` - /// use web5::credentials::VerifiableCredential; - /// /// let vc_jwt = r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"#; /// let verifiable_credential = /// VerifiableCredential::from_vc_jwt(vc_jwt, true).unwrap(); From cf614dd8d2e1d860e138ab070b22d23b18ef7eda Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:41 -0700 Subject: [PATCH 14/16] Update crates/web5/src/credentials/verifiable_credential_1_1.rs --- crates/web5/src/credentials/verifiable_credential_1_1.rs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index 815d52bf..4492619c 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -203,11 +203,6 @@ impl VerifiableCredential { /// /// # Example /// ``` - /// use web5::credentials::VerifiableCredential; - /// use web5::credentials::CredentialSubject; - /// use web5::credentials::Issuer; - /// use web5::dids::methods::did_jwk::DidJwk; - /// /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// From 584aa6138da117d157c31cb65b7159038fd5d3c0 Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:49:47 -0700 Subject: [PATCH 15/16] Update crates/web5/src/credentials/verifiable_presentation_1_1.rs --- crates/web5/src/credentials/verifiable_presentation_1_1.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/crates/web5/src/credentials/verifiable_presentation_1_1.rs b/crates/web5/src/credentials/verifiable_presentation_1_1.rs index b3ed3334..92007505 100644 --- a/crates/web5/src/credentials/verifiable_presentation_1_1.rs +++ b/crates/web5/src/credentials/verifiable_presentation_1_1.rs @@ -248,9 +248,6 @@ impl VerifiablePresentation { /// /// # Example /// ```rust - /// use web5::credentials::VerifiablePresentation; - /// use web5::dids::methods::did_jwk::DidJwk; - /// /// let holder_bearer_did = DidJwk::create(None).unwrap(); /// let vc_jwts = vec![String::from( /// r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"# From 3ad0e3b31bb050856b5a7d5f2257c1c5a6447a3b Mon Sep 17 00:00:00 2001 From: Neal Date: Mon, 16 Sep 2024 12:01:34 -0700 Subject: [PATCH 16/16] add ignore --- crates/web5/src/credentials/status_list_credential.rs | 4 ++-- crates/web5/src/credentials/verifiable_credential_1_1.rs | 6 +++--- crates/web5/src/credentials/verifiable_presentation_1_1.rs | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/crates/web5/src/credentials/status_list_credential.rs b/crates/web5/src/credentials/status_list_credential.rs index 0931bb4e..5795aa06 100644 --- a/crates/web5/src/credentials/status_list_credential.rs +++ b/crates/web5/src/credentials/status_list_credential.rs @@ -30,7 +30,7 @@ impl StatusListCredential { /// * `disabled_credentials` - A list of Verifiable Credentials that are disabled (revoked or suspended). /// /// # Example - /// ```rust + /// ```ignore /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// @@ -124,7 +124,7 @@ impl StatusListCredential { /// * `Err` if the credential status is invalid or incompatible. /// /// # Example - /// ```rust + /// ```ignore /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// diff --git a/crates/web5/src/credentials/verifiable_credential_1_1.rs b/crates/web5/src/credentials/verifiable_credential_1_1.rs index 4492619c..e4ad81bb 100644 --- a/crates/web5/src/credentials/verifiable_credential_1_1.rs +++ b/crates/web5/src/credentials/verifiable_credential_1_1.rs @@ -145,7 +145,7 @@ impl VerifiableCredential { /// * `options` - Optional parameters for creating the credential, such as schema or status. /// /// # Example - /// ``` + /// ```ignore /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// @@ -174,7 +174,7 @@ impl VerifiableCredential { /// * `verify` - If true, verifies the integrity of the JWT by performing cryptographic verification against the signature, validating the VC Data Model, and validates the JSON Schema if present. /// /// # Example - /// ``` + /// ```ignore /// let vc_jwt = r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"#; /// let verifiable_credential = /// VerifiableCredential::from_vc_jwt(vc_jwt, true).unwrap(); @@ -202,7 +202,7 @@ impl VerifiableCredential { /// A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Credential. /// /// # Example - /// ``` + /// ```ignore /// let issuer_bearer_did = DidJwk::create(None).unwrap(); /// let subject_did_uri = "did:dht:ng4hmqtrgujox4agpf8okxihnyy1zqnq97qfeq15x8oar7yepzhy"; /// diff --git a/crates/web5/src/credentials/verifiable_presentation_1_1.rs b/crates/web5/src/credentials/verifiable_presentation_1_1.rs index 92007505..88120b8c 100644 --- a/crates/web5/src/credentials/verifiable_presentation_1_1.rs +++ b/crates/web5/src/credentials/verifiable_presentation_1_1.rs @@ -247,7 +247,7 @@ impl VerifiablePresentation { /// A string representing the signed JWT, serialized as a compact JWS, of the Verifiable Presentation. /// /// # Example - /// ```rust + /// ```ignore /// let holder_bearer_did = DidJwk::create(None).unwrap(); /// let vc_jwts = vec![String::from( /// r#"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIzAifQ.eyJpc3MiOiJkaWQ6andrOmV5SmhiR2NpT2lKRlpESTFOVEU1SWl3aWEzUjVJam9pVDB0UUlpd2lZM0oySWpvaVJXUXlOVFV4T1NJc0luZ2lPaUpRUWxsTlJtOTFZMHM1UzNkUFNIUnpOamhTTkVWd2NtWXlNek5MTlRSTU1WVklOMVJJY1RSZmEwaE5JbjAiLCJqdGkiOiJ1cm46dXVpZDphMThiNDJiYS02MTU5LTQ1YTktYWMzYi0yNzZiYjBkNDdiZjYiLCJzdWIiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkiLCJuYmYiOjE3MjYyMzE5NzIsImlhdCI6MTcyNjIzMTk3MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZGh0Om5nNGhtcXRyZ3Vqb3g0YWdwZjhva3hpaG55eTF6cW5xOTdxZmVxMTV4OG9hcjd5ZXB6aHkifSwiaXNzdWVyIjoiZGlkOmp3azpleUpoYkdjaU9pSkZaREkxTlRFNUlpd2lhM1I1SWpvaVQwdFFJaXdpWTNKMklqb2lSV1F5TlRVeE9TSXNJbmdpT2lKUVFsbE5SbTkxWTBzNVMzZFBTSFJ6TmpoU05FVndjbVl5TXpOTE5UUk1NVlZJTjFSSWNUUmZhMGhOSW4wIiwiaXNzdWFuY2VEYXRlIjoiMjAyNC0wOS0xM1QxMjo1Mjo1MloiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlkIjoidXJuOnV1aWQ6YTE4YjQyYmEtNjE1OS00NWE5LWFjM2ItMjc2YmIwZDQ3YmY2In19.iCd7QlAiBNLCfvtUbBtk-9PTqFfucqZ44KxhFvjGcRSjkGJr610-0jLVsNSA_CP8gblYcfw1e5jx3pGeErC-Bw"#