Skip to content

Class: ClaimsService

modules/claims.ClaimsService

Service responsible for handling the request and issuance of claims. See more information about claims in IAM stack here.

const { connectToCacheServer } = await initWithPrivateKeySigner(privateKey, rpcUrl);
const { connectToDidRegistry } = await connectToCacheServer();
const { claimsService } = await connectToDidRegistry();
claimsService.getClaimById(claim.id);

Table of contents

Constructors

Methods

Constructors

constructor

• new ClaimsService(_signerService, _domainsService, _cacheClient, _didRegistry, _verifiableCredentialService)

Parameters

Name Type
_signerService SignerService
_domainsService DomainsService
_cacheClient CacheClient
_didRegistry DidRegistry
_verifiableCredentialService VerifiableCredentialsServiceBase

Methods

claimRevocationDetails

▸ claimRevocationDetails(options): Promise<undefined | ClaimRevocationDetailsResult>

Get the revocation details for a subject's On-Chain claim. Returns the revoker and revocationTimeStamp for the revocation.

claimsService.claimRevocationDetails({
    claim: {
        namespace: 'root.roles.energyweb.iam.ewc',
        subject: 'did:ethr:volta:0x00...0',
    },
});

or

claimsService.claimRevocationDetails({
    claimId: claim.id,
});

Parameters

Name Type Description
options ClaimRevocationDetailsOptions object containing options

Returns

Promise<undefined | ClaimRevocationDetailsResult>

revocation details

createClaimRequest

▸ createClaimRequest(options): Promise<void>

Allows subject to request for credential by creating and sending a claim request to claim issuer.

claimsService.createClaimRequest({
    claim: {
         claimType: 'email.roles.energyweb.iam.ewc',
         claimTypeVersion: 1,
         requestorFields: [{key: 'foo', value: 'bar'}],
    };
    subject: 'did:ethr:0x00...0',
    registrationTypes: [RegistrationTypes.OnChain, RegistrationTypes.OffChain]
});

Parameters

Name Type Description
options CreateClaimRequestOptions object containing options

Returns

Promise<void>

createDelegateProof

▸ createDelegateProof(delegateKey, identity, algorithm?): Promise<string>

Create a public claim to prove identity.

claimsService.createDelegateProof(
    '245a40a9...776071ca57cec',
    'did:ethr:0x00...0',
    Algorithms.EIP191,
);

Parameters

Name Type Default value Description
delegateKey string undefined Private key of the delegate in hexadecimal format
identity string undefined DID of the delegate
algorithm Algorithms Algorithms.EIP191 Algorithm used to sign the delegate (EIP191 and ES256 available)

Returns

Promise<string>

JWT token of delegate

createIdentityProof

▸ createIdentityProof(): Promise<string>

Create a public claim to prove identity.

claimsService.createIdentityProof();

Returns

Promise<string>

JWT token of created identity

createSelfSignedClaim

▸ createSelfSignedClaim(options): Promise<string>

Creates self signed off-chain claim with data and adds it to subject document. Signer must own or control subject.

claimsService.createSelfSignedClaim({
    data: {
         claimType: 'email.roles.energyweb.iam.ewc',
         claimTypeVersion: 1,
         issuerFields: [{key: 'foo', value: 'bar'}],
         profile: {
             name: 'John Doe',
             birthdate: '1990-01-01',
             address: '123 Main St',
         },
    },
    subject: 'did:ethr:volta:0x00...0',
});

Parameters

Name Type Description
options CreateSelfSignedClaimOptions object containing options

Returns

Promise<string>

URl to IPFS

deleteClaim

▸ deleteClaim(options): Promise<void>

Delete claim request. Works only for pending claims (not issued or rejected).

claimsService.deleteClaim({
    id: '7281a130-e2b1-430d-8c14-201010eae901',
});

Parameters

Name Type Description
options DeleteClaimOptions object containing options

Returns

Promise<void>

fetchCredential

▸ fetchCredential(subjectDID, roleNamespace): Promise<undefined | VerifiableCredential<RoleCredentialSubject> | RoleEIP191JWT>

Fetch a credential from storage

Parameters

Name Type Description
subjectDID string The DID to try to resolve a credential for
roleNamespace string -

Returns

Promise<undefined | VerifiableCredential<RoleCredentialSubject> | RoleEIP191JWT>

credential if available or undefined if not

getClaimById

▸ getClaimById(claimId): Promise<undefined | Claim>

Retrieve claim with given id.

const claimId = '7281a130-e2b1-430d-8c14-201010eae901';
claimsService.getClaimById(claimId);

Parameters

Name Type Description
claimId string claim id

Returns

Promise<undefined | Claim>

claim with given id

getClaimId

▸ getClaimId(«destructured»): Promise<string>

Generates claim id or returns id of existing claim with same data

Parameters

Name Type
«destructured» Object
› claimData ClaimData

Returns

Promise<string>

claim identifier

getClaimsByIssuer

▸ getClaimsByIssuer(options): Promise<Claim[]>

Retrieve claims issued by a given issuer with allowing filter by status and parent namespace.

claimsService.getClaimsByIssuer({
    did: 'did:ethr:0x00...0',
    isAccepted: false,
    namespace: 'energyweb.iam.ewc',
});

Parameters

Name Type Description
options GetClaimsByIssuerOptions object containing options

Returns

Promise<Claim[]>

list of claims

getClaimsByRequester

▸ getClaimsByRequester(options): Promise<Claim[]>

Retrieve claims requested by a given requester with allowing filter by status and parent namespace.

claimsService.getClaimsByRequester({
    did: 'did:ethr:0x00...0',
    isAccepted: false,
    namespace: 'energyweb.iam.ewc',
});

Parameters

Name Type Description
options GetClaimsByRequesterOptions object containing options

Returns

Promise<Claim[]>

list of claims

getClaimsByRevoker

▸ getClaimsByRevoker(options): Promise<Claim[]>

Retrieve all claims that a user can revoke. Allow to filter by namespace

claimsService.getClaimsByRevoker({
 did: 'did:ethr:0x00...0',
 namespace: 'energyweb.iam.ewc',
});

Parameters

Name Type
options GetClaimsByRevokerOptions

Returns

Promise<Claim[]>

list of claims

getClaimsBySubject

▸ getClaimsBySubject(options): Promise<Claim[]>

Retrieve claims for given subject with allowing filter by status and parent namespace.

claimsService.getClaimsBySubject({
    did: 'did:ethr:0x00...0',
    isAccepted: false,
    namespace: 'energyweb.iam.ewc',
});

Parameters

Name Type Description
options GetClaimsBySubjectOptions object containing options

Returns

Promise<Claim[]>

list of claims

getClaimsBySubjects

▸ getClaimsBySubjects(subjects): Promise<Claim[]>

Retrieve claims related to a given subjects.

claimsService.getClaimsBySubjects(['did:ethr:0x00...0', 'did:ethr:0x00...1', ...]);

Parameters

Name Type Description
subjects string[] list of subjects

Returns

Promise<Claim[]>

list of claims

getNamespaceFromClaimType

▸ getNamespaceFromClaimType(claimType): string

Get namespace from claim type.

claimsService.getNamespaceFromClaimType(
    'email.roles.energyweb.iam.ewc'
);

Parameters

Name Type Description
claimType string Private key of the delegate in hexadecimal format

Returns

string

Namespace of given claim type

getUserClaims

▸ getUserClaims(options): Promise<IServiceEndpoint & Pick<ClaimData, "claimType" | "claimTypeVersion">[]>

Get published off-chain claims of the given subject.

claimsService.getUserClaims({
    did: 'did:ethr:0x00...0',
});

Parameters

Name Type Description
options GetUserClaimsOptions object containing options

Returns

Promise<IServiceEndpoint & Pick<ClaimData, "claimType" | "claimTypeVersion">[]>

Claims containing DID document service endpoints

hasOnChainRole

▸ hasOnChainRole(did, role, version): Promise<boolean>

A utility function to check the blockchain directly if a DID has a role.

claimsService.hasOnChainRole('did:ethr:ewc:0x00...0', 'email.roles.iam.ewc', 1);

Parameters

Name Type Description
did string The ethr DID to check
role string The role to check (the full namespace)
version number The version to check

Returns

Promise<boolean>

true if DID has role at the version. false if not.

init

▸ init(): Promise<void>

Returns

Promise<void>

isClaimRevoked

▸ isClaimRevoked(options): Promise<boolean>

Check if On-Chain claim is revoked.

claimsService.isClaimRevoked({
    claim: {
        namespace: 'root.roles.energyweb.iam.ewc',
        subject: 'did:ethr:volta:0x00...0',
    },
});

or

claimsService.isClaimRevoked({
    claimId: claim.id,
});

Parameters

Name Type Description
options IsClaimRevokedOptions object containing options

Returns

Promise<boolean>

true if claim is revoked

issueClaim

▸ issueClaim(options): Promise<undefined | string>

Issue claim without previous request. Option available for issuers only. If credentialStatus is not overridden then status from ssi-hub will be set.

claimsService.issueClaim({
    claim: {
         claimType: 'email.roles.energyweb.iam.ewc',
         claimTypeVersion: 1,
         issuerFields: [{key: 'foo', value: 'bar'}],
    };
    subject: 'did:ethr:0x00...0',
    registrationTypes: [RegistrationTypes.OnChain, RegistrationTypes.OffChain]
});

Parameters

Name Type Description
options IssueClaimOptions object containing options

Returns

Promise<undefined | string>

Issued token if registrationTypes includes RegistrationTypes.OffChain

issueClaimRequest

▸ issueClaimRequest(options): Promise<void>

Issue a claim request by signing both off-chain and on-chain request and persisting result to the cache-server. Optionally, issue on-chain role can be submitted to the ClaimManager contract as well. If credentialStatus is not overridden then status from ssi-hub will be set.

const claim: Claim = await claimsService.getClaimById('7281a130-e2b1-430d-8c14-201010eae901');
claimsService.issueClaimRequest({
    requester: claim.requester,
    token: claim.token,
    id: claim.id,
    subjectAgreement: claim.subjectAgreement,
    registrationTypes: claim.registrationTypes;
    issuerFields: [{key: 'foo', value: 'bar'}],
    publishOnChain: false,
});

Parameters

Name Type Description
options IssueClaimRequestOptions object containing options

Returns

Promise<void>

publishPublicClaim

▸ publishPublicClaim(options): Promise<undefined | string>

Register role to claim manager contract if registrationTypes includes RegistrationTypes.OnChain Publish role to IPFS and add DID document service if registrationTypes includes RegistrationTypes.OffChain

const claim: Claim = await claimsService.getClaimById('7281a130-e2b1-430d-8c14-201010eae901');
claimsService.publishPublicClaim({
    claim: {
         token: claim.token,
         claimType: claim.claimType,
    };
    registrationTypes: claim.registrationTypes,
});

Parameters

Name Type Description
options PublishPublicClaimOptions object containing options

Returns

Promise<undefined | string>

URl to IPFS if registrationTypes includes RegistrationTypes.OffChain

registerOnchain

▸ registerOnchain(claim): Promise<void>

Register issued on-chain claim on Claim Manager contract Can be used by asset owners to register credentials on-chain for their assets.

const claim: Claim = await claimsService.getClaimById('7281a130-e2b1-430d-8c14-201010eae901');
claimsService.registerOnchain({
    claimType: claim.claimType,
    claimTypeVersion: claim.claimTypeVersion,
    subjectAgreement: claim.subjectAgreement,
    onChainProof: claim.onChainProof,
    acceptedBy: claim.acceptedBy;
    subject: claim.subject,
});

Parameters

Name Type Description
claim RegisterOnchainOptions object containing options

Returns

Promise<void>

rejectClaimRequest

▸ rejectClaimRequest(options): Promise<void>

Reject claim request.

const claim: Claim = await claimsService.getClaimById('7281a130-e2b1-430d-8c14-201010eae901');
claimsService.rejectClaimRequest({
    id: claim.id,
    requesterDID: claim.requester,
    rejectionReason: 'some reason',
});

Parameters

Name Type Description
options RejectClaimRequestOptions object containing options

Returns

Promise<void>

resolveCredentialAndVerify

▸ resolveCredentialAndVerify(subjectDID, roleNamespace): Promise<CredentialVerificationResult>

Resolve a credential from storage and verify its proof/signature and its issuer's authority

Parameters

Name Type Description
subjectDID string The DID to try to resolve a credential for
roleNamespace string -

Returns

Promise<CredentialVerificationResult>

void. Returns "Proof Not Verified" error if VC not verified. Returns error if issuer not verified

revokeClaim

▸ revokeClaim(options): Promise<boolean>

Revoke On-Chain issued claim by claimId or given namespace and subject. Required claimId or claim parameters.

claimsService.revokeClaim({
    claim: {
        namespace: 'root.roles.energyweb.iam.ewc',
        subject: 'did:ethr:volta:0x00...0',
    },
    registrationTypes = [RegistrationTypes.OnChain, RegistrationTypes.OffChain],
});

or

claimsService.revokeClaim({
    claimId: claim.id,
    registrationTypes = [RegistrationTypes.OnChain, RegistrationTypes.OffChain],
});

Parameters

Name Type Description
options RevokeClaimOptions object containing options

Returns

Promise<boolean>

true if claim was revoked

revokeMultipleClaim

▸ revokeMultipleClaim(options): Promise<void>

Revoke On-Chain issued claims of the given namespace for multiple subjects. Namespace must be the same for all subjects. Specify claims or claimIds parameters.

claimsService.revokeMultipleClaim({
    claims: [{
        namespace: 'root.roles.energyweb.iam.ewc',
        subject: 'did:ethr:volta:0x00...0',
        registrationTypes = [RegistrationTypes.OnChain, RegistrationTypes.OffChain],
    },
    {
        namespace: 'root.roles.energyweb.iam.ewc',
        subject: 'did:ethr:volta:0x00...1',
        registrationTypes = [RegistrationTypes.OnChain],
    }],
});

or

claimsService.revokeMultipleClaim({
    claimIds: ['245a40a9...776071ca57cec', '245a40a9...776071ca57cec'],
});

Parameters

Name Type Description
options RevokeMultipleClaimOptions object containing options

Returns

Promise<void>

verifyRoleEIP191JWT

▸ verifyRoleEIP191JWT(roleEIP191JWT): Promise<CredentialVerificationResult>

Verifies: - That off-chain claim was issued by authorized issuer - That off-chain claim proof is valid

Parameters

Name Type
roleEIP191JWT RoleEIP191JWT

Returns

Promise<CredentialVerificationResult>

Boolean indicating if verified and array of error messages

verifyVc

▸ verifyVc(vc): Promise<CredentialVerificationResult>

Verifies: - That credential proof is valid - That credential was issued by authorized issuer - That credential was not revoked

Parameters

Name Type Description
vc VerifiableCredential<RoleCredentialSubject> to be verified

Returns

Promise<CredentialVerificationResult>

Boolean indicating if verified and array of error messages

create

▸ Static create(signerService, domainsService, cacheClient, didRegistry, verifiableCredentialService): Promise<ClaimsService>

Parameters

Name Type
signerService SignerService
domainsService DomainsService
cacheClient CacheClient
didRegistry DidRegistry
verifiableCredentialService VerifiableCredentialsServiceBase

Returns

Promise<ClaimsService>