From 63e64e0e2693808c4704dca8cc511dc0bab3f3b1 Mon Sep 17 00:00:00 2001 From: Mircea Nistor Date: Thu, 9 Jun 2022 08:09:30 +0200 Subject: [PATCH] fix: update and fix inline documentation of all exported types (#921) * fix(build): use correct cross-package imports * chore(build): split build scripts for better granularity * docs(data-store-json): fix and augment inline documentation for public exports * docs(key-manager): add missing inline docs to exported classes * docs(kms-local): update inline docs for public classes * docs(message-handler): fix JSDoc links and update plugin documentation * docs(remote-server): fix inline docs * docs(url-handler): add description to UrlMessageHandler * docs(core): update and fix inline docs for @veramo/core exports * docs(selective-disclosure): update inline docs for @veramo/selective-disclosure exports * docs(credential-w3c): update inline docs for @veramo/credential-w3c exports * docs(data-store): fix and augment inline documentation for `@veramo/data-store` exports * docs(did-discovery): update and fix inline docs for @veramo/did-discovery exports * docs(did-comm): update and fix inline docs for @veramo/did-comm exports * docs(credential-eip712): update and fix inline docs for @veramo/credential-eip712 exports * fix(credential-status): update and fix type definitions and inline docs * docs(credential-ld): update and fix inline docs * fix(deps): bump api-extractor tools * docs(did-manager): update inline docs * docs(did-provider-key): add some inline docs * docs(did-resolver): update inline docs * docs(remote-client): add inline documentation for exports --- package.json | 6 +- packages/cli/package.json | 4 +- packages/core/plugin.schema.json | 64 +++++---- packages/core/src/agent.ts | 2 +- packages/core/src/index.ts | 7 + packages/core/src/types/IDataStoreORM.ts | 126 +++++++++--------- packages/core/src/types/IIdentifier.ts | 18 ++- packages/core/src/types/IKeyManager.ts | 37 +++-- packages/core/src/types/IResolver.ts | 31 +++-- packages/core/src/types/vc-data-model.ts | 20 +-- packages/core/src/validator.ts | 10 ++ packages/credential-eip712/plugin.schema.json | 6 +- .../src/agent/CredentialEIP712.ts | 3 +- .../src/types/ICredentialEIP712.ts | 20 ++- packages/credential-ld/plugin.schema.json | 14 +- packages/credential-ld/src/index.ts | 15 ++- .../credential-ld/src/ld-default-contexts.ts | 7 +- packages/credential-ld/src/ld-suites.ts | 7 +- .../EcdsaSecp256k1RecoverySignature2020.ts | 5 + .../src/suites/Ed25519Signature2018.ts | 5 + packages/credential-ld/src/types.ts | 41 +++--- packages/credential-status/jest.config.js | 20 --- packages/credential-status/plugin.schema.json | 126 ++++++++++++++---- .../src/credential-status.ts | 18 +++ packages/credential-status/src/types.ts | 46 +++++-- packages/credential-w3c/plugin.schema.json | 8 +- packages/credential-w3c/src/action-handler.ts | 8 +- packages/credential-w3c/src/index.ts | 8 +- .../src/browser-local-storage-store.ts | 4 +- .../data-store-json/src/data-store-json.ts | 12 +- .../src/identifier/did-store.ts | 15 ++- .../src/identifier/key-store.ts | 11 +- .../src/identifier/private-key-store.ts | 16 ++- packages/data-store-json/src/types.ts | 4 +- packages/data-store/package.json | 2 +- packages/data-store/src/data-store-orm.ts | 19 ++- packages/data-store/src/data-store.ts | 13 ++ .../data-store/src/did-discovery-provider.ts | 18 ++- .../src/entities/PreMigrationEntities.ts | 11 +- packages/data-store/src/entities/claim.ts | 27 ++-- .../data-store/src/entities/credential.ts | 28 ++-- .../data-store/src/entities/identifier.ts | 51 ++++--- packages/data-store/src/entities/key.ts | 25 +++- packages/data-store/src/entities/message.ts | 32 ++++- .../data-store/src/entities/presentation.ts | 25 ++-- .../data-store/src/entities/private-key.ts | 20 ++- packages/data-store/src/entities/service.ts | 16 ++- .../data-store/src/identifier/did-store.ts | 21 ++- .../data-store/src/identifier/key-store.ts | 13 ++ .../src/identifier/private-key-store.ts | 12 +- packages/data-store/src/index.ts | 8 ++ .../src/migrations/1.createDatabase.ts | 2 + .../src/migrations/2.simplifyRelations.ts | 4 +- .../migrations/3.createPrivateKeyStorage.ts | 2 + .../migrations/4.allowNullVPIssuanceDate.ts | 4 +- packages/data-store/src/migrations/index.ts | 7 + packages/did-comm/plugin.schema.json | 16 ++- packages/did-comm/src/didcomm.ts | 25 ++-- packages/did-comm/src/index.ts | 2 +- packages/did-comm/src/message-handler.ts | 2 +- .../did-comm/src/transports/transports.ts | 32 +++-- packages/did-comm/src/types/IDIDComm.ts | 15 ++- packages/did-comm/src/types/message-types.ts | 27 ++-- packages/did-discovery/plugin.schema.json | 8 +- packages/did-discovery/src/action-handler.ts | 2 + packages/did-discovery/src/index.ts | 6 + packages/did-discovery/src/types.ts | 20 ++- .../did-manager/src/did-discovery-provider.ts | 9 +- packages/did-manager/src/memory-did-store.ts | 5 + .../did-provider-key/src/key-did-provider.ts | 2 +- packages/did-provider-key/src/resolver.ts | 5 + packages/did-resolver/src/resolver.ts | 24 +++- .../did-resolver/src/universal-resolver.ts | 12 +- .../src/abstract-key-management-system.ts | 8 ++ .../key-manager/src/abstract-key-store.ts | 12 ++ .../src/abstract-private-key-store.ts | 30 ++++- .../key-manager/src/abstract-secret-box.ts | 6 + packages/key-manager/src/index.ts | 2 +- packages/key-manager/src/key-manager.ts | 13 +- packages/key-manager/src/memory-key-store.ts | 12 +- .../kms-local/src/key-management-system.ts | 20 ++- packages/kms-local/src/secret-box.ts | 10 ++ .../message-handler/src/message-handler.ts | 14 +- packages/message-handler/src/message.ts | 7 + packages/remote-client/src/client.ts | 11 ++ packages/remote-client/src/openApi.ts | 12 ++ packages/remote-server/src/agent-router.ts | 7 +- packages/remote-server/src/api-key-auth.ts | 7 + .../remote-server/src/api-schema-router.ts | 2 + packages/remote-server/src/default-did.ts | 8 ++ .../remote-server/src/messaging-router.ts | 6 +- .../remote-server/src/request-agent-router.ts | 6 +- .../remote-server/src/web-did-doc-router.ts | 7 + .../selective-disclosure/plugin.schema.json | 4 + .../src/action-handler.ts | 10 +- packages/selective-disclosure/src/index.ts | 7 + .../src/message-handler.ts | 4 +- packages/selective-disclosure/src/types.ts | 22 ++- packages/test-react-app/.eslintrc.js | 13 +- packages/url-handler/src/message-handler.ts | 7 + packages/utils/src/type-utils.ts | 6 +- 101 files changed, 1151 insertions(+), 438 deletions(-) delete mode 100644 packages/credential-status/jest.config.js diff --git a/package.json b/package.json index 81038215b..5165a1083 100644 --- a/package.json +++ b/package.json @@ -3,9 +3,11 @@ "private": true, "version": "1.0.0", "scripts": { - "build": "lerna run build && yarn build:schema-api", "bootstrap": "lerna bootstrap", - "build:schema-api": "lerna run extract-api && lerna run generate-plugin-schema", + "build": "yarn build:js && yarn build:api && yarn build:schema", + "build:js": "lerna run build --stream", + "build:api": "lerna run extract-api --stream", + "build:schema": "lerna run generate-plugin-schema --stream", "lint": "echo \"linting not yet enabled\"", "test:integration-build": "yarn test:integration-prepare && yarn test:integration-pretty", "test:integration-prepare": "ts-node --project packages/tsconfig.settings.json ./scripts/prepare-integration-tests.ts", diff --git a/packages/cli/package.json b/packages/cli/package.json index d571dda8b..cc51a3269 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -14,8 +14,8 @@ "update-veramo-latest": "yarn add @veramo/core@latest @veramo/discovery@latest @veramo/remote-client@latest @veramo/remote-server@latest @veramo/did-provider-key@latest @veramo/did-resolver@latest @veramo/did-jwt@latest @veramo/credential-w3c@latest @veramo/did-provider-ethr@latest @veramo/did-provider-web@latest @veramo/did-comm@latest @veramo/kms-local@latest @veramo/selective-disclosure@latest @veramo/data-store@latest @veramo/key-manager@latest @veramo/message-handler@latest @veramo/did-manager@latest @veramo/url-handler@latest" }, "dependencies": { - "@microsoft/api-extractor": "7.23.1", - "@microsoft/api-extractor-model": "7.17.2", + "@microsoft/api-extractor": "7.24.2", + "@microsoft/api-extractor-model": "7.17.3", "@types/blessed": "^0.1.17", "@types/swagger-ui-express": "^4.1.3", "@veramo/core": "^3.1.4", diff --git a/packages/core/plugin.schema.json b/packages/core/plugin.schema.json index 625e9c2a0..26afe0848 100644 --- a/packages/core/plugin.schema.json +++ b/packages/core/plugin.schema.json @@ -7,15 +7,15 @@ "properties": { "didDocument": { "$ref": "#/components/schemas/DIDDocument", - "description": "the DID document from which to extract the fragment. This MUST be the document resolved by {@link resolveDid }" + "description": "the DID document from which to extract the fragment. This MUST be the document resolved by\n {@link IResolver.resolveDid }" }, "didUrl": { "type": "string", - "description": "The DID URI that refers to the subsection by #fragment. Example: did:example:identifier#controller" + "description": "The DID URI that needs to be dereferenced. This should refer to the subsection by #fragment.\n\nExample: did:example:identifier#controller" }, "section": { "$ref": "#/components/schemas/DIDDocumentSection", - "description": "The section of the DID document where to search for the fragment. Example 'keyAgreement', or 'assertionMethod', or 'authentication', etc" + "description": "Optional. The section of the DID document where to search for the fragment. Example 'keyAgreement', or 'assertionMethod', or 'authentication', etc" } }, "required": [ @@ -273,7 +273,8 @@ "keyAgreement", "capabilityInvocation", "capabilityDelegation" - ] + ], + "description": "Refers to a section of a DID document. Either the list of verification methods or services or one of the verification relationships.\n\nSee {@link https://www.w3.org/TR/did-core/#verification-relationships | verification relationships }" }, "DIDDocComponent": { "anyOf": [ @@ -451,7 +452,7 @@ "Bls12381G1", "Bls12381G2" ], - "description": "Cryptographic key type" + "description": "Cryptographic key type." }, "KeyMetadata": { "type": "object", @@ -462,7 +463,8 @@ "type": "string" } } - } + }, + "description": "This encapsulates data about a key.\n\nImplementations of {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem } should populate this object, for each key, with the algorithms that can be performed using it.\n\nThis can also be used to add various tags to the keys under management." }, "ManagedKeyInfo": { "type": "object", @@ -501,7 +503,7 @@ "type", "publicKeyHex" ], - "description": "Represents information about a managed key. Private or secret key material is not present." + "description": "Represents information about a managed key. Private or secret key material is NOT present." }, "IKeyManagerDecryptJWEArgs": { "type": "object", @@ -847,7 +849,7 @@ } }, "keyManagerDecryptJWE": { - "description": "Decrypts data", + "description": "Decrypts data This API may change without a BREAKING CHANGE notice.", "arguments": { "$ref": "#/components/schemas/IKeyManagerDecryptJWEArgs" }, @@ -865,7 +867,7 @@ } }, "keyManagerEncryptJWE": { - "description": "Encrypts data", + "description": "Encrypts data This API may change without a BREAKING CHANGE notice.", "arguments": { "$ref": "#/components/schemas/IKeyManagerEncryptJWEArgs" }, @@ -1019,7 +1021,7 @@ "Bls12381G1", "Bls12381G2" ], - "description": "Cryptographic key type" + "description": "Cryptographic key type." }, "KeyMetadata": { "type": "object", @@ -1030,7 +1032,8 @@ "type": "string" } } - } + }, + "description": "This encapsulates data about a key.\n\nImplementations of {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem } should populate this object, for each key, with the algorithms that can be performed using it.\n\nThis can also be used to add various tags to the keys under management." }, "IDIDManagerAddServiceArgs": { "type": "object", @@ -1264,7 +1267,7 @@ "keys", "provider" ], - "description": "Represents the minimum amount of information needed to import an {@link IIdentifier }" + "description": "Represents the minimum amount of information needed to import an {@link IIdentifier } ." }, "MinimalImportableKey": { "$ref": "#/components/schemas/RequireOnly", @@ -1742,6 +1745,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiablePresentation": { @@ -2025,7 +2032,7 @@ "required": [ "column" ], - "description": "Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." + "description": "Represents a WHERE predicate for a {@link FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." }, "TIdentifiersColumns": { "type": "string", @@ -2055,7 +2062,7 @@ "column", "direction" ], - "description": "Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query." + "description": "Represents the sort order of results from a {@link FindArgs } query." }, "PartialIdentifier": { "type": "object", @@ -2145,7 +2152,7 @@ "Bls12381G1", "Bls12381G2" ], - "description": "Cryptographic key type" + "description": "Cryptographic key type." }, "KeyMetadata": { "type": "object", @@ -2156,7 +2163,8 @@ "type": "string" } } - } + }, + "description": "This encapsulates data about a key.\n\nImplementations of {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem } should populate this object, for each key, with the algorithms that can be performed using it.\n\nThis can also be used to add various tags to the keys under management." }, "IService": { "type": "object", @@ -2251,7 +2259,7 @@ "required": [ "column" ], - "description": "Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." + "description": "Represents a WHERE predicate for a {@link FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." }, "TMessageColumns": { "type": "string", @@ -2287,7 +2295,7 @@ "column", "direction" ], - "description": "Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query." + "description": "Represents the sort order of results from a {@link FindArgs } query." }, "IMessage": { "type": "object", @@ -2505,6 +2513,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiablePresentation": { @@ -2652,7 +2664,7 @@ "required": [ "column" ], - "description": "Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." + "description": "Represents a WHERE predicate for a {@link FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." }, "TCredentialColumns": { "type": "string", @@ -2685,7 +2697,7 @@ "column", "direction" ], - "description": "Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query." + "description": "Represents the sort order of results from a {@link FindArgs } query." }, "UniqueVerifiableCredential": { "type": "object", @@ -2769,7 +2781,7 @@ "required": [ "column" ], - "description": "Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." + "description": "Represents a WHERE predicate for a {@link FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." }, "TClaimsColumns": { "type": "string", @@ -2805,7 +2817,7 @@ "column", "direction" ], - "description": "Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query." + "description": "Represents the sort order of results from a {@link FindArgs } query." }, "FindPresentationsArgs": { "$ref": "#/components/schemas/FindArgs-TPresentationColumns", @@ -2873,7 +2885,7 @@ "required": [ "column" ], - "description": "Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." + "description": "Represents a WHERE predicate for a {@link FindArgs } query. In situations where multiple WHERE predicates are present, they are combined with AND." }, "TPresentationColumns": { "type": "string", @@ -2906,7 +2918,7 @@ "column", "direction" ], - "description": "Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query." + "description": "Represents the sort order of results from a {@link FindArgs } query." }, "UniqueVerifiablePresentation": { "type": "object", @@ -3277,6 +3289,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiablePresentation": { diff --git a/packages/core/src/agent.ts b/packages/core/src/agent.ts index 4ee7517b4..0cac44db3 100644 --- a/packages/core/src/agent.ts +++ b/packages/core/src/agent.ts @@ -71,7 +71,7 @@ export interface IAgentOptions { /** * Flag that enables schema validation for plugin methods. * - * @default false + * Defaults to `false`. */ schemaValidation?: boolean } diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 6c35deba0..1cad80807 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -16,5 +16,12 @@ export * from './types/IMessage' export * from './types/IMessageHandler' export * from './types/IResolver' export * from './types/vc-data-model' + +/** + * This represents the collection of schemas for the core plugins. + * Implementations of these schemas can be provided by other packages. + * + * @public + */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/core/src/types/IDataStoreORM.ts b/packages/core/src/types/IDataStoreORM.ts index 79e348826..22ee88ad9 100644 --- a/packages/core/src/types/IDataStoreORM.ts +++ b/packages/core/src/types/IDataStoreORM.ts @@ -4,9 +4,9 @@ import { IAgentContext, IPluginMethodMap } from './IAgent' import { IMessage } from './IMessage' /** - * Represents the sort order of results from a { @link IDataStoreORM.FindArgs } query. + * Represents the sort order of results from a {@link FindArgs} query. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface Order { column: TColumns @@ -14,10 +14,10 @@ export interface Order { } /** - * Represents a WHERE predicate for a { @link IDataStoreORM.FindArgs } query. + * Represents a WHERE predicate for a {@link FindArgs} query. * In situations where multiple WHERE predicates are present, they are combined with AND. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface Where { column: TColumns @@ -39,7 +39,7 @@ export interface Where { /** * Represents an {@link IDataStoreORM} Query. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface FindArgs { /** @@ -68,7 +68,7 @@ export interface FindArgs { * The columns that can be queried for an {@link IIdentifier} * * @deprecated This type will be removed in future versions of this plugin interface. - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type TIdentifiersColumns = 'did' | 'alias' | 'provider' @@ -76,7 +76,7 @@ export type TIdentifiersColumns = 'did' | 'alias' | 'provider' * The columns that can be queried for an {@link IMessage} * * See {@link IDataStoreORM.dataStoreORMGetMessagesCount} - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type TMessageColumns = | 'from' @@ -96,7 +96,7 @@ export type TMessageColumns = * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentials} * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentialsCount} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type TCredentialColumns = | 'context' @@ -113,7 +113,7 @@ export type TCredentialColumns = * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentialsByClaims} * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentialsByClaimsCount} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type TClaimsColumns = | 'context' @@ -133,7 +133,7 @@ export type TClaimsColumns = * See {@link IDataStoreORM.dataStoreORMGetVerifiablePresentations} * See {@link IDataStoreORM.dataStoreORMGetVerifiablePresentationsCount} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type TPresentationColumns = | 'context' @@ -152,7 +152,7 @@ export type TPresentationColumns = * This does not constitute an authorization mechanism, but relies on an authorization mechanism existing before the * Veramo Agent is created. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface AuthorizedDIDContext extends IAgentContext<{}> { authorizedDID?: string @@ -164,7 +164,7 @@ export interface AuthorizedDIDContext extends IAgentContext<{}> { * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentials} * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentialsByClaims} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface UniqueVerifiableCredential { hash: string @@ -176,7 +176,7 @@ export interface UniqueVerifiableCredential { * * See {@link IDataStoreORM.dataStoreORMGetVerifiablePresentations} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export interface UniqueVerifiablePresentation { hash: string @@ -186,7 +186,7 @@ export interface UniqueVerifiablePresentation { /** * The filter that can be used to find {@link IIdentifier}s in the data store. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type FindIdentifiersArgs = FindArgs @@ -194,7 +194,7 @@ export type FindIdentifiersArgs = FindArgs * The filter that can be used to find {@link IMessage}s in the data store. * See {@link IDataStoreORM.dataStoreORMGetMessages} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type FindMessagesArgs = FindArgs @@ -203,7 +203,7 @@ export type FindMessagesArgs = FindArgs * of their claims. * * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentialsByClaims} - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type FindClaimsArgs = FindArgs @@ -211,7 +211,7 @@ export type FindClaimsArgs = FindArgs * The filter that can be used to find {@link VerifiableCredential}s in the data store. * See {@link IDataStoreORM.dataStoreORMGetVerifiableCredentials} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type FindCredentialsArgs = FindArgs @@ -219,14 +219,14 @@ export type FindCredentialsArgs = FindArgs * The filter that can be used to find {@link VerifiablePresentation}s in the data store. * See {@link IDataStoreORM.dataStoreORMGetVerifiablePresentations} * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type FindPresentationsArgs = FindArgs /** * The result of a {@link IDataStoreORM.dataStoreORMGetIdentifiers} query. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export type PartialIdentifier = Partial @@ -239,7 +239,11 @@ export type PartialIdentifier = Partial * If this interface is implemented by a different plugin than {@link IDataStore}, then both plugins MUST use the same * media for data storage. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @see {@link @veramo/data-store#DataStoreORM} for an implementation using a TypeORM backend + * @see {@link @veramo/data-store-json#DataStoreJson} for an implementation using a JSON object that can also be + * persisted. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDataStoreORM extends IPluginMethodMap { /** @@ -251,12 +255,12 @@ export interface IDataStoreORM extends IPluginMethodMap { * AbstractDIDStore}, then these identifiers can also come from {@link IDIDManager.didManagerCreate | * didManagerCreate} or {@link IDIDManager.didManagerImport | didManagerImport} operations. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * * @deprecated This will be removed in future versions of this plugin interface. - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetIdentifiers( args: FindIdentifiersArgs, @@ -272,24 +276,24 @@ export interface IDataStoreORM extends IPluginMethodMap { * AbstractDIDStore}, then these identifiers can also come from {@link IDIDManager.didManagerCreate | * didManagerCreate} or {@link IDIDManager.didManagerImport | didManagerImport} operations. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * * @deprecated This will be removed in future versions of this plugin interface. - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetIdentifiersCount(args: FindIdentifiersArgs, context: AuthorizedDIDContext): Promise /** * Returns a list of {@link IMessage}s that match the given filter. - * These are messages that were stored using {IDataStore.dataStoreSaveMessage | dataStoreSaveMessage}. + * These are messages that were stored using {@link IDataStore.dataStoreSaveMessage | dataStoreSaveMessage}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetMessages(args: FindMessagesArgs, context: AuthorizedDIDContext): Promise> @@ -297,11 +301,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * Returns a count of {@link IMessage}s that match the given filter. * These are messages that were stored using {@link IDataStore.dataStoreSaveMessage | dataStoreSaveMessage}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying. + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetMessagesCount(args: FindMessagesArgs, context: AuthorizedDIDContext): Promise @@ -312,11 +316,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are VerifiableCredentials that were stored using * {@link IDataStore.dataStoreSaveVerifiableCredential | dataStoreSaveVerifiableCredential}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiableCredentialsByClaims( args: FindClaimsArgs, @@ -330,11 +334,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are VerifiableCredentials that were stored using * {@link IDataStore.dataStoreSaveVerifiableCredential | dataStoreSaveVerifiableCredential}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiableCredentialsByClaimsCount( args: FindClaimsArgs, @@ -348,11 +352,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are VerifiableCredentials that were stored using * {@link IDataStore.dataStoreSaveVerifiableCredential | dataStoreSaveVerifiableCredential}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiableCredentials( args: FindCredentialsArgs, @@ -366,11 +370,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are VerifiableCredentials that were stored using * {@link IDataStore.dataStoreSaveVerifiableCredential | dataStoreSaveVerifiableCredential}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiableCredentialsCount( args: FindCredentialsArgs, @@ -384,11 +388,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are {@link VerifiablePresentation}s that were stored using * {@link IDataStore.dataStoreSaveVerifiablePresentation | dataStoreSaveVerifiablePresentation}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiablePresentations( args: FindPresentationsArgs, @@ -402,11 +406,11 @@ export interface IDataStoreORM extends IPluginMethodMap { * These are {@link VerifiablePresentation}s that were stored using * {@link IDataStore.dataStoreSaveVerifiablePresentation | dataStoreSaveVerifiablePresentation}. * - * @param args The filter to apply when querying - * @param context Can be sued to signal that only a particular DID is authorized to perform this operation. This will - * cause the result to only contain data that this DID should be able to access. + * @param args - The filter to apply when querying + * @param context - Can be used to signal that only a particular DID is authorized to perform this operation. This + * will cause the result to only contain data that this DID should be able to access. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ dataStoreORMGetVerifiablePresentationsCount( args: FindPresentationsArgs, diff --git a/packages/core/src/types/IIdentifier.ts b/packages/core/src/types/IIdentifier.ts index 2175aa4c4..3ca4ecb29 100644 --- a/packages/core/src/types/IIdentifier.ts +++ b/packages/core/src/types/IIdentifier.ts @@ -37,7 +37,9 @@ export interface IIdentifier { } /** - * Represents the minimum amount of information needed to import an {@link IIdentifier} + * Represents the minimum amount of information needed to import an {@link IIdentifier}. + * + * @public */ export type MinimalImportableIdentifier = { keys: Array @@ -45,7 +47,8 @@ export type MinimalImportableIdentifier = { } & Omit /** - * Cryptographic key type + * Cryptographic key type. + * * @public */ export type TKeyType = 'Ed25519' | 'Secp256k1' | 'X25519' | 'Bls12381G1' | 'Bls12381G2' @@ -86,8 +89,19 @@ export interface IKey { meta?: KeyMetadata | null } +/** + * This encapsulates data about a key. + * + * Implementations of {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem} should + * populate this object, for each key, with the algorithms that can be performed using it. + * + * This can also be used to add various tags to the keys under management. + * + * @public + */ export interface KeyMetadata { algorithms?: string[] + [x: string]: any } diff --git a/packages/core/src/types/IKeyManager.ts b/packages/core/src/types/IKeyManager.ts index ab47e6135..782660d8b 100644 --- a/packages/core/src/types/IKeyManager.ts +++ b/packages/core/src/types/IKeyManager.ts @@ -3,17 +3,23 @@ import { TKeyType, IKey, KeyMetadata } from './IIdentifier' /** * Represents an object type where a subset of keys are required and everything else is optional. + * + * @public */ export type RequireOnly = Required> & Partial /** * Represents the properties required to import a key. + * + * @public */ export type MinimalImportableKey = RequireOnly /** * Represents information about a managed key. - * Private or secret key material is not present. + * Private or secret key material is NOT present. + * + * @public */ export type ManagedKeyInfo = Omit @@ -62,7 +68,7 @@ export interface IKeyManagerDeleteArgs { /** * Input arguments for {@link IKeyManager.keyManagerEncryptJWE | keyManagerEncryptJWE} - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IKeyManagerEncryptJWEArgs { /** @@ -83,7 +89,7 @@ export interface IKeyManagerEncryptJWEArgs { /** * Input arguments for {@link IKeyManager.keyManagerDecryptJWE | keyManagerDecryptJWE} - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IKeyManagerDecryptJWEArgs { /** @@ -179,7 +185,18 @@ export interface IKeyManagerSignEthTXArgs { } /** - * Key manager interface + * Key manager interface. + * + * This defines an interface for a plugin that orchestrates various implementations of + * {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem}. + * + * See {@link @veramo/key-manager#KeyManager | KeyManager} for a reference implementation. + * + * The methods of this plugin are used automatically by other plugins, such as + * {@link @veramo/did-manager#DIDManager | DIDManager}, + * {@link @veramo/credential-w3c#CredentialIssuer | CredentialIssuer}, or {@link @veramo/did-comm#DIDComm | DIDComm} to + * perform their required cryptographic operations using the managed keys. + * * @public */ export interface IKeyManager extends IPluginMethodMap { @@ -210,8 +227,9 @@ export interface IKeyManager extends IPluginMethodMap { /** * Generates a signature according to the algorithm specified. - * @throws `Error("not_supported")` if the KMS does not support the operation or if the key does not match the algorithm. - * @param args + * @throws `Error("not_supported")` if the KMS does not support the operation or if the key does not match the + * algorithm. + * @param args - The input to the signing method, including data to be signed, key reference and algorithm to use. */ keyManagerSign(args: IKeyManagerSignArgs): Promise @@ -221,20 +239,21 @@ export interface IKeyManager extends IPluginMethodMap { * This computes the raw shared secret (the result of a Diffie-Hellman computation) * To use this for symmetric encryption you MUST apply a KDF on the result. * - * @param args {@link IKeyManagerSharedKeyArgs} + * @param args - {@link IKeyManagerSharedSecretArgs} The input to compute the shared secret, including the local key + * reference and remote key details. * @returns a `Promise` that resolves to a hex encoded shared secret */ keyManagerSharedSecret(args: IKeyManagerSharedSecretArgs): Promise /** * Encrypts data - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ keyManagerEncryptJWE(args: IKeyManagerEncryptJWEArgs): Promise /** * Decrypts data - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ keyManagerDecryptJWE(args: IKeyManagerDecryptJWEArgs): Promise diff --git a/packages/core/src/types/IResolver.ts b/packages/core/src/types/IResolver.ts index ea4ad43e8..c936eec2f 100644 --- a/packages/core/src/types/IResolver.ts +++ b/packages/core/src/types/IResolver.ts @@ -5,6 +5,7 @@ import { ServiceEndpoint, VerificationMethod, } from 'did-resolver' + export { DIDDocument, DIDResolutionOptions, DIDResolutionResult } from 'did-resolver' import { IPluginMethodMap } from './IAgent' @@ -31,18 +32,25 @@ export interface ResolveDidArgs { /** * Input arguments for {@link IResolver.getDIDComponentById | getDIDComponentById} - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface GetDIDComponentArgs { /** - * the DID document from which to extract the fragment. This MUST be the document resolved by {@link resolveDid} + * the DID document from which to extract the fragment. This MUST be the document resolved by + * {@link IResolver.resolveDid} */ didDocument: DIDDocument + /** - * The DID URI that refers to the subsection by #fragment. Example: did:example:identifier#controller + * The DID URI that needs to be dereferenced. + * This should refer to the subsection by #fragment. + * + * Example: did:example:identifier#controller */ didUrl: string + /** + * Optional. * The section of the DID document where to search for the fragment. Example 'keyAgreement', or 'assertionMethod', * or 'authentication', etc */ @@ -52,7 +60,7 @@ export interface GetDIDComponentArgs { /** * Return type of {@link IResolver.getDIDComponentById | getDIDComponentById} * represents a `VerificationMethod` or a `ServiceEndpoint` entry from a {@link did-resolver#DIDDocument | DIDDocument} - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type DIDDocComponent = VerificationMethod | ServiceEndpoint @@ -113,21 +121,26 @@ export interface IResolver extends IPluginMethodMap { * }) * ``` * - * @param args.didDocument - the DID document from which to extract the fragment. - * This MUST be the document resolved by {@link resolveDid} - * @param args.didUrl - the DID URI that needs to be dereferenced - * @param args.section - Optional - the section of the DID Document to be used for dereferencing + * @param args - The description of the component you want. * * @returns a `Promise` containing the {@link did-resolver#VerificationMethod | VerificationMethod} or * {@link did-resolver#ServiceEndpoint | ServiceEndpoint} * * @throws `not_found:...` in case the fragment is not displayed in the DID document * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ getDIDComponentById(args: GetDIDComponentArgs): Promise } +/** + * Refers to a section of a DID document. + * Either the list of verification methods or services or one of the verification relationships. + * + * See {@link https://www.w3.org/TR/did-core/#verification-relationships | verification relationships} + * + * @public + */ export type DIDDocumentSection = | 'verificationMethod' | 'publicKey' //used for backward compatibility diff --git a/packages/core/src/types/vc-data-model.ts b/packages/core/src/types/vc-data-model.ts index 85c4661f7..1c7181399 100644 --- a/packages/core/src/types/vc-data-model.ts +++ b/packages/core/src/types/vc-data-model.ts @@ -2,7 +2,7 @@ * Represents a Json Web Token in compact form. * "header.payload.signature" * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type CompactJWT = string @@ -16,7 +16,7 @@ export type CompactJWT = string * * See {@link https://www.w3.org/TR/vc-data-model/#issuer | Issuer data model} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type IssuerType = { id: string; [x: string]: any } | string @@ -27,7 +27,7 @@ export type IssuerType = { id: string; [x: string]: any } | string * * See {@link https://www.w3.org/TR/vc-data-model/#credential-subject | Credential Subject} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type CredentialSubject = { id?: string @@ -42,18 +42,18 @@ export type CredentialSubject = { * * See {@link https://www.w3.org/TR/vc-data-model/#status | Credential Status} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type CredentialStatus = { - id?: string - type?: string + id: string + type: string [x: string]: any } /** * A proof property of a Verifiable Credential or Presentation * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ProofType { type?: string @@ -65,7 +65,7 @@ export interface ProofType { * Represents an unsigned W3C Credential payload. * See {@link https://www.w3.org/TR/vc-data-model/#credentials | VC data model} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface UnsignedCredential { issuer: IssuerType @@ -84,7 +84,7 @@ export interface UnsignedCredential { * Represents a signed Verifiable Credential payload (includes proof), using a JSON representation. * See {@link https://www.w3.org/TR/vc-data-model/#credentials | VC data model} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type VerifiableCredential = UnsignedCredential & { proof: ProofType } @@ -93,7 +93,7 @@ export type VerifiableCredential = UnsignedCredential & { proof: ProofType } * See {@link https://www.w3.org/TR/vc-data-model/#credentials | VC data model} * See {@link https://www.w3.org/TR/vc-data-model/#proof-formats | proof formats} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type W3CVerifiableCredential = VerifiableCredential | CompactJWT diff --git a/packages/core/src/validator.ts b/packages/core/src/validator.ts index f56f692c0..432d89cfd 100644 --- a/packages/core/src/validator.ts +++ b/packages/core/src/validator.ts @@ -5,12 +5,21 @@ validator.setRemoteReference('http://json-schema.org/draft-07/schema#', { type: ['array', 'boolean', 'integer', 'number', 'object', 'string'], }) +/** + * Represents a Schema validation error. + * + * This can occur when a method of the agent is invoked with certain parameters or the returned value doesn't match the + * declared plugin schema. + * + * @public + */ export class ValidationError extends Error { public method: string public code: string public message: string public path: string public description: string + constructor(message: string, method: string, code: string, path: string, description: string) { super(message) this.name = 'ValidationError' @@ -29,6 +38,7 @@ export class PluginReturnTypeError extends Error { public message: string public path: string public description: string + constructor(message: string, method: string, code: string, path: string, description: string) { super(message) this.name = 'PluginReturnTypeError' diff --git a/packages/credential-eip712/plugin.schema.json b/packages/credential-eip712/plugin.schema.json index 25faa680f..4a5b503a4 100644 --- a/packages/credential-eip712/plugin.schema.json +++ b/packages/credential-eip712/plugin.schema.json @@ -100,6 +100,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiableCredential": { @@ -176,7 +180,7 @@ "properties": { "presentation": { "$ref": "#/components/schemas/PresentationPayload", - "description": "The json payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n'@context', 'type' and 'issuanceDate' will be added automatically if omitted" + "description": "The json payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n`@context`, `type` and `issuanceDate` will be added automatically if omitted" }, "keyRef": { "type": "string", diff --git a/packages/credential-eip712/src/agent/CredentialEIP712.ts b/packages/credential-eip712/src/agent/CredentialEIP712.ts index b18cf548d..da5ae6e29 100644 --- a/packages/credential-eip712/src/agent/CredentialEIP712.ts +++ b/packages/credential-eip712/src/agent/CredentialEIP712.ts @@ -7,7 +7,6 @@ import { IIdentifier, } from "@veramo/core" import { - _ExtendedIKey, extractIssuer, MANDATORY_CREDENTIAL_CONTEXT, processEntryToArray, @@ -34,7 +33,7 @@ import { getEthTypesFromInputDoc } from "eip-712-types-generation" /** * A Veramo plugin that implements the {@link ICredentialIssuerEIP712} methods. * - * @public + * @beta This API may change without a BREAKING CHANGE notice. */ export class CredentialIssuerEIP712 implements IAgentPlugin { readonly methods: ICredentialIssuerEIP712 diff --git a/packages/credential-eip712/src/types/ICredentialEIP712.ts b/packages/credential-eip712/src/types/ICredentialEIP712.ts index a44b29824..d2d052c8f 100644 --- a/packages/credential-eip712/src/types/ICredentialEIP712.ts +++ b/packages/credential-eip712/src/types/ICredentialEIP712.ts @@ -17,7 +17,7 @@ import { * @remarks Please see {@link https://www.w3.org/TR/vc-data-model | W3C Verifiable Credentials data model} * @remarks Please see {@link https://w3c-ccg.github.io/ethereum-eip712-signature-2021-spec/ | EthereumEip712Signature2021} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICredentialIssuerEIP712 extends IPluginMethodMap { /** @@ -32,7 +32,7 @@ export interface ICredentialIssuerEIP712 extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#credentials | Verifiable Credential data model} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ createVerifiableCredentialEIP712( args: ICreateVerifiableCredentialEIP712Args, @@ -49,7 +49,7 @@ export interface ICredentialIssuerEIP712 extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#credentials | Verifiable Credential data model} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ verifyCredentialEIP712( args: IVerifyCredentialEIP712Args, @@ -93,7 +93,7 @@ export interface ICredentialIssuerEIP712 extends IPluginMethodMap { * Encapsulates the parameters required to create a * {@link https://www.w3.org/TR/vc-data-model/#credentials | W3C Verifiable Credential} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateVerifiableCredentialEIP712Args { /** @@ -119,7 +119,7 @@ export interface ICreateVerifiableCredentialEIP712Args { * using the {@link https://w3c-ccg.github.io/ethereum-eip712-signature-2021-spec/ | EthereumEip712Signature2021} * proof format. * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateVerifiablePresentationEIP712Args { /** @@ -129,7 +129,7 @@ export interface ICreateVerifiablePresentationEIP712Args { * The signer of the Presentation is chosen based on the `holder` property * of the `presentation` * - * '@context', 'type' and 'issuanceDate' will be added automatically if omitted + * `@context`, `type` and `issuanceDate` will be added automatically if omitted */ presentation: PresentationPayload @@ -144,7 +144,7 @@ export interface ICreateVerifiablePresentationEIP712Args { * Encapsulates the parameters required to verify a * {@link https://www.w3.org/TR/vc-data-model/#credentials | W3C Verifiable Credential} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IVerifyCredentialEIP712Args { /** @@ -184,12 +184,8 @@ export interface ICreateVerifiablePresentationEIP712Args { * * This interface can be used for static type checks, to make sure your application is properly initialized. * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export type IRequiredContext = IAgentContext< IResolver & IKeyManager & IDIDManager > - -export type ContextDoc = { - '@context': Record -} diff --git a/packages/credential-ld/plugin.schema.json b/packages/credential-ld/plugin.schema.json index 9cd4515fa..2de35c22f 100644 --- a/packages/credential-ld/plugin.schema.json +++ b/packages/credential-ld/plugin.schema.json @@ -7,7 +7,7 @@ "properties": { "credential": { "$ref": "#/components/schemas/CredentialPayload", - "description": "The json payload of the Credential according to the\n {@link https://www.w3.org/TR/vc-data-model/#credentials | canonical model } \n\nThe signer of the Credential is chosen based on the `issuer.id` property of the `credential`\n\n'@context', 'type' and 'issuanceDate' will be added automatically if omitted" + "description": "The json payload of the Credential according to the\n {@link https://www.w3.org/TR/vc-data-model/#credentials | canonical model } \n\nThe signer of the Credential is chosen based on the `issuer.id` property of the `credential`\n\n`@context`, `type` and `issuanceDate` will be added automatically if omitted" }, "keyRef": { "type": "string", @@ -100,6 +100,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiableCredential": { @@ -176,7 +180,7 @@ "properties": { "presentation": { "$ref": "#/components/schemas/PresentationPayload", - "description": "The json payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n'@context', 'type' and 'issuanceDate' will be added automatically if omitted" + "description": "The json payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n`@context`, `type` and `issuanceDate` will be added automatically if omitted." }, "challenge": { "type": "string", @@ -329,8 +333,7 @@ }, "fetchRemoteContexts": { "type": "boolean", - "description": "Set this to true if you want the '@context' URLs to be fetched in case they are not pre-loaded.", - "default": false + "description": "Set this to true if you want the `@context` URLs to be fetched in case they are not pre-loaded.\n\nDefaults to `false`" } }, "required": [ @@ -355,8 +358,7 @@ }, "fetchRemoteContexts": { "type": "boolean", - "description": "Set this to true if you want the '@context' URLs to be fetched in case they are not pre-loaded.", - "default": false + "description": "Set this to true if you want the `@context` URLs to be fetched in case they are not pre-loaded.\n\nDefaults to `false`" } }, "required": [ diff --git a/packages/credential-ld/src/index.ts b/packages/credential-ld/src/index.ts index ddb2e29b8..aea45d00f 100644 --- a/packages/credential-ld/src/index.ts +++ b/packages/credential-ld/src/index.ts @@ -1,7 +1,13 @@ /** - * Provides a {@link @veramo/credential-ld#CredentialIssuerLD | plugin} for the {@link @veramo/core#Agent} that implements + * Provides a {@link @veramo/credential-ld#CredentialIssuerLD | plugin} for the {@link @veramo/core#Agent} that + * implements * {@link @veramo/credential-ld#ICredentialIssuerLD} interface. * + * This plugin adds support for working with JSON-LD credentials. + * When installed, this plugin will be automatically used by + * {@link @veramo/credential-w3c#CredentialIssuer | CredentialIssuer} if the user requests the credential to be signed + * by one of the installed signature suites. + * * @packageDocumentation */ export { CredentialIssuerLD } from './action-handler' @@ -10,5 +16,12 @@ export { LdDefaultContexts } from './ld-default-contexts' export { VeramoLdSignature } from './ld-suites' export * from './suites/EcdsaSecp256k1RecoverySignature2020' export * from './suites/Ed25519Signature2018' + +/** + * The parameter and return types schemas for the {@link @veramo/credential-ld#CredentialIssuerLD | CredentialIssuerLD} + * plugin methods. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/credential-ld/src/ld-default-contexts.ts b/packages/credential-ld/src/ld-default-contexts.ts index c3dcb12b6..34fecb93c 100644 --- a/packages/credential-ld/src/ld-default-contexts.ts +++ b/packages/credential-ld/src/ld-default-contexts.ts @@ -5,7 +5,12 @@ async function _read(_path: string): Promise { } /** - * Provides a hardcoded map of common context definitions + * Provides a hardcoded map of common Linked Data `@context` definitions. + * + * You can use this to bootstrap the `@context` definitions used by + * {@link @veramo/credential-ld#CredentialIssuerLD | CredentialIssuerLD} with these common context definitions. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export const LdDefaultContexts = new Map([ ['https://www.w3.org/2018/credentials/v1', _read('www.w3.org_2018_credentials_v1.json')], diff --git a/packages/credential-ld/src/ld-suites.ts b/packages/credential-ld/src/ld-suites.ts index a0e77d42b..5b99f1a49 100644 --- a/packages/credential-ld/src/ld-suites.ts +++ b/packages/credential-ld/src/ld-suites.ts @@ -7,10 +7,15 @@ import { PresentationPayload, TKeyType, } from '@veramo/core' -import { DIDDocument } from 'did-resolver/src/resolver' +import { DIDDocument } from 'did-resolver' export type RequiredAgentMethods = IResolver & Pick +/** + * Base class for Veramo adapters of LinkedDataSignature suites. + * + * @alpha This API is experimental and is very likely to change or disappear in future releases without notice. + */ export abstract class VeramoLdSignature { // LinkedDataSignature Suites according to // https://github.com/digitalbazaar/jsonld-signatures/blob/main/lib/suites/LinkedDataSignature.js diff --git a/packages/credential-ld/src/suites/EcdsaSecp256k1RecoverySignature2020.ts b/packages/credential-ld/src/suites/EcdsaSecp256k1RecoverySignature2020.ts index 4ea6d4f41..ca6f2c586 100644 --- a/packages/credential-ld/src/suites/EcdsaSecp256k1RecoverySignature2020.ts +++ b/packages/credential-ld/src/suites/EcdsaSecp256k1RecoverySignature2020.ts @@ -8,6 +8,11 @@ import { import * as u8a from 'uint8arrays' import { asArray, encodeJoseBlob } from '@veramo/utils' +/** + * Veramo wrapper for the EcdsaSecp256k1RecoverySignature2020 suite by Transmute Industries + * + * @alpha This API is experimental and is very likely to change or disappear in future releases without notice. + */ export class VeramoEcdsaSecp256k1RecoverySignature2020 extends VeramoLdSignature { getSupportedVerificationType(): string { return 'EcdsaSecp256k1RecoveryMethod2020' diff --git a/packages/credential-ld/src/suites/Ed25519Signature2018.ts b/packages/credential-ld/src/suites/Ed25519Signature2018.ts index c1beb6595..a950f5282 100644 --- a/packages/credential-ld/src/suites/Ed25519Signature2018.ts +++ b/packages/credential-ld/src/suites/Ed25519Signature2018.ts @@ -4,6 +4,11 @@ import { CredentialPayload, DIDDocument, IAgentContext, IKey, TKeyType } from '@ import * as u8a from 'uint8arrays' import { Ed25519Signature2018, Ed25519VerificationKey2018 } from '@transmute/ed25519-signature-2018' +/** + * Veramo wrapper for the Ed25519Signature2018 suite by Transmute Industries + * + * @alpha This API is experimental and is very likely to change or disappear in future releases without notice. + */ export class VeramoEd25519Signature2018 extends VeramoLdSignature { getSupportedVerificationType(): string { return 'Ed25519VerificationKey2018' diff --git a/packages/credential-ld/src/types.ts b/packages/credential-ld/src/types.ts index 2be442498..099ec1310 100644 --- a/packages/credential-ld/src/types.ts +++ b/packages/credential-ld/src/types.ts @@ -2,7 +2,6 @@ import { CredentialPayload, IAgentContext, IDIDManager, - IKey, IKeyManager, IPluginMethodMap, IResolver, @@ -13,11 +12,12 @@ import { /** * The interface definition for a plugin that can issue and verify Verifiable Credentials and Presentations - * that use JSON-LD format. + * that use JSON-LD format (also called Data Integrity Proofs). * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model | W3C Verifiable Credentials data model} + * @see {@link https://www.w3.org/TR/vc-data-model/#data-integrity-proofs | Data Integrity proofs} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICredentialIssuerLD extends IPluginMethodMap { /** @@ -32,7 +32,7 @@ export interface ICredentialIssuerLD extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#presentations | Verifiable Presentation data model } * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ createVerifiablePresentationLD( args: ICreateVerifiablePresentationLDArgs, @@ -51,7 +51,7 @@ export interface ICredentialIssuerLD extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#credentials | Verifiable Credential data model} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ createVerifiableCredentialLD( args: ICreateVerifiableCredentialLDArgs, @@ -68,7 +68,7 @@ export interface ICredentialIssuerLD extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#credentials | Verifiable Credential data model} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ verifyCredentialLD(args: IVerifyCredentialLDArgs, context: IRequiredContext): Promise @@ -82,7 +82,7 @@ export interface ICredentialIssuerLD extends IPluginMethodMap { * * @remarks Please see {@link https://www.w3.org/TR/vc-data-model/#presentations | Verifiable Credential data model} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ verifyPresentationLD(args: IVerifyPresentationLDArgs, context: IRequiredContext): Promise } @@ -91,7 +91,7 @@ export interface ICredentialIssuerLD extends IPluginMethodMap { * Encapsulates the parameters required to create a * {@link https://www.w3.org/TR/vc-data-model/#presentations | W3C Verifiable Presentation} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateVerifiablePresentationLDArgs { /** @@ -101,7 +101,7 @@ export interface ICreateVerifiablePresentationLDArgs { * The signer of the Presentation is chosen based on the `holder` property * of the `presentation` * - * '@context', 'type' and 'issuanceDate' will be added automatically if omitted + * `@context`, `type` and `issuanceDate` will be added automatically if omitted. */ presentation: PresentationPayload @@ -125,7 +125,7 @@ export interface ICreateVerifiablePresentationLDArgs { * Encapsulates the parameters required to create a * {@link https://www.w3.org/TR/vc-data-model/#credentials | W3C Verifiable Credential} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateVerifiableCredentialLDArgs { /** @@ -135,7 +135,7 @@ export interface ICreateVerifiableCredentialLDArgs { * The signer of the Credential is chosen based on the `issuer.id` property * of the `credential` * - * '@context', 'type' and 'issuanceDate' will be added automatically if omitted + * `@context`, `type` and `issuanceDate` will be added automatically if omitted */ credential: CredentialPayload @@ -149,7 +149,7 @@ export interface ICreateVerifiableCredentialLDArgs { * Encapsulates the parameters required to verify a * {@link https://www.w3.org/TR/vc-data-model/#credentials | W3C Verifiable Credential} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice */ export interface IVerifyCredentialLDArgs { /** @@ -163,9 +163,9 @@ export interface IVerifyCredentialLDArgs { credential: VerifiableCredential /** - * Set this to true if you want the '@context' URLs to be fetched in case they are not pre-loaded. + * Set this to true if you want the `@context` URLs to be fetched in case they are not pre-loaded. * - * @default false + * Defaults to `false` */ fetchRemoteContexts?: boolean } @@ -174,7 +174,7 @@ export interface IVerifyCredentialLDArgs { * Encapsulates the parameters required to verify a * {@link https://www.w3.org/TR/vc-data-model/#presentations | W3C Verifiable Presentation} * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IVerifyPresentationLDArgs { /** @@ -198,9 +198,9 @@ export interface IVerifyPresentationLDArgs { domain?: string /** - * Set this to true if you want the '@context' URLs to be fetched in case they are not pre-loaded. + * Set this to true if you want the `@context` URLs to be fetched in case they are not pre-loaded. * - * @default false + * Defaults to `false` */ fetchRemoteContexts?: boolean } @@ -211,12 +211,17 @@ export interface IVerifyPresentationLDArgs { * * This interface can be used for static type checks, to make sure your application is properly initialized. * - * @beta This API is likely to change without a BREAKING CHANGE notice + * @beta This API may change without a BREAKING CHANGE notice. */ export type IRequiredContext = IAgentContext< IResolver & Pick & Pick > +/** + * Describes a document with a `@context` property. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export type ContextDoc = { '@context': Record } diff --git a/packages/credential-status/jest.config.js b/packages/credential-status/jest.config.js deleted file mode 100644 index 4be682084..000000000 --- a/packages/credential-status/jest.config.js +++ /dev/null @@ -1,20 +0,0 @@ -module.exports = { - moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'], - collectCoverage: true, - collectCoverageFrom: ['src/**/*.ts', '!**/types/**', '!**/build/**', '!**/node_modules/**'], - coverageReporters: ['text', 'lcov', 'json'], - coverageDirectory: './coverage', - transform: { - '\\.jsx?$': 'babel-jest', - '\\.tsx?$': 'ts-jest', - }, - transformIgnorePatterns: ['node_modules/(?!credential-status/)'], - testMatch: ['**/__tests__/**/*.test.*'], - globals: { - 'ts-jest': { - tsconfig: './tsconfig.json', - }, - }, - testEnvironment: 'node', - automock: false -} diff --git a/packages/credential-status/plugin.schema.json b/packages/credential-status/plugin.schema.json index 0283cb4ff..097e62288 100644 --- a/packages/credential-status/plugin.schema.json +++ b/packages/credential-status/plugin.schema.json @@ -6,7 +6,7 @@ "type": "object", "properties": { "credential": { - "$ref": "#/components/schemas/CredentialJwtOrJSON" + "$ref": "#/components/schemas/VerifiableCredential" }, "didDoc": { "$ref": "#/components/schemas/DIDDocument" @@ -15,39 +15,121 @@ "required": [ "credential", "didDoc" - ] + ], + "description": "Arguments for calling {@link ICheckCredentialStatus.checkCredentialStatus | checkCredentialStatus } .\n\nThe credential whose status should be checked and the DID document of the credential issuer.\n\nSee {@link https://www.w3.org/TR/vc-data-model/#status | Credential Status }" }, - "CredentialJwtOrJSON": { - "anyOf": [ - { + "VerifiableCredential": { + "type": "object", + "properties": { + "proof": { + "$ref": "#/components/schemas/ProofType" + }, + "issuer": { + "$ref": "#/components/schemas/IssuerType" + }, + "credentialSubject": { + "$ref": "#/components/schemas/CredentialSubject" + }, + "type": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "string" + } + ] + }, + "@context": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "string" + } + ] + }, + "issuanceDate": { + "type": "string" + }, + "expirationDate": { "type": "string" }, + "credentialStatus": { + "$ref": "#/components/schemas/CredentialStatus" + }, + "id": { + "type": "string" + } + }, + "required": [ + "@context", + "credentialSubject", + "issuanceDate", + "issuer", + "proof" + ], + "description": "Represents a signed Verifiable Credential payload (includes proof), using a JSON representation. See {@link https://www.w3.org/TR/vc-data-model/#credentials | VC data model }" + }, + "ProofType": { + "type": "object", + "properties": { + "type": { + "type": "string" + } + }, + "description": "A proof property of a Verifiable Credential or Presentation" + }, + "IssuerType": { + "anyOf": [ { "type": "object", "properties": { - "credentialStatus": { - "$ref": "#/components/schemas/StatusEntry" + "id": { + "type": "string" } - } + }, + "required": [ + "id" + ] + }, + { + "type": "string" } ], - "description": "The Verifiable Credential or Presentation to be verified in either JSON/JSON-LD or JWT format." + "description": "The issuer of a Credential or the holder of a Presentation.\n\nThe value of the issuer property MUST be either a URI or an object containing an id property. It is RECOMMENDED that the URI in the issuer or its id be one which, if de-referenced, results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential.\n\nSee {@link https://www.w3.org/TR/vc-data-model/#issuer | Issuer data model }" }, - "StatusEntry": { + "CredentialSubject": { "type": "object", "properties": { - "type": { + "id": { "type": "string" - }, + } + }, + "description": "The value of the credentialSubject property is defined as a set of objects that contain one or more properties that are each related to a subject of the verifiable credential. Each object MAY contain an id.\n\nSee {@link https://www.w3.org/TR/vc-data-model/#credential-subject | Credential Subject }" + }, + "CredentialStatus": { + "type": "object", + "properties": { "id": { "type": "string" + }, + "type": { + "type": "string" } }, "required": [ - "type", - "id" + "id", + "type" ], - "description": "Represents a status method entry that could be embedded in a W3C Verifiable Credential. Normally, only credentials that list a status method would need to be verified by it.\n\nex: ```json credentialStatus: { type: \"EthrStatusRegistry2019\", id: \"rinkeby:0xregistryAddress\" } ``` See https://www.w3.org/TR/vc-data-model/#status" + "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 }" }, "DIDDocument": { "type": "object", @@ -286,23 +368,11 @@ "type", "serviceEndpoint" ] - }, - "CredentialStatus": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "type": { - "type": "string" - } - }, - "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 }" } }, "methods": { "checkCredentialStatus": { - "description": "", + "description": "Checks the status of a ", "arguments": { "$ref": "#/components/schemas/ICheckCredentialStatusArgs" }, diff --git a/packages/credential-status/src/credential-status.ts b/packages/credential-status/src/credential-status.ts index 56ea5353c..a07d1a326 100644 --- a/packages/credential-status/src/credential-status.ts +++ b/packages/credential-status/src/credential-status.ts @@ -2,6 +2,24 @@ import { IAgentContext, IAgentPlugin } from '@veramo/core' import { Status, StatusMethod } from 'credential-status' import { ICheckCredentialStatus, ICheckCredentialStatusArgs } from './types' +/** + * This plugin implements the {@link @veramo/credential-status#ICheckCredentialStatus | ICheckCredentialStatus} + * interface. + * + * This aggregates some {@link credential-status#StatusMethod | credential status implementations} to provide a second + * layer of validation when verifying Verifiable Credentials. + * + * This is 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. + * + * The results provided by this plugin depend on whether the {@link credential-status#StatusMethod | StatusMethod} + * required by the credential is installed. + * + * @see {@link credential-status#Status} + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export class CredentialStatusPlugin implements IAgentPlugin { private readonly status: Status readonly methods: ICheckCredentialStatus diff --git a/packages/credential-status/src/types.ts b/packages/credential-status/src/types.ts index 976fae37f..57a4a6d50 100644 --- a/packages/credential-status/src/types.ts +++ b/packages/credential-status/src/types.ts @@ -1,20 +1,46 @@ -import { IAgentContext, IPluginMethodMap } from '@veramo/core' -import { CredentialJwtOrJSON, CredentialStatus } from 'credential-status' +import { IAgentContext, IPluginMethodMap, VerifiableCredential } from '@veramo/core' +import { CredentialStatus } from 'credential-status' import { DIDDocument } from 'did-resolver' +/** + * Arguments for calling {@link ICheckCredentialStatus.checkCredentialStatus | checkCredentialStatus}. + * + * The credential whose status should be checked and the DID document of the credential issuer. + * + * See {@link https://www.w3.org/TR/vc-data-model/#status | Credential Status} + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export interface ICheckCredentialStatusArgs { - credential: CredentialJwtOrJSON + credential: VerifiableCredential didDoc: DIDDocument } -export interface ICheckCredentialStatusResult { - revoked: boolean - - // eslint-disable-next-line @typescript-eslint/no-explicit-any - [x: string]: any -} - +/** + * This interface defines a plugin that can check the {@link https://www.w3.org/TR/vc-data-model/#status | status} of a + * {@link @veramo/core#VerifiableCredential | Verifiable Credential}. + * + * This is 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. + * + * The result provided by implementations of this plugin depend on whether the implementation of the StatusMethod is + * available. + * + * @see {@link https://www.w3.org/TR/vc-data-model/#status | Credential Status} for data model documentation. + * @see {@link @veramo/credential-status#CredentialStatusPlugin | CredentialStatusPlugin } for an implementation. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export interface ICheckCredentialStatus extends IPluginMethodMap { + + /** + * Checks the status of a {@link @veramo/core#VerifiableCredential | Verifiable Credential}. + * + * @param args - The credential to be checked, along with the DID document of the issuer. + * @param context - *RESERVED* This is filled by the framework when the method is called. + */ checkCredentialStatus( args: ICheckCredentialStatusArgs, context: IAgentContext, diff --git a/packages/credential-w3c/plugin.schema.json b/packages/credential-w3c/plugin.schema.json index 55edee267..7218c9d47 100644 --- a/packages/credential-w3c/plugin.schema.json +++ b/packages/credential-w3c/plugin.schema.json @@ -7,7 +7,7 @@ "properties": { "credential": { "$ref": "#/components/schemas/CredentialPayload", - "description": "The json payload of the Credential according to the\n {@link https://www.w3.org/TR/vc-data-model/#credentials | canonical model } \n\nThe signer of the Credential is chosen based on the `issuer.id` property of the `credential`\n\n'@context', 'type' and 'issuanceDate' will be added automatically if omitted" + "description": "The JSON payload of the Credential according to the\n {@link https://www.w3.org/TR/vc-data-model/#credentials | canonical model } \n\nThe signer of the Credential is chosen based on the `issuer.id` property of the `credential`\n\n`@context`, `type` and `issuanceDate` will be added automatically if omitted" }, "save": { "type": "boolean", @@ -113,6 +113,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "ProofFormat": { @@ -198,7 +202,7 @@ "properties": { "presentation": { "$ref": "#/components/schemas/PresentationPayload", - "description": "The json payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n'@context', 'type' and 'issuanceDate' will be added automatically if omitted" + "description": "The JSON payload of the Presentation according to the\n {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model } .\n\nThe signer of the Presentation is chosen based on the `holder` property of the `presentation`\n\n`@context`, `type` and `issuanceDate` will be added automatically if omitted" }, "save": { "type": "boolean", diff --git a/packages/credential-w3c/src/action-handler.ts b/packages/credential-w3c/src/action-handler.ts index 0d918f56d..314ffceff 100644 --- a/packages/credential-w3c/src/action-handler.ts +++ b/packages/credential-w3c/src/action-handler.ts @@ -57,13 +57,13 @@ export type ProofFormat = 'jwt' | 'lds' | 'EthereumEip712Signature2021' */ export interface ICreateVerifiablePresentationArgs { /** - * The json payload of the Presentation according to the + * The JSON payload of the Presentation according to the * {@link https://www.w3.org/TR/vc-data-model/#presentations | canonical model}. * * The signer of the Presentation is chosen based on the `holder` property * of the `presentation` * - * '@context', 'type' and 'issuanceDate' will be added automatically if omitted + * `@context`, `type` and `issuanceDate` will be added automatically if omitted */ presentation: PresentationPayload @@ -110,13 +110,13 @@ export interface ICreateVerifiablePresentationArgs { */ export interface ICreateVerifiableCredentialArgs { /** - * The json payload of the Credential according to the + * The JSON payload of the Credential according to the * {@link https://www.w3.org/TR/vc-data-model/#credentials | canonical model} * * The signer of the Credential is chosen based on the `issuer.id` property * of the `credential` * - * '@context', 'type' and 'issuanceDate' will be added automatically if omitted + * `@context`, `type` and `issuanceDate` will be added automatically if omitted */ credential: CredentialPayload diff --git a/packages/credential-w3c/src/index.ts b/packages/credential-w3c/src/index.ts index fd1725200..48549bda0 100644 --- a/packages/credential-w3c/src/index.ts +++ b/packages/credential-w3c/src/index.ts @@ -1,5 +1,6 @@ /** - * Provides a {@link @veramo/credential-w3c#CredentialIssuer | plugin} for the {@link @veramo/core#Agent} that implements + * Provides a {@link @veramo/credential-w3c#CredentialIssuer | plugin} for the {@link @veramo/core#Agent} that + * implements * {@link @veramo/credential-w3c#ICredentialIssuer} interface. * * Provides a {@link @veramo/credential-w3c#W3cMessageHandler | plugin} for the @@ -15,5 +16,10 @@ export { ICreateVerifiablePresentationArgs, ProofFormat, } from './action-handler' +/** + * The parameter and return type schemas for the methods of the {@link @veramo/credential-w3c#ICredentialIssuer} plugin. + * + * @public + */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/data-store-json/src/browser-local-storage-store.ts b/packages/data-store-json/src/browser-local-storage-store.ts index 29b428d7a..3101ed602 100644 --- a/packages/data-store-json/src/browser-local-storage-store.ts +++ b/packages/data-store-json/src/browser-local-storage-store.ts @@ -10,13 +10,15 @@ import { } from './types' /** - * Implementation of {@link VeramoJsonStore} that uses browser localStorage to store data + * Implementation of {@link VeramoJsonStore} that uses browser localStorage to store data. * * @example * ``` * const dataStore = BrowserLocalStorageStore.fromLocalStorage('veramo-state') * const plugin = new DataStoreJson(dataStore) * ``` + * + * @public */ export class BrowserLocalStorageStore implements VeramoJsonStore { notifyUpdate: DiffCallback diff --git a/packages/data-store-json/src/data-store-json.ts b/packages/data-store-json/src/data-store-json.ts index bdad6162b..c4b464e9d 100644 --- a/packages/data-store-json/src/data-store-json.ts +++ b/packages/data-store-json/src/data-store-json.ts @@ -36,13 +36,11 @@ import { } from './types' import { normalizeCredential } from 'did-jwt-vc' -type LocalRecords = Required< - Pick -> +type LocalRecords = Required> /** - * A storage plugin that implements the {@link IDataStore} and {@link IDataStoreORM} methods using a JSON object as a - * backend. + * A Veramo agent storage plugin that implements the {@link @veramo/core#IDataStore | IDataStore} and + * {@link @veramo/core#IDataStoreORM | IDataStoreORM} methods using one big JSON object as a backend. * * Each update operation triggers a callback that can be used to either save the latest state of the agent data or * compute a diff and log only the changes. @@ -51,7 +49,7 @@ type LocalRecords = Required< * memory as well as providing an update notification callback to persist this data. * The JSON object can be pre-populated with data from previous sessions. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export class DataStoreJson implements IAgentPlugin { readonly methods: IDataStore & IDataStoreORM @@ -61,7 +59,7 @@ export class DataStoreJson implements IAgentPlugin { private readonly notifyUpdate: DiffCallback /** - * @param jsonStore a reference to the JSON object that holds the data in memory and implements an update callback. + * @param jsonStore - A reference to the JSON object that holds the data in memory and implements an update callback. * This object can be pre-populated with data from previous sessions, and will be used by reference. */ constructor(jsonStore: VeramoJsonStore) { diff --git a/packages/data-store-json/src/identifier/did-store.ts b/packages/data-store-json/src/identifier/did-store.ts index a049b3e59..7e9012991 100644 --- a/packages/data-store-json/src/identifier/did-store.ts +++ b/packages/data-store-json/src/identifier/did-store.ts @@ -8,8 +8,9 @@ import { serialize, deserialize } from '@ungap/structured-clone' const debug = Debug('veramo:data-store-json:did-store') /** - * An implementation of {@link AbstractDIDStore} that uses a JSON object to store the relationships between DIDs, their - * providers and controllers and their keys and services as they are known and managed by a Veramo agent. + * An implementation of {@link @veramo/did-manager#AbstractDIDStore | AbstractDIDStore} that uses a JSON object to + * store the relationships between DIDs, their providers and controllers and their keys and services as they are known + * and managed by a Veramo agent. * * An instance of this class can be used by {@link @veramo/did-manager#DIDManager} as the data storage layer. * @@ -18,7 +19,7 @@ const debug = Debug('veramo:data-store-json:did-store') * For correct usage, this MUST use the same {@link VeramoJsonStore} instance as the one used by * {@link @veramo/key-manager#KeyManager | KeyManager}. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export class DIDStoreJson extends AbstractDIDStore { private readonly cacheTree: Required> @@ -37,10 +38,10 @@ export class DIDStoreJson extends AbstractDIDStore { } async get({ - did, - alias, - provider, - }: { + did, + alias, + provider, + }: { did?: string alias?: string provider?: string diff --git a/packages/data-store-json/src/identifier/key-store.ts b/packages/data-store-json/src/identifier/key-store.ts index 90738e624..9adb4d803 100644 --- a/packages/data-store-json/src/identifier/key-store.ts +++ b/packages/data-store-json/src/identifier/key-store.ts @@ -8,9 +8,10 @@ import { serialize, deserialize } from '@ungap/structured-clone' const debug = Debug('veramo:data-store-json:key-store') /** - * An implementation of {@link AbstractKeyStore} that uses a JSON object to store the relationships between keys, their - * IDs, aliases and {@link @veramo/key-manager#AbstractKeyManagementSystem | KMS implementations}, as they are known - * and managed by a Veramo agent. + * An implementation of {@link @veramo/key-manager#AbstractKeyStore | AbstractKeyStore} that uses a JSON object to + * store the relationships between keys, their IDs, aliases and + * {@link @veramo/key-manager#AbstractKeyManagementSystem | KMS implementations}, as they are known and managed by a + * Veramo agent. * * An instance of this class can be used by {@link @veramo/key-manager#KeyManager} as the data storage layer. * @@ -19,14 +20,14 @@ const debug = Debug('veramo:data-store-json:key-store') * For correct usage, this MUST use the same {@link VeramoJsonStore} instance as the one used by * {@link @veramo/did-manager#DIDManager | DIDManager}. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export class KeyStoreJson extends AbstractKeyStore { private readonly cacheTree: Required> private readonly notifyUpdate: DiffCallback /** - * @param jsonStore serves as the JSON object storing data in memory as well as providing an update notification + * @param jsonStore - Serves as the JSON object storing data in memory as well as providing an update notification * callback to persist this data. For correct usage, this MUST use the same {@link VeramoJsonStore} instance as the * one used by {@link @veramo/did-manager#DIDManager | DIDManager}. */ diff --git a/packages/data-store-json/src/identifier/private-key-store.ts b/packages/data-store-json/src/identifier/private-key-store.ts index b237cfbf1..dd468e9c3 100644 --- a/packages/data-store-json/src/identifier/private-key-store.ts +++ b/packages/data-store-json/src/identifier/private-key-store.ts @@ -1,5 +1,5 @@ import { AbstractSecretBox, AbstractPrivateKeyStore } from '@veramo/key-manager' -import { ImportablePrivateKey, ManagedPrivateKey } from '@veramo/key-manager/src/abstract-private-key-store' +import { ImportablePrivateKey, ManagedPrivateKey } from '@veramo/key-manager' import { v4 as uuid4 } from 'uuid' import Debug from 'debug' import { DiffCallback, VeramoJsonCache, VeramoJsonStore } from '../types' @@ -8,26 +8,28 @@ import { serialize, deserialize } from '@ungap/structured-clone' const debug = Debug('veramo:data-store-json:private-key-store') /** - * An implementation of {@link AbstractPrivateKeyStore} that uses a JSON object to store the private key material - * needed by {@link @veramo/kms-local#KeyManagementSystem}. + * An implementation of {@link @veramo/key-manager#AbstractPrivateKeyStore | AbstractPrivateKeyStore} that uses a JSON + * object to store the private key material needed by {@link @veramo/kms-local#KeyManagementSystem | + * KeyManagementSystem}. * * This class must be initialized with a {@link VeramoJsonStore}, which serves as the JSON object storing data in * memory as well as providing an update notification callback to persist this data. * The JSON object does not have to be shared with other users of {@link VeramoJsonStore}, but it can be. * - * If an {@link AbstractSecretBox} is used, then key material is encrypted, even in memory. + * If an {@link @veramo/key-manager#AbstractSecretBox | AbstractSecretBox} is used, then key material is encrypted, + * even in memory. * - * @beta This API is likely to change without a BREAKING CHANGE notice. + * @beta This API may change without a BREAKING CHANGE notice. */ export class PrivateKeyStoreJson extends AbstractPrivateKeyStore { private readonly cacheTree: Required> private readonly notifyUpdate: DiffCallback /** - * @param jsonStore This serves as the JSON object storing data in memory as well as providing an update notification + * @param jsonStore - This serves as the JSON object storing data in memory as well as providing an update notification * callback to persist this data. The JSON object does not have to be shared with other users of * {@link VeramoJsonStore}, but it can be. - * @param secretBox if this is used, then key material is encrypted, even in memory. + * @param secretBox - If this is used, then key material is encrypted, even in memory. */ constructor(jsonStore: VeramoJsonStore, private secretBox?: AbstractSecretBox) { super() diff --git a/packages/data-store-json/src/types.ts b/packages/data-store-json/src/types.ts index 936b9337b..bbb375457 100644 --- a/packages/data-store-json/src/types.ts +++ b/packages/data-store-json/src/types.ts @@ -101,8 +101,8 @@ export interface VeramoJsonStore extends VeramoJsonCache { /** * A callback method that is called when the data stored in a {@link VeramoJsonCache} is updated. * - * @param oldState the snapshot of the cache before the update. - * @param newState the new cache object, after the update. This object may reference the underlying storage. + * @param oldState - The snapshot of the cache before the update. + * @param newState - The new cache object, after the update. This object may reference the underlying storage. * * @beta This API may change in future versions without a BREAKING CHANGE notice. */ diff --git a/packages/data-store/package.json b/packages/data-store/package.json index 18b569a4c..0ee508aaa 100644 --- a/packages/data-store/package.json +++ b/packages/data-store/package.json @@ -6,7 +6,7 @@ "types": "build/index.d.ts", "scripts": { "build": "tsc", - "generate-plugin-schema": "yarn veramo dev extract-api" + "extract-api": "yarn veramo dev extract-api" }, "dependencies": { "@veramo/core": "^3.1.4", diff --git a/packages/data-store/src/data-store-orm.ts b/packages/data-store/src/data-store-orm.ts index bb3f73bb6..75f3b6b31 100644 --- a/packages/data-store/src/data-store-orm.ts +++ b/packages/data-store/src/data-store-orm.ts @@ -38,6 +38,21 @@ import { SelectQueryBuilder, } from 'typeorm' +/** + * This class implements the {@link @veramo/core#IDataStoreORM} query interface using a TypeORM compatible database. + * + * This allows you to filter Verifiable Credentials, Presentations and Messages by some common properties that are + * parsed and stored in database tables. + * + * This class is designed to work with {@link @veramo/data-store#DataStore} which is the default way to populate the + * database with Credentials, Presentations and Messages in such a way that they can be queried by this class. + * These two classes MUST also share the same database connection. + * + * @see {@link @veramo/core#IDataStoreORM} + * @see {@link @veramo/core#IDataStore} + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export class DataStoreORM implements IAgentPlugin { readonly methods: IDataStoreORM readonly schema = schema.IDataStoreORM @@ -331,9 +346,7 @@ function addVerifierQuery(input: FindArgs, qb: SelectQueryBuilder): Se } function createWhereObject( - input: FindArgs< - TMessageColumns | TClaimsColumns | TCredentialColumns | TPresentationColumns | TIdentifiersColumns - >, + input: FindArgs, ): any { const where: Record = {} if (input?.where) { diff --git a/packages/data-store/src/data-store.ts b/packages/data-store/src/data-store.ts index fa04b9488..ff27a0b8e 100644 --- a/packages/data-store/src/data-store.ts +++ b/packages/data-store/src/data-store.ts @@ -19,6 +19,19 @@ import { Claim } from './entities/claim' import { Presentation, createPresentationEntity } from './entities/presentation' import { Connection } from 'typeorm' +/** + * This class implements the {@link @veramo/core#IDataStore} interface using a TypeORM compatible database. + * + * This allows you to store and retrieve Verifiable Credentials, Presentations and Messages by their IDs. + * + * For more complex queries you should use {@link @veramo/data-store#DataStoreORM} which is the default way to query + * the stored data by some common properties. These two classes MUST also share the same database connection. + * + * @see {@link @veramo/core#IDataStoreORM} + * @see {@link @veramo/core#IDataStore} + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export class DataStore implements IAgentPlugin { readonly methods: IDataStore readonly schema = schema.IDataStore diff --git a/packages/data-store/src/did-discovery-provider.ts b/packages/data-store/src/did-discovery-provider.ts index 6910c6ee2..9984d3e76 100644 --- a/packages/data-store/src/did-discovery-provider.ts +++ b/packages/data-store/src/did-discovery-provider.ts @@ -6,6 +6,16 @@ import { IDIDDiscoveryDiscoverDidArgs, } from '@veramo/did-discovery' +/** + * This implementation of {@link @veramo/did-discovery#AbstractDidDiscoveryProvider | AbstractDidDiscoveryProvider} + * helps you discover DIDs based on data that is stored by a local plugin that implements + * {@link @veramo/core#IDataStoreORM | IDataStoreORM}. + * + * DIDs can be discovered by partial matches of `name` from `Profile` credentials, by partial matches of `alias` of + * managed DIDs as well as partial matches of DIDs that are issuer or subject of credentials. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export class DataStoreDiscoveryProvider implements AbstractDidDiscoveryProvider { readonly name = 'data-store-discovery' @@ -31,7 +41,7 @@ export class DataStoreDiscoveryProvider implements AbstractDidDiscoveryProvider }, }) }) - + const credentialsByDID = await context.agent.dataStoreORMGetVerifiableCredentialsByClaims({ where: [ { column: 'type', value: ['name'] }, @@ -39,7 +49,7 @@ export class DataStoreDiscoveryProvider implements AbstractDidDiscoveryProvider { column: 'credentialType', value: ['VerifiableCredential,Profile'] }, ], }) - + credentialsByDID.forEach((vc) => { matches.push({ did: vc.verifiableCredential.credentialSubject.id as string, @@ -51,7 +61,7 @@ export class DataStoreDiscoveryProvider implements AbstractDidDiscoveryProvider const identifiersByDID = await context.agent.dataStoreORMGetIdentifiers({ where: [ - { column: 'did', value: [`%${args.query}%`], op: 'Like'} + { column: 'did', value: [`%${args.query}%`], op: 'Like' } ] }) @@ -66,7 +76,7 @@ export class DataStoreDiscoveryProvider implements AbstractDidDiscoveryProvider const identifiersByAlias = await context.agent.dataStoreORMGetIdentifiers({ where: [ - { column: 'alias', value: [`%${args.query}%`], op: 'Like'} + { column: 'alias', value: [`%${args.query}%`], op: 'Like' } ] }) diff --git a/packages/data-store/src/entities/PreMigrationEntities.ts b/packages/data-store/src/entities/PreMigrationEntities.ts index 19ec6fb85..322991a9c 100644 --- a/packages/data-store/src/entities/PreMigrationEntities.ts +++ b/packages/data-store/src/entities/PreMigrationEntities.ts @@ -1,14 +1,21 @@ import { BaseEntity, Column, Entity, PrimaryColumn } from 'typeorm' import { KeyType } from "./key"; +/** + * This represents the private key data of keys that were stored by {@link @veramo/data-store#KeyStore} before Veramo + * 3.0. During database migration this key material is moved to a different table and accessible by + * {@link @veramo/data-store#PrivateKeyStore}. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('key') export class PreMigrationKey extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore kid: string @Column() - //@ts-ignore + //@ts-ignore type: KeyType @Column({ nullable: true }) diff --git a/packages/data-store/src/entities/claim.ts b/packages/data-store/src/entities/claim.ts index 46eb0d989..b0f8133c1 100644 --- a/packages/data-store/src/entities/claim.ts +++ b/packages/data-store/src/entities/claim.ts @@ -2,17 +2,26 @@ import { Entity, Column, BaseEntity, ManyToOne, PrimaryColumn } from 'typeorm' import { Identifier } from './identifier' import { Credential } from './credential' +/** + * Represents the properties of a claim extracted from a Verifiable Credential `credentialSubject`, and stored in a + * TypeORM database for querying. + * + * @see {@link @veramo/core#IDataStoreORM} for the interface defining how this can be queried. + * @see {@link @veramo/data-store#DataStoreORM} for the implementation of the query interface. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('claim') export class Claim extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore hash: string @ManyToOne((type) => Identifier, (identifier) => identifier.issuedClaims, { eager: true, onDelete: 'CASCADE', }) - //@ts-ignore + //@ts-ignore issuer: Identifier @ManyToOne((type) => Identifier, (identifier) => identifier.receivedClaims, { @@ -24,33 +33,33 @@ export class Claim extends BaseEntity { @ManyToOne((type) => Credential, (credential) => credential.claims, { onDelete: 'CASCADE', }) - //@ts-ignore + //@ts-ignore credential: Credential @Column() - //@ts-ignore + //@ts-ignore issuanceDate: Date @Column({ nullable: true }) expirationDate?: Date @Column('simple-array') - //@ts-ignore + //@ts-ignore context: string[] @Column('simple-array') - //@ts-ignore + //@ts-ignore credentialType: string[] @Column() - //@ts-ignore + //@ts-ignore type: string @Column('text', { nullable: true }) - //@ts-ignore + //@ts-ignore value: string | null @Column() - //@ts-ignore + //@ts-ignore isObj: boolean } diff --git a/packages/data-store/src/entities/credential.ts b/packages/data-store/src/entities/credential.ts index 12c7eb5e0..858d7a5e1 100644 --- a/packages/data-store/src/entities/credential.ts +++ b/packages/data-store/src/entities/credential.ts @@ -6,10 +6,22 @@ import { Presentation } from './presentation' import { Claim } from './claim' import { asArray, computeEntryHash, extractIssuer } from '@veramo/utils' +/** + * Represents some common properties of a Verifiable Credential that are stored in a TypeORM database for querying. + * + * @see {@link @veramo/core#IDataStoreORM.dataStoreORMGetVerifiableCredentials | dataStoreORMGetVerifiableCredentials} + * for the interface defining how this can be queried. + * + * @see {@link @veramo/data-store#DataStoreORM | DataStoreORM} for the implementation of the query interface. + * + * @see {@link @veramo/core#IDataStoreORM.dataStoreORMGetVerifiableCredentialsByClaims | dataStoreORMGetVerifiableCredentialsByClaims} for the interface defining how to query credentials by the claims they contain. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('credential') export class Credential extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore hash: string //@ts-ignore @@ -30,7 +42,7 @@ export class Credential extends BaseEntity { eager: true, onDelete: 'CASCADE', }) - //@ts-ignore + //@ts-ignore issuer: Identifier // Subject can be null https://w3c.github.io/vc-data-model/#credential-uniquely-identifies-a-subject @@ -45,32 +57,32 @@ export class Credential extends BaseEntity { id?: string @Column() - //@ts-ignore + //@ts-ignore issuanceDate: Date @Column({ nullable: true }) expirationDate?: Date @Column('simple-array') - //@ts-ignore + //@ts-ignore context: string[] @Column('simple-array') - //@ts-ignore + //@ts-ignore type: string[] @OneToMany((type) => Claim, (claim) => claim.credential, { cascade: ['insert'], }) - //@ts-ignore + //@ts-ignore claims: Claim[] @ManyToMany((type) => Presentation, (presentation) => presentation.credentials) - //@ts-ignore + //@ts-ignore presentations: Presentation[] @ManyToMany((type) => Message, (message) => message.credentials) - //@ts-ignore + //@ts-ignore messages: Message[] } diff --git a/packages/data-store/src/entities/identifier.ts b/packages/data-store/src/entities/identifier.ts index 3b71245c7..7dcdf2914 100644 --- a/packages/data-store/src/entities/identifier.ts +++ b/packages/data-store/src/entities/identifier.ts @@ -17,19 +17,29 @@ import { Presentation } from './presentation' import { Credential } from './credential' import { Claim } from './claim' +/** + * Represents some properties and relationships of an {@link @veramo/core#IIdentifier} that are stored in a TypeORM + * database for the purpose of keeping track of keys and services associated with a DID managed by a Veramo agent. + * + * @see {@link @veramo/data-store#DIDStore | DIDStore} for the implementation used by the + * {@link @veramo/did-manager#DIDManager | DIDManager}. + * @see {@link @veramo/data-store#DataStoreORM | DataStoreORM} for the implementation of the query interface. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('identifier') @Index(['alias', 'provider'], { unique: true }) export class Identifier extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore did: string @Column({ nullable: true }) - //@ts-ignore + //@ts-ignore provider?: string @Column({ nullable: true }) - //@ts-ignore + //@ts-ignore alias?: string @BeforeInsert() @@ -44,65 +54,70 @@ export class Identifier extends BaseEntity { } @Column({ select: false }) - //@ts-ignore + //@ts-ignore saveDate: Date @Column({ select: false }) - //@ts-ignore + //@ts-ignore updateDate: Date @Column({ nullable: true }) - //@ts-ignore + //@ts-ignore controllerKeyId?: string @OneToMany((type) => Key, (key) => key.identifier) - //@ts-ignore + //@ts-ignore keys: Key[] @OneToMany((type) => Service, (service) => service.identifier, { cascade: true, }) - //@ts-ignore + //@ts-ignore services: Service[] @OneToMany((type) => Message, (message) => message.from) - //@ts-ignore + //@ts-ignore sentMessages: Message[] @OneToMany((type) => Message, (message) => message.to) - //@ts-ignore + //@ts-ignore receivedMessages: Message[] @OneToMany((type) => Presentation, (presentation) => presentation.holder) - //@ts-ignore + //@ts-ignore issuedPresentations: Presentation[] @ManyToMany((type) => Presentation, (presentation) => presentation.verifier) - //@ts-ignore + //@ts-ignore receivedPresentations: Presentation[] @OneToMany((type) => Credential, (credential) => credential.issuer) - //@ts-ignore + //@ts-ignore issuedCredentials: Credential[] @OneToMany((type) => Credential, (credential) => credential.subject) - //@ts-ignore + //@ts-ignore receivedCredentials: Credential[] @OneToMany((type) => Claim, (claim) => claim.issuer) - //@ts-ignore + //@ts-ignore issuedClaims: Claim[] @OneToMany((type) => Claim, (claim) => claim.subject) - //@ts-ignore + //@ts-ignore receivedClaims: Claim[] /** - * Convenience method + * Convenience method to get the most recent information about a subject DID as described by Verifiable Credential + * claims. * + * Example: + * ```typescript + * // get the latest claim value for credentials containing `credentialSubject.name` and this Identifier as subject. * const name = await identifier.getLatestClaimValue({type: 'name'}) + * ``` * - * @param where + * @param where - The TypeORM `where` filter to use. */ async getLatestClaimValue( dbConnection: Promise, diff --git a/packages/data-store/src/entities/key.ts b/packages/data-store/src/entities/key.ts index ea794e6bb..98cc13f41 100644 --- a/packages/data-store/src/entities/key.ts +++ b/packages/data-store/src/entities/key.ts @@ -2,24 +2,39 @@ import { KeyMetadata, TKeyType } from '@veramo/core' import { Entity, Column, PrimaryColumn, BaseEntity, ManyToOne } from 'typeorm' import { Identifier } from './identifier' +/** + * Mirrors {@link @veramo/core#TKeyType | TKeyType} + * + * @beta - This API may change without a BREAKING CHANGE notice. + */ export type KeyType = TKeyType +/** + * Represents some properties of a {@link @veramo/core#IKey | IKey} that are stored in a TypeORM + * database for the purpose of keeping track of the {@link @veramo/key-manager#AbstractKeyManagementSystem} + * implementations and the keys they are able to use. + * + * @see {@link @veramo/data-store#KeyStore | KeyStore} for the implementation used by the + * {@link @veramo/key-manager#KeyManager | KeyManager}. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('key') export class Key extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore kid: string @Column() - //@ts-ignore + //@ts-ignore kms: string @Column() - //@ts-ignore + //@ts-ignore type: KeyType @Column() - //@ts-ignore + //@ts-ignore publicKeyHex: string @Column({ @@ -37,6 +52,6 @@ export class Key extends BaseEntity { meta?: KeyMetadata | null @ManyToOne((type) => Identifier, (identifier) => identifier?.keys, { onDelete: 'CASCADE' }) - //@ts-ignore + //@ts-ignore identifier?: Identifier } diff --git a/packages/data-store/src/entities/message.ts b/packages/data-store/src/entities/message.ts index 9ba8bb4fd..cc9879414 100644 --- a/packages/data-store/src/entities/message.ts +++ b/packages/data-store/src/entities/message.ts @@ -16,11 +16,31 @@ import { createCredentialEntity, Credential } from './credential' import { computeEntryHash } from '@veramo/utils' import { v4 as uuidv4 } from 'uuid' +/** + * Represents message metadata as it is stored by {@link @veramo/data-store#DataStore | DataStore}. + * + * This metadata is most often used by {@link @veramo/message-handler#MessageHandler | MessageHandler} and + * {@link @veramo/core#IMessageHandler | IMessageHandler} implementations to decorate messages that are interpreted and + * decoded, but not returned as final, as they pass through the message handler chain. + * + * @beta - This API may change without a BREAKING CHANGE notice. + */ export interface MetaData { type: string value?: string } +/** + * Represents some common properties of an {@link @veramo/core#IMessage} that are stored in a TypeORM database for + * querying. + * + * @see {@link @veramo/core#IDataStoreORM.dataStoreORMGetMessages | dataStoreORMGetMessages} + * for the interface defining how this can be queried + * + * @see {@link @veramo/data-store#DataStoreORM | DataStoreORM} for the implementation of the query interface. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('message') export class Message extends BaseEntity { @BeforeInsert() @@ -31,7 +51,7 @@ export class Message extends BaseEntity { } @PrimaryColumn() - //@ts-ignore + //@ts-ignore id: string @BeforeInsert() @@ -46,11 +66,11 @@ export class Message extends BaseEntity { } @Column({ select: false }) - //@ts-ignore + //@ts-ignore saveDate: Date @Column({ select: false }) - //@ts-ignore + //@ts-ignore updateDate: Date @Column({ nullable: true }) @@ -63,7 +83,7 @@ export class Message extends BaseEntity { threadId?: string @Column() - //@ts-ignore + //@ts-ignore type: string @Column({ nullable: true }) @@ -103,12 +123,12 @@ export class Message extends BaseEntity { cascade: true, }) @JoinTable() - //@ts-ignore + //@ts-ignore presentations: Presentation[] @ManyToMany((type) => Credential, (credential) => credential.messages, { cascade: true }) @JoinTable() - //@ts-ignore + //@ts-ignore credentials: Credential[] } diff --git a/packages/data-store/src/entities/presentation.ts b/packages/data-store/src/entities/presentation.ts index 090716ef3..ea0f3df4c 100644 --- a/packages/data-store/src/entities/presentation.ts +++ b/packages/data-store/src/entities/presentation.ts @@ -7,10 +7,19 @@ import { createCredentialEntity, Credential } from './credential' import { asArray, computeEntryHash } from '@veramo/utils' import { normalizeCredential } from 'did-jwt-vc' +/** + * Represents some common properties of a Verifiable Presentation that are stored in a TypeORM database for querying. + * + * @see {@link @veramo/core#IDataStoreORM.dataStoreORMGetVerifiablePresentations | dataStoreORMGetVerifiablePresentations} for the interface defining how this can be queried. + * + * @see {@link @veramo/data-store#DataStoreORM | DataStoreORM} for the implementation of the query interface. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('presentation') export class Presentation extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore hash: string //@ts-ignore @@ -31,7 +40,7 @@ export class Presentation extends BaseEntity { eager: true, onDelete: 'CASCADE', }) - //@ts-ignore + //@ts-ignore holder: Identifier @ManyToMany((type) => Identifier, (identifier) => identifier?.receivedPresentations, { @@ -40,36 +49,36 @@ export class Presentation extends BaseEntity { nullable: true, }) @JoinTable() - //@ts-ignore + //@ts-ignore verifier?: Identifier[] @Column({ nullable: true }) id?: String @Column() - //@ts-ignore + //@ts-ignore issuanceDate: Date @Column({ nullable: true }) expirationDate?: Date @Column('simple-array') - //@ts-ignore + //@ts-ignore context: string[] @Column('simple-array') - //@ts-ignore + //@ts-ignore type: string[] @ManyToMany((type) => Credential, (credential) => credential.presentations, { cascade: true, }) @JoinTable() - //@ts-ignore + //@ts-ignore credentials: Credential[] @ManyToMany((type) => Message, (message) => message.presentations) - //@ts-ignore + //@ts-ignore messages: Message[] } diff --git a/packages/data-store/src/entities/private-key.ts b/packages/data-store/src/entities/private-key.ts index 5cb1d2716..836478e06 100644 --- a/packages/data-store/src/entities/private-key.ts +++ b/packages/data-store/src/entities/private-key.ts @@ -1,19 +1,27 @@ -import { TKeyType } from '@veramo/core' +import { KeyType } from './key' import { Entity, Column, PrimaryColumn, BaseEntity } from 'typeorm' -export type KeyType = TKeyType - +/** + * Represents some properties of a {@link @veramo/key-manager#ManagedPrivateKey | ManagedPrivateKey} that are stored in + * a TypeORM database when using a {@link @veramo/data-store#PrivateKeyStore | PrivateKeyStore} to store private key + * data. + * + * @see {@link @veramo/kms-local#KeyManagementSystem | KeyManagementSystem} for an implementation of a KMS that can + * make use of such stored keys. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('private-key') export class PrivateKey extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore alias: string @Column() - //@ts-ignore + //@ts-ignore type: KeyType @Column() - //@ts-ignore + //@ts-ignore privateKeyHex: string } diff --git a/packages/data-store/src/entities/service.ts b/packages/data-store/src/entities/service.ts index 603cf880e..5cfb9e7c5 100644 --- a/packages/data-store/src/entities/service.ts +++ b/packages/data-store/src/entities/service.ts @@ -1,24 +1,32 @@ import { Entity, Column, PrimaryColumn, BaseEntity, ManyToOne } from 'typeorm' import { Identifier } from './identifier' +/** + * Represents some properties of a {@link did-resolver#ServiceEndpoint | ServiceEndpoint} as it is stored in a TypeORM + * database. This is used by {@link @veramo/data-store#DIDStore | DIDStore} to provide information to + * {@link @veramo/did-manager#DIDManager | DIDManager} when DID management information is stored in a local TypeORM + * database. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ @Entity('service') export class Service extends BaseEntity { @PrimaryColumn() - //@ts-ignore + //@ts-ignore id: string @Column() - //@ts-ignore + //@ts-ignore type: string @Column() - //@ts-ignore + //@ts-ignore serviceEndpoint: string @Column({ nullable: true }) description?: string @ManyToOne((type) => Identifier, (identifier) => identifier?.services, { onDelete: 'CASCADE' }) - //@ts-ignore + //@ts-ignore identifier?: Identifier } diff --git a/packages/data-store/src/identifier/did-store.ts b/packages/data-store/src/identifier/did-store.ts index a1ca7d503..bbb50aad1 100644 --- a/packages/data-store/src/identifier/did-store.ts +++ b/packages/data-store/src/identifier/did-store.ts @@ -8,18 +8,31 @@ import { Connection, In, IsNull, Not } from 'typeorm' import Debug from 'debug' import { Presentation } from '../entities/presentation' + const debug = Debug('veramo:typeorm:identifier-store') +/** + * An implementation of {@link @veramo/did-manager#AbstractDIDStore | AbstractDIDStore} that uses a TypeORM database to + * store the relationships between DIDs, their providers and controllers and their keys and services as they are known + * and managed by a Veramo agent. + * + * An instance of this class can be used by {@link @veramo/did-manager#DIDManager} as the data storage layer. + * + * To make full use of this class, it should use the same database as the one used by + * {@link @veramo/data-store#KeyStore | KeyStore}. + * + * @public + */ export class DIDStore extends AbstractDIDStore { constructor(private dbConnection: Promise) { super() } async get({ - did, - alias, - provider, - }: { + did, + alias, + provider, + }: { did: string alias: string provider: string diff --git a/packages/data-store/src/identifier/key-store.ts b/packages/data-store/src/identifier/key-store.ts index bb7e9575b..a3c7a4b8d 100644 --- a/packages/data-store/src/identifier/key-store.ts +++ b/packages/data-store/src/identifier/key-store.ts @@ -7,6 +7,19 @@ import { Key } from '../entities/key' import Debug from 'debug' const debug = Debug('veramo:typeorm:key-store') +/** + * An implementation of {@link @veramo/key-manager#AbstractKeyStore | AbstractKeyStore} that uses a TypeORM database to + * store the relationships between keys, their IDs, aliases and + * {@link @veramo/key-manager#AbstractKeyManagementSystem | KMS implementations}, as they are known and managed by a + * Veramo agent. + * + * An instance of this class can be used by {@link @veramo/key-manager#KeyManager} as the data storage layer. + * + * To make full use of this class, it should use the same database as the one used by + * {@link @veramo/data-store#DIDStore | DIDStore}. + * + * @public + */ export class KeyStore extends AbstractKeyStore { constructor(private dbConnection: Promise) { super() diff --git a/packages/data-store/src/identifier/private-key-store.ts b/packages/data-store/src/identifier/private-key-store.ts index ead7feb35..dcf9c428a 100644 --- a/packages/data-store/src/identifier/private-key-store.ts +++ b/packages/data-store/src/identifier/private-key-store.ts @@ -1,11 +1,21 @@ import { AbstractSecretBox, AbstractPrivateKeyStore } from '@veramo/key-manager' import { Connection } from 'typeorm' -import { ImportablePrivateKey, ManagedPrivateKey } from '@veramo/key-manager/src/abstract-private-key-store' +import { ImportablePrivateKey, ManagedPrivateKey } from '@veramo/key-manager' import { PrivateKey } from '../entities/private-key' import { v4 as uuid4 } from 'uuid' import Debug from 'debug' + const debug = Debug('veramo:typeorm:key-store') +/** + * An implementation of {@link @veramo/key-manager#bstractPrivateKeyStore | AbstractPrivateKeyStore} that uses a + * TypeORM database connection to store private key material. + * + * The keys can be encrypted while at rest if this class is initialized with an + * {@link @veramo/key-manager#AbstractSecretBox | AbstractSecretBox} implementation. + * + * @public + */ export class PrivateKeyStore extends AbstractPrivateKeyStore { constructor(private dbConnection: Promise, private secretBox?: AbstractSecretBox) { super() diff --git a/packages/data-store/src/index.ts b/packages/data-store/src/index.ts index 8b0976854..9500e8780 100644 --- a/packages/data-store/src/index.ts +++ b/packages/data-store/src/index.ts @@ -24,6 +24,14 @@ import { Service } from './entities/service' import { Message, MetaData } from './entities/message' import { PrivateKey } from './entities/private-key' import { PreMigrationKey } from './entities/PreMigrationEntities' + +/** + * The TypeORM entities used by this package. + * + * This array SHOULD be used when creating a TypeORM connection. + * + * @public + */ export const Entities = [ Key, Identifier, diff --git a/packages/data-store/src/migrations/1.createDatabase.ts b/packages/data-store/src/migrations/1.createDatabase.ts index 8005ed84a..b9c76c000 100644 --- a/packages/data-store/src/migrations/1.createDatabase.ts +++ b/packages/data-store/src/migrations/1.createDatabase.ts @@ -4,6 +4,8 @@ const debug = Debug('veramo:data-store:initial-migration') /** * Create the database layout for Veramo 3.0 + * + * @public */ export class CreateDatabase1447159020001 implements MigrationInterface { async up(queryRunner: QueryRunner): Promise { diff --git a/packages/data-store/src/migrations/2.simplifyRelations.ts b/packages/data-store/src/migrations/2.simplifyRelations.ts index 11d2ff54b..e85857e44 100644 --- a/packages/data-store/src/migrations/2.simplifyRelations.ts +++ b/packages/data-store/src/migrations/2.simplifyRelations.ts @@ -3,7 +3,9 @@ import Debug from 'debug' const debug = Debug('veramo:data-store:initial-migration') /** - * Fix inconsistencies between Entity data and column data + * Fix inconsistencies between Entity data and column data. + * + * @public */ export class SimplifyRelations1447159020002 implements MigrationInterface { async up(queryRunner: QueryRunner): Promise { diff --git a/packages/data-store/src/migrations/3.createPrivateKeyStorage.ts b/packages/data-store/src/migrations/3.createPrivateKeyStorage.ts index 0186a64c2..db55600ed 100644 --- a/packages/data-store/src/migrations/3.createPrivateKeyStorage.ts +++ b/packages/data-store/src/migrations/3.createPrivateKeyStorage.ts @@ -6,6 +6,8 @@ const debug = Debug('veramo:data-store:migrate-private-keys') /** * Migration of existing private keys from Veramo 2.x to Veramo 3.x + * + * @public */ export class CreatePrivateKeyStorage1629293428674 implements MigrationInterface { async up(queryRunner: QueryRunner): Promise { diff --git a/packages/data-store/src/migrations/4.allowNullVPIssuanceDate.ts b/packages/data-store/src/migrations/4.allowNullVPIssuanceDate.ts index 2ca1c4fad..b0b5962e5 100644 --- a/packages/data-store/src/migrations/4.allowNullVPIssuanceDate.ts +++ b/packages/data-store/src/migrations/4.allowNullVPIssuanceDate.ts @@ -5,7 +5,9 @@ import Debug from 'debug' const debug = Debug('veramo:data-store:migrate-presentation-issuance-date') /** - * Reduce issuanceDate constraint of Presentations + * Reduce issuanceDate constraint of Presentations. + * + * @public */ export class AllowNullIssuanceDateForPresentations1637237492913 implements MigrationInterface { private getTableName(givenName: string, queryRunner: QueryRunner): string { diff --git a/packages/data-store/src/migrations/index.ts b/packages/data-store/src/migrations/index.ts index ea7bdc84c..7196abc36 100644 --- a/packages/data-store/src/migrations/index.ts +++ b/packages/data-store/src/migrations/index.ts @@ -3,6 +3,13 @@ import { SimplifyRelations1447159020002 } from './2.simplifyRelations' import { CreatePrivateKeyStorage1629293428674 } from './3.createPrivateKeyStorage' import { AllowNullIssuanceDateForPresentations1637237492913 } from './4.allowNullVPIssuanceDate' +/** + * The migrations array that SHOULD be used when initializing a TypeORM database connection. + * + * These ensure the correct creation of tables and the proper migrations of data when tables change between versions. + * + * @public + */ export const migrations = [ CreateDatabase1447159020001, SimplifyRelations1447159020002, diff --git a/packages/did-comm/plugin.schema.json b/packages/did-comm/plugin.schema.json index 4206354b4..284aa46bc 100644 --- a/packages/did-comm/plugin.schema.json +++ b/packages/did-comm/plugin.schema.json @@ -21,7 +21,7 @@ "application/didcomm-signed+json", "application/didcomm-encrypted+json" ], - "description": "Represents different DIDComm v2 message encapsulation" + "description": "Represents different DIDComm v2 message encapsulation." }, "IPackDIDCommMessageArgs": { "type": "object", @@ -107,9 +107,11 @@ "type": "array", "items": { "type": "string" - } + }, + "description": "Add extra recipients for the packed message." } - } + }, + "description": "Extra options when packing a DIDComm message." }, "ISendDIDCommMessageArgs": { "type": "object", @@ -404,6 +406,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "VerifiablePresentation": { @@ -503,7 +509,7 @@ "metaData", "message" ], - "description": "The result of unpacking a DIDComm v2 message" + "description": "The result of unpacking a DIDComm v2 message." }, "IDIDCommMessageMetaData": { "type": "object", @@ -515,7 +521,7 @@ "required": [ "packing" ], - "description": "Metadata resulting from unpacking a DIDComm v2 message" + "description": "Metadata resulting from unpacking a DIDComm v2 message." } }, "methods": { diff --git a/packages/did-comm/src/didcomm.ts b/packages/did-comm/src/didcomm.ts index d566dc0bb..1d3e1d7ed 100644 --- a/packages/did-comm/src/didcomm.ts +++ b/packages/did-comm/src/didcomm.ts @@ -62,12 +62,14 @@ import { _FlattenedJWS, _GenericJWS, } from './types/utility-types' + const debug = Debug('veramo:did-comm:action-handler') /** * @deprecated Please use {@link IDIDComm.sendDIDCommMessage} instead. This will be removed in Veramo 4.0. * Input arguments for {@link IDIDComm.sendMessageDIDCommAlpha1} - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ISendMessageDIDCommAlpha1Args { url?: string @@ -86,14 +88,16 @@ export interface ISendMessageDIDCommAlpha1Args { /** * The input to the {@link DIDComm.unpackDIDCommMessage} method. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export type IUnpackDIDCommMessageArgs = IPackedDIDCommMessage /** * The input to the {@link DIDComm.packDIDCommMessage} method. * When `packing` is `authcrypt` or `jws`, a `keyRef` MUST be provided. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IPackDIDCommMessageArgs { message: IDIDCommMessage @@ -106,7 +110,8 @@ export interface IPackDIDCommMessageArgs { * The input to the {@link DIDComm.sendDIDCommMessage} method. * The provided `messageId` will be used in the emitted * event to allow event/message correlation. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ISendDIDCommMessageArgs { packedMessage: IPackedDIDCommMessage @@ -118,11 +123,12 @@ export interface ISendDIDCommMessageArgs { /** * DID Comm plugin for {@link @veramo/core#Agent} * - * This plugin provides a method of creating an encrypted message according to the initial {@link https://github.com/decentralized-identifier/DIDComm-js | DIDComm-js} implementation. + * This plugin provides a method of creating an encrypted message according to the initial + * {@link https://github.com/decentralized-identifier/DIDComm-js | DIDComm-js} implementation. * * @remarks Be advised that this spec is still not final and that this protocol may need to change. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export class DIDComm implements IAgentPlugin { readonly transports: IDIDCommTransport[] @@ -133,7 +139,8 @@ export class DIDComm implements IAgentPlugin { /** * Constructor that takes a list of {@link IDIDCommTransport} objects. - * @param transports A list of {@link IDIDCommTransport} objects. + * @param transports - A list of {@link IDIDCommTransport} objects. Defaults to + * {@link @veramo/did-comm#DIDCommHttpTransport | DIDCommHttpTransport} */ constructor(transports: IDIDCommTransport[] = [new DIDCommHttpTransport()]) { this.transports = transports @@ -277,6 +284,7 @@ export class DIDComm implements IAgentPlugin { kid: string publicKeyBytes: Uint8Array } + let recipients: IRecipient[] = [] async function computeRecipients(to: string): Promise { @@ -591,7 +599,8 @@ export class DIDComm implements IAgentPlugin { }) debug('Encrypted:', postPayload) - } catch (e) {} + } catch (e) { + } debug('Sending to %s', serviceEndpoint) const res = await fetch(serviceEndpoint, { diff --git a/packages/did-comm/src/index.ts b/packages/did-comm/src/index.ts index 009f8bbed..a5ce79c92 100644 --- a/packages/did-comm/src/index.ts +++ b/packages/did-comm/src/index.ts @@ -18,7 +18,7 @@ export * from './types/IDIDComm' export { DIDCommMessageHandler } from './message-handler' export * from './transports/transports' /** - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/did-comm/src/message-handler.ts b/packages/did-comm/src/message-handler.ts index a01761e39..fbc4857c0 100644 --- a/packages/did-comm/src/message-handler.ts +++ b/packages/did-comm/src/message-handler.ts @@ -8,7 +8,7 @@ type IContext = IAgentContext /** * A plugin for the {@link @veramo/message-handler#MessageHandler} that decrypts DIDComm messages. - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export class DIDCommMessageHandler extends AbstractMessageHandler { constructor() { diff --git a/packages/did-comm/src/transports/transports.ts b/packages/did-comm/src/transports/transports.ts index 321aff69d..a8057814c 100644 --- a/packages/did-comm/src/transports/transports.ts +++ b/packages/did-comm/src/transports/transports.ts @@ -4,7 +4,8 @@ import { v4 as uuidv4 } from 'uuid' /** * Result interface for sending DIDComm messages through * {@link IDIDCommTransport.send}. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDCommTransportResult { result?: string @@ -14,7 +15,8 @@ export interface IDIDCommTransportResult { /** * Common interface for transports that can be used in the * {@link DIDComm} module. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDCommTransport { /** @@ -26,8 +28,9 @@ export interface IDIDCommTransport { /** * Returns `true` if this transport is suitable for the provided * DID Document service section, otherwise `false`. - * @param service The DID Document service section - * @beta + * @param service - The DID Document service section + * + * @beta This API may change without a BREAKING CHANGE notice. */ isServiceSupported(service: any): boolean @@ -36,17 +39,19 @@ export interface IDIDCommTransport { * the service endpoint defined in the provided DID Document service * section. * - * @param service The DID Document service section that contains + * @param service - The DID Document service section that contains * a `serviceEndpoint` entry. - * @param message The message to be sent. - * @beta + * @param message - The message to be sent. + * + * @beta This API may change without a BREAKING CHANGE notice. */ send(service: any, message: string): Promise } /** * Abstract implementation of {@link IDIDCommTransport}. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export abstract class AbstractDIDCommTransport implements IDIDCommTransport { id: string @@ -54,8 +59,10 @@ export abstract class AbstractDIDCommTransport implements IDIDCommTransport { /** * Shared constructor that takes an optional identifier (for reusing) for * this {@link IDIDCommTransport}. - * @param id An optional identifier for this {@link IDIDCommTransport}. - * @beta + * + * @param id - An optional identifier for this {@link IDIDCommTransport}. + * + * @beta This API may change without a BREAKING CHANGE notice. */ constructor(id?: string) { this.id = id || uuidv4() @@ -71,7 +78,8 @@ export abstract class AbstractDIDCommTransport implements IDIDCommTransport { /** * Implementation of {@link IDIDCommTransport} to provide a simple * transport based on HTTP(S) requests. - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export class DIDCommHttpTransport extends AbstractDIDCommTransport { /** @@ -82,7 +90,7 @@ export class DIDCommHttpTransport extends AbstractDIDCommTransport { /** * Creates a new {@link DIDCommHttpTransport}. - * @param httpMethod Default HTTP method if not specified in the service + * @param httpMethod - Default HTTP method if not specified in the service * section. */ constructor(httpMethod?: 'post' | 'get') { diff --git a/packages/did-comm/src/types/IDIDComm.ts b/packages/did-comm/src/types/IDIDComm.ts index d835b764e..10744d04d 100644 --- a/packages/did-comm/src/types/IDIDComm.ts +++ b/packages/did-comm/src/types/IDIDComm.ts @@ -22,7 +22,8 @@ import { /** * DID Comm plugin interface for {@link @veramo/core#Agent} - * @beta + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDComm extends IPluginMethodMap { /** @@ -32,7 +33,7 @@ export interface IDIDComm extends IPluginMethodMap { * @returns the {@link DIDCommMessageMediaType} if it was successfully parsed * @throws if the message cannot be parsed as DIDComm v2 * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ getDIDCommMessageMediaType(args: IPackedDIDCommMessage): Promise @@ -52,7 +53,7 @@ export interface IDIDComm extends IPluginMethodMap { * * @returns a Promise that resolves to an object containing the serialized packed `message` string * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ packDIDCommMessage( args: IPackDIDCommMessageArgs, @@ -71,7 +72,7 @@ export interface IDIDComm extends IPluginMethodMap { * @returns a Promise that resolves to an object containing * the {@link IDIDCommMessage} and {@link DIDCommMessagePacking} used. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ unpackDIDCommMessage( args: IUnpackDIDCommMessageArgs, @@ -94,13 +95,13 @@ export interface IDIDComm extends IPluginMethodMap { * @returns The transport id that was used to send the message. It throws an error in case something * went wrong. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ sendDIDCommMessage(args: ISendDIDCommMessageArgs, context: IAgentContext): Promise /** * - * @deprecated Please use {@link sendDIDCommMessage} instead. This will be removed in Veramo 4.0 + * @deprecated Please use {@link IDIDComm.sendDIDCommMessage} instead. This will be removed in Veramo 4.0 * * This is used to create a message according to the initial {@link https://github.com/decentralized-identifier/DIDComm-js | DIDComm-js} implementation. * @@ -109,7 +110,7 @@ export interface IDIDComm extends IPluginMethodMap { * @param args - Arguments necessary for sending a DIDComm message * @param context - This reserved param is automatically added and handled by the framework, *do not override* * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ sendMessageDIDCommAlpha1( args: ISendMessageDIDCommAlpha1Args, diff --git a/packages/did-comm/src/types/message-types.ts b/packages/did-comm/src/types/message-types.ts index 915a3db05..81d8ef645 100644 --- a/packages/did-comm/src/types/message-types.ts +++ b/packages/did-comm/src/types/message-types.ts @@ -2,7 +2,7 @@ * The DIDComm message structure. * See https://identity.foundation/didcomm-messaging/spec/#plaintext-message-structure * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDCommMessage { type: string @@ -17,14 +17,23 @@ export interface IDIDCommMessage { from_prior?: string body: any } + +/** + * Extra options when packing a DIDComm message. + * + * @beta - This API may change without a BREAKING CHANGE notice. + */ export interface IDIDCommOptions { + /** + * Add extra recipients for the packed message. + */ bcc?: string[] } /** - * Represents different DIDComm v2 message encapsulation + * Represents different DIDComm v2 message encapsulation. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export enum DIDCommMessageMediaType { /** @@ -53,7 +62,7 @@ export enum DIDCommMessageMediaType { * `none` will produce `DIDCommMessageMediaType.PLAIN` messages. * * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export type DIDCommMessagePacking = | 'authcrypt' @@ -64,9 +73,9 @@ export type DIDCommMessagePacking = | 'anoncrypt+jws' /** - * Metadata resulting from unpacking a DIDComm v2 message + * Metadata resulting from unpacking a DIDComm v2 message. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDCommMessageMetaData { packing: DIDCommMessagePacking @@ -74,9 +83,9 @@ export interface IDIDCommMessageMetaData { } /** - * The result of unpacking a DIDComm v2 message + * The result of unpacking a DIDComm v2 message. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IUnpackedDIDCommMessage { metaData: IDIDCommMessageMetaData @@ -87,7 +96,7 @@ export interface IUnpackedDIDCommMessage { * The result of packing a DIDComm v2 message. * The message is always serialized as string. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IPackedDIDCommMessage { message: string diff --git a/packages/did-discovery/plugin.schema.json b/packages/did-discovery/plugin.schema.json index 11101f5bc..abc8aadcd 100644 --- a/packages/did-discovery/plugin.schema.json +++ b/packages/did-discovery/plugin.schema.json @@ -17,7 +17,7 @@ "required": [ "query" ], - "description": "Contains the parameters of a DID Discovery Request" + "description": "Contains the parameters of a DID Discovery Request." }, "IDIDDiscoveryDiscoverDidResult": { "type": "object", @@ -48,7 +48,7 @@ "required": [ "results" ], - "description": "DID Discovery results" + "description": "DID Discovery results." }, "IDIDDiscoveryProviderResult": { "type": "object", @@ -69,7 +69,7 @@ "provider", "matches" ], - "description": "Discovery results from one provider" + "description": "Discovery results from one provider." }, "IDIDDiscoverMatch": { "type": "object", @@ -87,7 +87,7 @@ "did", "metaData" ], - "description": "A single discovery match" + "description": "A single discovery match." } }, "methods": { diff --git a/packages/did-discovery/src/action-handler.ts b/packages/did-discovery/src/action-handler.ts index ed1630bf6..a6553b9c6 100644 --- a/packages/did-discovery/src/action-handler.ts +++ b/packages/did-discovery/src/action-handler.ts @@ -13,6 +13,8 @@ const debug = Debug('veramo:did-discovery') /** * This class adds support for discovering DIDs. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export class DIDDiscovery implements IAgentPlugin { readonly methods: IDIDDiscovery diff --git a/packages/did-discovery/src/index.ts b/packages/did-discovery/src/index.ts index 2e544cff7..e1c47f125 100644 --- a/packages/did-discovery/src/index.ts +++ b/packages/did-discovery/src/index.ts @@ -6,5 +6,11 @@ export { DIDDiscovery } from './action-handler' export { AbstractDidDiscoveryProvider } from './abstract-did-discovery-provider' export * from './types' + +/** + * The parameter and return type schemas for the methods of the {@link @veramo/did-discovery#DIDDiscovery} plugin. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/did-discovery/src/types.ts b/packages/did-discovery/src/types.ts index 6740f8f26..6a34b8516 100644 --- a/packages/did-discovery/src/types.ts +++ b/packages/did-discovery/src/types.ts @@ -1,7 +1,9 @@ import { IAgentContext, IPluginMethodMap } from '@veramo/core' /** - * Contains the parameters of a DID Discovery Request + * Contains the parameters of a DID Discovery Request. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDDiscoveryDiscoverDidArgs { /** @@ -16,7 +18,9 @@ export interface IDIDDiscoveryDiscoverDidArgs { } /** - * A single discovery match + * A single discovery match. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDDiscoverMatch { /** @@ -31,7 +35,9 @@ export interface IDIDDiscoverMatch { } /** - * Discovery results from one provider + * Discovery results from one provider. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDDiscoveryProviderResult { /** @@ -46,7 +52,9 @@ export interface IDIDDiscoveryProviderResult { } /** - * DID Discovery results + * DID Discovery results. + * + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IDIDDiscoveryDiscoverDidResult extends Partial { /** @@ -61,7 +69,9 @@ export interface IDIDDiscoveryDiscoverDidResult extends Partial = {} diff --git a/packages/did-provider-key/src/key-did-provider.ts b/packages/did-provider-key/src/key-did-provider.ts index a5dabdd21..7894dfe34 100644 --- a/packages/did-provider-key/src/key-did-provider.ts +++ b/packages/did-provider-key/src/key-did-provider.ts @@ -11,7 +11,7 @@ type IContext = IAgentContext /** * {@link @veramo/did-manager#DIDManager} identifier provider for `did:key` identifiers * - * @alpha + * @beta This API may change without a BREAKING CHANGE notice. */ export class KeyDIDProvider extends AbstractIdentifierProvider { private defaultKms: string diff --git a/packages/did-provider-key/src/resolver.ts b/packages/did-provider-key/src/resolver.ts index f76846729..58adb049a 100644 --- a/packages/did-provider-key/src/resolver.ts +++ b/packages/did-provider-key/src/resolver.ts @@ -40,6 +40,11 @@ const resolveDidKey: DIDResolver = async ( } } +/** + * Provides a mapping to a did:key resolver, usable by {@link did-resolver#Resolver}. + * + * @public + */ export function getDidKeyResolver() { return { key: resolveDidKey } } diff --git a/packages/did-resolver/src/resolver.ts b/packages/did-resolver/src/resolver.ts index 84fe4db09..45fd3feab 100644 --- a/packages/did-resolver/src/resolver.ts +++ b/packages/did-resolver/src/resolver.ts @@ -8,14 +8,24 @@ import { parse as parseDID, Resolvable, } from 'did-resolver' + export { DIDDocument } import Debug from 'debug' + const debug = Debug('veramo:resolver') interface Options { resolver: Resolvable } +/** + * A Veramo Plugin that enables users to resolve DID documents. + * + * This plugin is used automatically by plugins that create or verify Verifiable Credentials or Presentations or when + * working with DIDComm + * + * @public + */ export class DIDResolverPlugin implements IAgentPlugin { readonly methods: IResolver readonly schema = schema.IResolver @@ -33,9 +43,9 @@ export class DIDResolverPlugin implements IAgentPlugin { /** {@inheritDoc @veramo/core#IResolver.resolveDid} */ async resolveDid({ - didUrl, - options, - }: { + didUrl, + options, + }: { didUrl: string options?: DIDResolutionOptions }): Promise { @@ -62,10 +72,10 @@ export class DIDResolverPlugin implements IAgentPlugin { /** {@inheritDoc @veramo/core#IResolver.getDIDComponentById} */ async getDIDComponentById({ - didDocument, - didUrl, - section, - }: { + didDocument, + didUrl, + section, + }: { didDocument: DIDDocument didUrl: string section?: DIDDocumentSection diff --git a/packages/did-resolver/src/universal-resolver.ts b/packages/did-resolver/src/universal-resolver.ts index 33227b17f..40c2c101e 100644 --- a/packages/did-resolver/src/universal-resolver.ts +++ b/packages/did-resolver/src/universal-resolver.ts @@ -7,6 +7,8 @@ interface Options { /** * @deprecated please use `getUniresolver(url)` or `getUniresolverFor(methods, url)` instead + * + * @internal */ export class UniversalResolver { constructor(options: Options) { @@ -27,8 +29,10 @@ export class UniversalResolver { * }) * ``` * - * @param url the URL for the universal resolver instance (See https://uniresolver.io ) + * @param url - the URL for the universal resolver instance (See https://uniresolver.io ) * @returns `DIDResolver` + * + * @public */ export function getUniversalResolver( url: string = 'https://dev.uniresolver.io/1.0/identifiers/', @@ -62,9 +66,11 @@ export function getUniversalResolver( * }) * ``` * - * @param methods an array of DID methods that should be resolved by this universal resolver - * @param url the URL for the universal resolver instance (See https://uniresolver.io ) + * @param methods - an array of DID methods that should be resolved by this universal resolver + * @param url - the URL for the universal resolver instance (See https://uniresolver.io ) * @returns `Record` a mapping of the given methods to an instance of `DIDResolver` + * + * @public */ export function getUniversalResolverFor( methods: string[], diff --git a/packages/key-manager/src/abstract-key-management-system.ts b/packages/key-manager/src/abstract-key-management-system.ts index a07a2bc99..ba36bc2e7 100644 --- a/packages/key-manager/src/abstract-key-management-system.ts +++ b/packages/key-manager/src/abstract-key-management-system.ts @@ -3,10 +3,18 @@ import { arrayify } from '@ethersproject/bytes' import { serialize } from '@ethersproject/transactions' import * as u8a from 'uint8arrays' +/** + * This base abstract class should be extended to provide cryptographic functions to other Veramo plugins. + * + * @public + */ export abstract class AbstractKeyManagementSystem { abstract importKey(args: Exclude): Promise + abstract listKeys(): Promise> + abstract createKey(args: { type: TKeyType; meta?: any }): Promise + abstract deleteKey(args: { kid: string }): Promise /**@deprecated please use `sign({key, alg: 'eth_signTransaction', data: arrayify(serialize(transaction))})` instead */ diff --git a/packages/key-manager/src/abstract-key-store.ts b/packages/key-manager/src/abstract-key-store.ts index a238f9fd7..57aed46a7 100644 --- a/packages/key-manager/src/abstract-key-store.ts +++ b/packages/key-manager/src/abstract-key-store.ts @@ -1,8 +1,20 @@ import { IKey, ManagedKeyInfo } from '@veramo/core' +/** + * This base abstract class should be extended to provide platform specific implementations that are usable by + * {@link @veramo/key-manager#KeyManager | KeyManager}. + * + * Implementations of this class are used to store mappings between key IDs and their respective + * {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem} implementations. + * + * @public + */ export abstract class AbstractKeyStore { abstract import(args: Partial): Promise + abstract get(args: { kid: string }): Promise + abstract delete(args: { kid: string }): Promise + abstract list(args: {}): Promise> } diff --git a/packages/key-manager/src/abstract-private-key-store.ts b/packages/key-manager/src/abstract-private-key-store.ts index 76603f0a6..bb6890d3e 100644 --- a/packages/key-manager/src/abstract-private-key-store.ts +++ b/packages/key-manager/src/abstract-private-key-store.ts @@ -1,16 +1,44 @@ -import { ManagedKeyInfo, RequireOnly, TKeyType } from '@veramo/core' +import { RequireOnly, TKeyType } from '@veramo/core' +/** + * Represents a private key. + * + * The `alias` is used to refer to the key material which is stored as the hex encoding of the raw byte array + * (`privateKeyHex`). + * + * The `type` refers to the type of key that is represented. + * + * @public + */ export interface ManagedPrivateKey { alias: string privateKeyHex: string type: TKeyType } +/** + * Represents private key data that can be imported. This is a subset of {@link ManagedPrivateKey}. + * + * The `alias` of the resulting {@link ManagedPrivateKey} can be generated automatically if none is provided. + * + * @public + */ export type ImportablePrivateKey = RequireOnly +/** + * This base abstract class should be extended to provide platform specific implementations that are usable by + * {@link @veramo/kms-local#KeyManagementSystem | kms-local}. + * + * Implementations of this class are used to store mappings between key aliases and key material. + * + * @public + */ export abstract class AbstractPrivateKeyStore { abstract import(args: ImportablePrivateKey): Promise + abstract get(args: { alias: string }): Promise + abstract delete(args: { alias: string }): Promise + abstract list(args: {}): Promise> } diff --git a/packages/key-manager/src/abstract-secret-box.ts b/packages/key-manager/src/abstract-secret-box.ts index a21d25379..67320b287 100644 --- a/packages/key-manager/src/abstract-secret-box.ts +++ b/packages/key-manager/src/abstract-secret-box.ts @@ -1,3 +1,9 @@ +/** + * This simple abstract class can be extended by different implementations to provide encryption at rest for + * some implementations of {@link @veramo/key-manager#AbstractPrivateKeyStore | AbstractPrivateKeyStore}. + * + * @public + */ export abstract class AbstractSecretBox { abstract encrypt(message: string): Promise abstract decrypt(encryptedMessageHex: string): Promise diff --git a/packages/key-manager/src/index.ts b/packages/key-manager/src/index.ts index 1b8d90242..451db007f 100644 --- a/packages/key-manager/src/index.ts +++ b/packages/key-manager/src/index.ts @@ -7,6 +7,6 @@ export { KeyManager } from './key-manager' export { AbstractKeyManagementSystem } from './abstract-key-management-system' export { AbstractKeyStore } from './abstract-key-store' -export { AbstractPrivateKeyStore, ManagedPrivateKey } from './abstract-private-key-store' +export { AbstractPrivateKeyStore, ImportablePrivateKey, ManagedPrivateKey } from './abstract-private-key-store' export { AbstractSecretBox } from './abstract-secret-box' export { MemoryKeyStore, MemoryPrivateKeyStore } from './memory-key-store' diff --git a/packages/key-manager/src/key-manager.ts b/packages/key-manager/src/key-manager.ts index 0417becb3..f0e75d6ef 100644 --- a/packages/key-manager/src/key-manager.ts +++ b/packages/key-manager/src/key-manager.ts @@ -25,10 +25,21 @@ import { serialize, computeAddress } from '@ethersproject/transactions' import { toUtf8String, toUtf8Bytes } from '@ethersproject/strings' import { convertPublicKeyToX25519 } from '@stablelib/ed25519' import Debug from 'debug' + const debug = Debug('veramo:key-manager') /** - * Agent plugin that provides {@link @veramo/core#IKeyManager} methods + * Agent plugin that implements {@link @veramo/core#IKeyManager} methods. + * + * This plugin orchestrates various implementations of {@link AbstractKeyManagementSystem}, using a KeyStore to + * remember the link between a key reference, its metadata, and the respective key management system that provides the + * actual cryptographic capabilities. + * + * The methods of this plugin are used automatically by other plugins, such as + * {@link @veramo/did-manager#DIDManager | DIDManager}, + * {@link @veramo/credential-w3c#CredentialIssuer | CredentialIssuer}, or {@link @veramo/did-comm#DIDComm | DIDComm} to + * perform their required cryptographic operations using the managed keys. + * * @public */ export class KeyManager implements IAgentPlugin { diff --git a/packages/key-manager/src/memory-key-store.ts b/packages/key-manager/src/memory-key-store.ts index 219e3c504..2149e9acc 100644 --- a/packages/key-manager/src/memory-key-store.ts +++ b/packages/key-manager/src/memory-key-store.ts @@ -7,6 +7,14 @@ import { } from './abstract-private-key-store' import { v4 as uuidv4 } from 'uuid' +/** + * An implementation of {@link AbstractKeyStore} that holds everything in memory. + * + * This is usable by {@link @veramo/key-manager#KeyManager | KeyManager} to hold the key metadata and relationship to + * the KMS implementation. + * + * @public + */ export class MemoryKeyStore extends AbstractKeyStore { private keys: Record = {} @@ -38,7 +46,9 @@ export class MemoryKeyStore extends AbstractKeyStore { /** * An implementation of {@link AbstractPrivateKeyStore} that holds everything in memory. * - * This is usable by {@link @veramo/kms-local} to hold the private key data. + * This is usable by {@link @veramo/kms-local#KeyManagementSystem} to hold the private key data. + * + * @public */ export class MemoryPrivateKeyStore extends AbstractPrivateKeyStore { private privateKeys: Record = {} diff --git a/packages/kms-local/src/key-management-system.ts b/packages/kms-local/src/key-management-system.ts index dc69a4600..7872806e9 100644 --- a/packages/kms-local/src/key-management-system.ts +++ b/packages/kms-local/src/key-management-system.ts @@ -24,8 +24,18 @@ import { randomBytes } from '@ethersproject/random' import { arrayify, hexlify } from '@ethersproject/bytes' import * as u8a from 'uint8arrays' import Debug from 'debug' + const debug = Debug('veramo:kms:local') +/** + * This is an implementation of {@link @veramo/key-manager#AbstractKeyManagementSystem | AbstractKeyManagementSystem} + * that uses a local {@link @veramo/key-manager#AbstractPrivateKeyStore | AbstractPrivateKeyStore} to hold private key + * material. + * + * The key material is used to provide local implementations of various cryptographic algorithms. + * + * @public + */ export class KeyManagementSystem extends AbstractKeyManagementSystem { private readonly keyStore: AbstractPrivateKeyStore @@ -92,10 +102,10 @@ export class KeyManagementSystem extends AbstractKeyManagementSystem { } async sign({ - keyRef, - algorithm, - data, - }: { + keyRef, + algorithm, + data, + }: { keyRef: Pick algorithm?: string data: Uint8Array @@ -250,7 +260,7 @@ export class KeyManagementSystem extends AbstractKeyManagementSystem { } /** - * Converts a {@link ManagedPrivateKey} to {@link ManagedKeyInfo} + * Converts a {@link @veramo/key-manager#ManagedPrivateKey | ManagedPrivateKey} to {@link @veramo/core#ManagedKeyInfo} */ private asManagedKeyInfo(args: RequireOnly): ManagedKeyInfo { let key: Partial diff --git a/packages/kms-local/src/secret-box.ts b/packages/kms-local/src/secret-box.ts index 1c7330dc2..3b69d123c 100644 --- a/packages/kms-local/src/secret-box.ts +++ b/packages/kms-local/src/secret-box.ts @@ -6,6 +6,16 @@ import { toUtf8Bytes, toUtf8String } from '@ethersproject/strings' const NONCE_BYTES = 24 +/** + * This is an implementation of {@link @veramo/key-manager#AbstractSecretBox | AbstractSecretBox} that uses a JavaScript + * {@link https://nacl.cr.yp.to/secretbox.html | nacl secretBox} implementation for encryption. + * + * See {@link @veramo/data-store#PrivateKeyStore} + * See {@link @veramo/data-store-json#PrivateKeyStoreJson} + * See {@link @veramo/key-manager#AbstractSecretBox} + * + * @public + */ export class SecretBox extends AbstractSecretBox { constructor(private secretKey: string) { super() diff --git a/packages/message-handler/src/message-handler.ts b/packages/message-handler/src/message-handler.ts index 3c45436ac..f65680bb3 100644 --- a/packages/message-handler/src/message-handler.ts +++ b/packages/message-handler/src/message-handler.ts @@ -12,6 +12,7 @@ import { Message } from './message' import { AbstractMessageHandler } from './abstract-message-handler' import Debug from 'debug' + const debug = Debug('veramo:message-handler') export const EventTypes = { @@ -21,7 +22,18 @@ export const EventTypes = { } /** - * Agent plugin that provides {@link @veramo/core#IMessageHandler} methods + * A Veramo agent plugin that implements {@link @veramo/core#IMessageHandler | IMessageHandler} methods. + * + * This plugin is meant to chain together multiple other {@link @veramo/core#IMessageHandler | IMessageHandler} + * implementations. + * + * When handling a message, the message is passed from one handler to the next, and each handler in + * the chain can decide if it is able to interpret the message. + * + * If the message can be processed by a handler it is returned as an {@link @veramo/core#IMessage | IMessage}. + * If the message cannot be processed by any of the handlers, an error is thrown. + * + * @public */ export class MessageHandler implements IAgentPlugin { /** diff --git a/packages/message-handler/src/message.ts b/packages/message-handler/src/message.ts index df0e535dc..37dc47044 100644 --- a/packages/message-handler/src/message.ts +++ b/packages/message-handler/src/message.ts @@ -1,5 +1,12 @@ import { IMessage, IMetaData, VerifiableCredential, VerifiablePresentation } from '@veramo/core' +/** + * A class implementing {@link @veramo/core#IMessage | IMessage}. + * + * This is used by {@link @veramo/message-handler#MessageHandler | MessageHandler}. + * + * @public + */ export class Message implements IMessage { constructor(data?: { raw: string; metaData?: IMetaData[] }) { if (data?.raw) { diff --git a/packages/remote-client/src/client.ts b/packages/remote-client/src/client.ts index 67185320a..3339261bc 100644 --- a/packages/remote-client/src/client.ts +++ b/packages/remote-client/src/client.ts @@ -1,6 +1,17 @@ import 'cross-fetch/polyfill' import { IAgentPlugin, IPluginMethodMap, IAgentPluginSchema } from '@veramo/core' +/** + * This plugin can be used to access the methods of a remote Veramo agent as if they were implemented locally. + * + * The remote agent should be provided by {@link @veramo/remote-server#AgentRouter | AgentRouter}, or a similar + * implementation of this API. + * + * The schema of the remote agent is usually provided by {@link @veramo/remote-server#ApiSchemaRouter | + * ApiSchemaRouter}. + * + * @public + */ export class AgentRestClient implements IAgentPlugin { readonly methods: IPluginMethodMap = {} readonly schema?: IAgentPluginSchema diff --git a/packages/remote-client/src/openApi.ts b/packages/remote-client/src/openApi.ts index 3876f6c51..8982cf223 100644 --- a/packages/remote-client/src/openApi.ts +++ b/packages/remote-client/src/openApi.ts @@ -1,6 +1,18 @@ import { OpenAPIV3 } from 'openapi-types' import { IAgent } from '@veramo/core' +/** + * This method can be used to generate an OpenAPIv3 schema to describe how the methods of a Veramo agent can be called + * remotely. + * + * @param agent - The agent whose schema needs to be interpreted. + * @param basePath - The base URL + * @param exposedMethods - The list of method names available through this schema + * @param name - The name of the agent + * @param version - The version of the agent + * + * @public + */ export const getOpenApiSchema = ( agent: IAgent, basePath: string, diff --git a/packages/remote-server/src/agent-router.ts b/packages/remote-server/src/agent-router.ts index 08634e18d..cd32f4326 100644 --- a/packages/remote-server/src/agent-router.ts +++ b/packages/remote-server/src/agent-router.ts @@ -17,10 +17,15 @@ export interface AgentRouterOptions { } /** - * Creates a router that exposes {@link @veramo/core#Agent} methods + * Creates a router that exposes {@link @veramo/core#Agent} methods remotely. + * + * This can be used by {@link @veramo/remote-client#AgentRestClient | AgentRestClient} to instantiate the methods of + * this agent on the client. * * @param options - Initialization option * @returns Expressjs router + * + * @public */ export const AgentRouter = (options: AgentRouterOptions): Router => { const router = Router() diff --git a/packages/remote-server/src/api-key-auth.ts b/packages/remote-server/src/api-key-auth.ts index ddb9abdb1..cbf9824cd 100644 --- a/packages/remote-server/src/api-key-auth.ts +++ b/packages/remote-server/src/api-key-auth.ts @@ -2,6 +2,13 @@ import passport from 'passport' import Bearer from 'passport-http-bearer' import { Router } from 'express' +/** + * This provides a simple authorization mechanism based on a single pre-shared API key. + * + * @param apiKey - the pre-shared API key + * + * @public + */ export function apiKeyAuth({ apiKey }: { apiKey: string }) { const router = Router() router.use(passport.initialize()) diff --git a/packages/remote-server/src/api-schema-router.ts b/packages/remote-server/src/api-schema-router.ts index 498209bb6..ae511b5a6 100644 --- a/packages/remote-server/src/api-schema-router.ts +++ b/packages/remote-server/src/api-schema-router.ts @@ -42,6 +42,8 @@ export interface ApiSchemaRouterOptions { * * @param options - Initialization option * @returns Expressjs router + * + * @public */ export const ApiSchemaRouter = (options: ApiSchemaRouterOptions): Router => { const router = Router() diff --git a/packages/remote-server/src/default-did.ts b/packages/remote-server/src/default-did.ts index 01a4084d9..fdd47e241 100644 --- a/packages/remote-server/src/default-did.ts +++ b/packages/remote-server/src/default-did.ts @@ -8,6 +8,14 @@ interface CreateDefaultDidOptions { messagingServiceEndpoint?: string } +/** + * This can be used to automatically create a did:web with signing and encryption keys and listing messaging and + * DIDComm service endpoints. + * + * @param options - The options guiding the creation of the default DID + * + * @beta This API may change without a BREAKING CHANGE notice. + */ export async function createDefaultDid(options: CreateDefaultDidOptions) { if (!options.agent) throw Error('[createDefaultDid] Agent is required') if (!options.baseUrl) throw Error('[createDefaultDid] baseUrl is required') diff --git a/packages/remote-server/src/messaging-router.ts b/packages/remote-server/src/messaging-router.ts index 3cab3628f..c1b61a2a7 100644 --- a/packages/remote-server/src/messaging-router.ts +++ b/packages/remote-server/src/messaging-router.ts @@ -24,10 +24,14 @@ export interface MessagingRouterOptions { } /** - * Creates a router for handling incoming messages + * Creates a router for handling incoming messages. + * + * Messages posted to this router get sent to the `handleMessage` method of the associated agent where this is used. * * @param options - Initialization option * @returns Expressjs router + * + * @public */ export const MessagingRouter = (options: MessagingRouterOptions): Router => { const router = Router() diff --git a/packages/remote-server/src/request-agent-router.ts b/packages/remote-server/src/request-agent-router.ts index 3f25db41e..b4f1e0130 100644 --- a/packages/remote-server/src/request-agent-router.ts +++ b/packages/remote-server/src/request-agent-router.ts @@ -21,10 +21,14 @@ export interface RequestWithAgentRouterOptions { } /** - * Creates a router that adds veramo agent to the request object + * Creates an expressjs router that adds a Veramo agent to the request object. + * + * This is needed by all other routers provided by this package to be able to perform their functions. * * @param options - Initialization option * @returns Expressjs router + * + * @public */ export const RequestWithAgentRouter = (options: RequestWithAgentRouterOptions): Router => { const router = Router() diff --git a/packages/remote-server/src/web-did-doc-router.ts b/packages/remote-server/src/web-did-doc-router.ts index 9c86828ca..cb1c67a64 100644 --- a/packages/remote-server/src/web-did-doc-router.ts +++ b/packages/remote-server/src/web-did-doc-router.ts @@ -6,6 +6,11 @@ interface RequestWithAgentDIDManager extends Request { agent?: TAgent } +/** + * The URL path to the DID document, used by did:web when the identifier is a hostname. + * + * @public + */ export const didDocEndpoint = '/.well-known/did.json' const keyMapping: Record = { @@ -28,6 +33,8 @@ export interface WebDidDocRouterOptions { * * @param options - Initialization option * @returns Expressjs router + * + * @public */ export const WebDidDocRouter = (options: WebDidDocRouterOptions): Router => { const router = Router() diff --git a/packages/selective-disclosure/plugin.schema.json b/packages/selective-disclosure/plugin.schema.json index d8015ad89..9f33fe713 100644 --- a/packages/selective-disclosure/plugin.schema.json +++ b/packages/selective-disclosure/plugin.schema.json @@ -223,6 +223,10 @@ "type": "string" } }, + "required": [ + "id", + "type" + ], "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 }" }, "CompactJWT": { diff --git a/packages/selective-disclosure/src/action-handler.ts b/packages/selective-disclosure/src/action-handler.ts index e3b995d07..37ee1497f 100644 --- a/packages/selective-disclosure/src/action-handler.ts +++ b/packages/selective-disclosure/src/action-handler.ts @@ -39,7 +39,7 @@ import { * {@link https://www.w3.org/TR/vc-data-model/#presentations | W3C Presentation} * as the response encoding instead of a `shareReq`. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export class SelectiveDisclosure implements IAgentPlugin { readonly methods: ISelectiveDisclosure @@ -64,7 +64,7 @@ export class SelectiveDisclosure implements IAgentPlugin { * {@link ISelectiveDisclosureRequest} * @param context - *RESERVED* This is filled by the framework when the method is called. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ async createSelectiveDisclosureRequest( args: ICreateSelectiveDisclosureRequestArgs, @@ -113,7 +113,7 @@ export class SelectiveDisclosure implements IAgentPlugin { * @param args - Contains the Request to be fulfilled and the DID of the subject * @param context - *RESERVED* This is filled by the framework when the method is called. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ async getVerifiableCredentialsForSdr( args: IGetVerifiableCredentialsForSdrArgs, @@ -171,7 +171,7 @@ export class SelectiveDisclosure implements IAgentPlugin { * @param args - Contains the request and the response `Presentation` that needs to be checked. * @param context - *RESERVED* This is filled by the framework when the method is called. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ async validatePresentationAgainstSdr( args: IValidatePresentationAgainstSdrArgs, @@ -240,7 +240,7 @@ export class SelectiveDisclosure implements IAgentPlugin { /** * Creates profile credentials * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ async createProfilePresentation( args: ICreateProfileCredentialsArgs, diff --git a/packages/selective-disclosure/src/index.ts b/packages/selective-disclosure/src/index.ts index c939110ec..44fa2fb0c 100644 --- a/packages/selective-disclosure/src/index.ts +++ b/packages/selective-disclosure/src/index.ts @@ -10,5 +10,12 @@ export { SdrMessageHandler, MessageTypes } from './message-handler' export { SelectiveDisclosure } from './action-handler' export * from './types' + +/** + * The parameter and return types schemas for the {@link @veramo/selective-disclosure#SelectiveDisclosure} plugin + * methods. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ const schema = require('../plugin.schema.json') export { schema } diff --git a/packages/selective-disclosure/src/message-handler.ts b/packages/selective-disclosure/src/message-handler.ts index 359e8a475..6644b900f 100644 --- a/packages/selective-disclosure/src/message-handler.ts +++ b/packages/selective-disclosure/src/message-handler.ts @@ -10,7 +10,7 @@ const debug = Debug('veramo:selective-disclosure:message-handler') * Identifies a {@link @veramo/core#IMessage} that represents a Selective Disclosure Request * * @remarks See {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export const MessageTypes = { sdr: 'sdr', @@ -20,7 +20,7 @@ export const MessageTypes = { * A Veramo message handler plugin that can decode an incoming Selective Disclosure Response * into the internal Message representation. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export class SdrMessageHandler extends AbstractMessageHandler { async handle(message: Message, context: IAgentContext): Promise { diff --git a/packages/selective-disclosure/src/types.ts b/packages/selective-disclosure/src/types.ts index 4536fb221..2d9af7e53 100644 --- a/packages/selective-disclosure/src/types.ts +++ b/packages/selective-disclosure/src/types.ts @@ -13,7 +13,7 @@ import { ICredentialIssuer } from '@veramo/credential-w3c' * Used for requesting Credentials using Selective Disclosure. * Represents an accepted issuer of a credential. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface Issuer { /** @@ -33,8 +33,7 @@ export interface Issuer { * @remarks See * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * - * @beta - */ + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ISelectiveDisclosureRequest { /** * The issuer of the request @@ -68,8 +67,7 @@ export interface ISelectiveDisclosureRequest { * @remarks See * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * - * @beta - */ + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICredentialRequestInput { /** * Motive for requiring this credential. @@ -113,7 +111,7 @@ export interface ICredentialRequestInput { * @remarks See * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICredentialsForSdr extends ICredentialRequestInput { credentials: UniqueVerifiableCredential[] @@ -122,7 +120,7 @@ export interface ICredentialsForSdr extends ICredentialRequestInput { /** * The result of a selective disclosure response validation. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IPresentationValidationResult { valid: boolean @@ -136,7 +134,7 @@ export interface IPresentationValidationResult { * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * specs * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateSelectiveDisclosureRequestArgs { data: ISelectiveDisclosureRequest @@ -149,7 +147,7 @@ export interface ICreateSelectiveDisclosureRequestArgs { * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * specs * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IGetVerifiableCredentialsForSdrArgs { /** @@ -167,7 +165,7 @@ export interface IGetVerifiableCredentialsForSdrArgs { * A tuple used to verify a Selective Disclosure Response. * Encapsulates the response(`presentation`) and the corresponding request (`sdr`) that made it. * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface IValidatePresentationAgainstSdrArgs { presentation: VerifiablePresentation @@ -177,7 +175,7 @@ export interface IValidatePresentationAgainstSdrArgs { /** * Profile data * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ICreateProfileCredentialsArgs { /** @@ -216,7 +214,7 @@ export interface ICreateProfileCredentialsArgs { * @remarks See * {@link https://github.com/uport-project/specs/blob/develop/messages/sharereq.md | Selective Disclosure Request} * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export interface ISelectiveDisclosure extends IPluginMethodMap { createSelectiveDisclosureRequest( diff --git a/packages/test-react-app/.eslintrc.js b/packages/test-react-app/.eslintrc.js index d4d119a50..1670b59cb 100644 --- a/packages/test-react-app/.eslintrc.js +++ b/packages/test-react-app/.eslintrc.js @@ -11,6 +11,15 @@ module.exports = { }, parserOptions: { sourceType: "module", - ecmaVersion: 2020 - } + ecmaVersion: 2020, + ecmaFeatures: { + jsx: true, + modules: true, + experimentalObjectRestSpread: true + } + }, + plugins: [ + "react" + ], + "extends": ["eslint:recommended", "plugin:react/recommended"], } diff --git a/packages/url-handler/src/message-handler.ts b/packages/url-handler/src/message-handler.ts index 22868ae5f..7e7f4e0dd 100644 --- a/packages/url-handler/src/message-handler.ts +++ b/packages/url-handler/src/message-handler.ts @@ -4,8 +4,15 @@ import { Message, AbstractMessageHandler } from '@veramo/message-handler' import parse = require('url-parse') import Debug from 'debug' + const debug = Debug('veramo:url:message-handler') +/** + * An implementation of {@link @veramo/message-handler#AbstractMessageHandler | AbstractMessageHandler} that can + * extract a message from a URL. + * + * @public + */ export class UrlMessageHandler extends AbstractMessageHandler { async handle(message: Message, context: IAgentContext<{}>): Promise { if (message.raw) { diff --git a/packages/utils/src/type-utils.ts b/packages/utils/src/type-utils.ts index fe9595e4d..7cd096745 100644 --- a/packages/utils/src/type-utils.ts +++ b/packages/utils/src/type-utils.ts @@ -2,7 +2,7 @@ * Checks if a variable is defined and not null * @param arg * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export function isDefined(arg: T): arg is Exclude { return arg !== null && typeof arg !== 'undefined' @@ -12,7 +12,7 @@ export function isDefined(arg: T): arg is Exclude { * Transforms an item or an array of items into an array of items * @param arg * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export function asArray(arg?: T | T[] | null): T[] { return isDefined(arg) ? (Array.isArray(arg) ? arg : [arg]) : [] @@ -22,7 +22,7 @@ export function asArray(arg?: T | T[] | null): T[] { * Checks if an object is iterable (can be used for `for..of`) * @param obj * - * @beta + * @beta This API may change without a BREAKING CHANGE notice. */ export function isIterable(obj: any): obj is Iterable { return obj != null && typeof obj[Symbol.iterator] === 'function'