From 6fbd22fa6ba7bb1d4092afbded0f95c0d841bd97 Mon Sep 17 00:00:00 2001 From: Italo Borssatto Date: Mon, 8 Aug 2022 11:49:18 -0300 Subject: [PATCH] feat: define an interface for credential status manager (#956) partially fixes #937 relates to #981 --- packages/core/package.json | 1 + packages/core/src/types/ICredentialStatus.ts | 78 +++++++++++++++++++ packages/core/src/types/vc-data-model.ts | 2 +- packages/credential-status/plugin.schema.json | 17 +++- packages/credential-status/src/types.ts | 4 +- 5 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 packages/core/src/types/ICredentialStatus.ts diff --git a/packages/core/package.json b/packages/core/package.json index 2834ac102..fe2a33db5 100644 --- a/packages/core/package.json +++ b/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": [ diff --git a/packages/core/src/types/ICredentialStatus.ts b/packages/core/src/types/ICredentialStatus.ts new file mode 100644 index 000000000..6a6c2f859 --- /dev/null +++ b/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 + + /** + * 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 + + /** + * List all the credential status types (methods) available in the current agent instance. + */ + credentialStatusTypes(): Promise +} \ No newline at end of file diff --git a/packages/core/src/types/vc-data-model.ts b/packages/core/src/types/vc-data-model.ts index 1c7181399..69de0c0c3 100644 --- a/packages/core/src/types/vc-data-model.ts +++ b/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 diff --git a/packages/credential-status/plugin.schema.json b/packages/credential-status/plugin.schema.json index 097e62288..abeda70b9 100644 --- a/packages/credential-status/plugin.schema.json +++ b/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" } } } diff --git a/packages/credential-status/src/types.ts b/packages/credential-status/src/types.ts index 57a4a6d50..82bd4bb8f 100644 --- a/packages/credential-status/src/types.ts +++ b/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, - ): Promise + ): Promise }