feat: define an interface for credential status manager (#956)

partially fixes #937
relates to #981

packages/core/package.json

@@ -27,6 +27,7 @@
   "devDependencies": {
     "@types/debug": "4.1.7",
     "did-resolver": "3.2.2",
+    "credential-status": "^2.0.3",
     "typescript": "4.7.3"
   },
   "files": [

packages/core/src/types/ICredentialStatus.ts

@@ -0,0 +1,78 @@
+export { DIDDocument, DIDResolutionOptions, DIDResolutionResult } from 'did-resolver'
+import { IPluginMethodMap } from './IAgent'
+import { CredentialStatus, VerifiableCredential } from './vc-data-model'
+
+/**
+ * The arguments expected by a plugin that implements a credential status type/method 
+ * in order to change the status of an issued verifiable credential.
+ * 
+ * Each credential status type has its own specific parameters according to their spec.
+ * 
+ * @see https://w3c-ccg.github.io/vc-status-list-2021/ | StatusList2021Entry
+ * @see https://w3c-ccg.github.io/vc-csl2017/ | CredentialStatusList2017
+ *
+ * @beta
+ */
+interface CredentialStatusUpdateOptions { [x: string]: any }
+
+/**
+ * Input arguments for {@link ICredentialStatus.credentialStatusUpdate  | credentialStatusUpdate}
+ * @beta
+ */
+export interface CredentialStatusUpdateArgs {
+  /**
+   * The verifiable credential whose status will be updated.
+   */
+  vc: VerifiableCredential
+
+  /**
+   * Credential status strategy options that will be passed to the method specific manager.
+   * 
+   * @see: https://www.w3.org/TR/vc-data-model/#status
+   */
+  options?: CredentialStatusUpdateOptions
+}
+
+/**
+ * Arguments for generating a `credentialStatus` property for a {@link VerifiableCredential}.
+ * @see {@link ICredentialStatus.credentialStatusGenerate}
+ *
+ * @beta
+ */
+export interface CredentialStatusGenerateArgs {
+  /**
+   * The credential status type (aka credential status method) to be used in the `credentialStatus` generation.
+   */
+  type: string
+}
+
+/**
+ * Credential status manager interface
+ * @beta
+ */
+export interface ICredentialStatus extends IPluginMethodMap {
+  /**
+   * Changes the status of an existing verifiable credential. 
+   * Commonly used to revoke an existent credential.
+   * 
+   * @param args - Input arguments for updating the status or revoking a credential
+   * @beta
+   */
+  credentialStatusUpdate(args: CredentialStatusUpdateArgs): Promise<any>
+
+  /**
+   * Generates a `credentialStatus` property for a future credential, not yet signed.
+   * 
+   * This method is used during the creation of a VC in order to make the VC capable of 
+   * having its status updated later, allowing it to be revoked later by instance.
+   * 
+   * @param args - Input arguments for generating the `credentialStatus` field of a new credential
+   * @beta
+   */
+  credentialStatusGenerate(args: CredentialStatusGenerateArgs): Promise<CredentialStatus>
+
+  /**
+   * List all the credential status types (methods) available in the current agent instance.
+   */
+  credentialStatusTypes(): Promise<string[]>
+}

packages/core/src/types/vc-data-model.ts

@@ -18,7 +18,7 @@ export type CompactJWT = string
  *
  * @beta This API may change without a BREAKING CHANGE notice.
  */
-export type IssuerType = { id: string; [x: string]: any } | string
+export type IssuerType = { id: string;[x: string]: any } | string
 
 /**
  * The value of the credentialSubject property is defined as a set of objects that contain one or more properties that

packages/credential-status/plugin.schema.json

@@ -122,7 +122,7 @@
               "type": "string"
             },
             "type": {
-              "type": "string"
+              "$ref": "#/components/schemas/CredentialStatusType"
             }
           },
           "required": [
@@ -131,6 +131,10 @@
           ],
           "description": "Used for the discovery of information about the current status of a verifiable credential, such as whether it is suspended or revoked. The precise contents of the credential status information is determined by the specific `credentialStatus` type definition, and varies depending on factors such as whether it is simple to implement or if it is privacy-enhancing.\n\nSee  {@link  https://www.w3.org/TR/vc-data-model/#status | Credential Status }"
         },
+        "CredentialStatusType": {
+          "type": "string",
+          "description": "Expresses the credential status type (also referred to as the credential status method). It is expected that the value will provide enough information to determine the current status of the credential and that machine readable information needs to be retrievable from the URI. For example, the object could contain a link to an external document noting whether or not the credential is suspended or revoked."
+        },
         "DIDDocument": {
           "type": "object",
           "properties": {
@@ -368,6 +372,15 @@
             "type",
             "serviceEndpoint"
           ]
+        },
+        "CredentialStatusVerification": {
+          "type": "object",
+          "properties": {
+            "revoked": {
+              "type": "boolean"
+            }
+          },
+          "description": "Represents the result of a status check.\n\nImplementations should populate the `revoked` boolean property, but they can return additional metadata that is method specific."
         }
       },
       "methods": {
@@ -377,7 +390,7 @@
             "$ref": "#/components/schemas/ICheckCredentialStatusArgs"
           },
           "returnType": {
-            "$ref": "#/components/schemas/CredentialStatus"
+            "$ref": "#/components/schemas/CredentialStatusVerification"
           }
         }
       }

packages/credential-status/src/types.ts

@@ -1,5 +1,5 @@
 import { IAgentContext, IPluginMethodMap, VerifiableCredential } from '@veramo/core'
-import { CredentialStatus } from 'credential-status'
+import { CredentialStatus as CredentialStatusVerification } from 'credential-status'
 import { DIDDocument } from 'did-resolver'
 
 /**
@@ -44,5 +44,5 @@ export interface ICheckCredentialStatus extends IPluginMethodMap {
   checkCredentialStatus(
     args: ICheckCredentialStatusArgs,
     context: IAgentContext<any>,
-  ): Promise<CredentialStatus>
+  ): Promise<CredentialStatusVerification>
 }