Trust registries

To unify the process of declaring trusted identities for credential verification, Document Rails introduces the concept of trust registries.

Trust registries allow you to declare a list of DIDs and JWKs, which you can later use in the credential verification API.

Automatic updates

Optionally, you may configure trust registries to be automatically updated in the background.

Trust registries support the following update types:

Push (1)
Pull (2)

In both cases, you will have to provide a URL of a "trust registry publisher", a separate service you can install to publish trust registries, or utilize to fetch existing trust registries from other entities.

Push trust registries

Push trust registries are utilized to automatically publish the trust registry list to a "trust registry publisher".

This allows third-parties to fetch an up-to-date list of your identities, making sure they utilize the latest versions of your signing keys to verify credentials.

Pull trust registries

Pull trust registries allow you to automatically fetch the latest information about trusted identities from other "trust registry publishers".

For example, a third-party entity can setup their own "trust registry publisher", which you can use to automatically check issued credentials against.

Existing keys are removed during sync

During the pull trust registry sync process, Document Rails replaces existing keys.

Pull trust registries are not meant to be edited manually.

Transient trust registries

When using the verification API, instead of pre-defining trust registries using Document Rails you may pass trusted issuers dynamically from your application by using transient trust registries.

Transient trust registries are not stored in the database and are utilized for the duration of a single verification request. Practically, this delegates trust registry maintenance to your application, allowing you to dynamically set trusted issuers for every single request depending on the requirements of a particular verification session.

To use transient trust registries, pass the transient_trust_registry value when invoking the verification API:

import { verify, OptionalityFlag, VerifyInputKind } from "@vaultie/document-rails";

const response = await verify(
    client,
    accessToken,
    organizationId,
    {
        input: {
            kind: VerifyInputKind.W3CVC,
            data: "...",
        },
        transient_trust_registry: {
            dids: ["did:web:example.com"],
        },
    }
);

Creating trust registries

Create a trust registry without automatic updates (JavaScript)Create a push trust registry (JavaScript)Create a pull trust registry (JavaScript)

import { createTrustRegistry } from "@vaultie/document-rails";

const response = await createTrustRegistry(
    client,
    accessToken,
    organizationId,
    {},
);

import { createTrustRegistry, TrustRegistryUpdateType } from "@vaultie/document-rails";

const response = await createTrustRegistry(
    client,
    accessToken,
    organizationId,
    {
        update_type: TrustRegistryUpdateType.Push,

        // Trust registry publisher URL.
        update_url: "http://trp.example.com/pushTest",
    },
);

import { createTrustRegistry, TrustRegistryUpdateType } from "@vaultie/document-rails";

const response = await createTrustRegistry(
    client,
    accessToken,
    organizationId,
    {
        update_type: TrustRegistryUpdateType.Pull,

        // Trust registry publisher URL.
        update_url: "http://trp.example.com/pullTest",
    },
);

Attaching entities to trust registries

Attach an existing DID to a trust registry (JavaScript)Attach an existing JWK to a trust registry (JavaScript)Attach an existing certificate to a trust registry (JavaScript)

import { attachDIDToTrustRegistry } from "@vaultie/document-rails";

await attachDIDToTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    didId,
);

import { attachJWKToTrustRegistry } from "@vaultie/document-rails";

await attachJWKToTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    jwkId,
);

import { attachCertificateToTrustRegistry } from "@vaultie/document-rails";

await attachCertificateToTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    certificateId,
);

Detaching entities from trust registries

Detach an existing DID from a trust registry (JavaScript)Detach an existing JWK from a trust registry (JavaScript)Detach an existing certificate from a trust registry (JavaScript)

import { detachDIDFromTrustRegistry } from "@vaultie/document-rails";

await detachDIDFromTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    didId,
);

import { detachJWKFromTrustRegistry } from "@vaultie/document-rails";

await detachJWKFromTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    jwkId,
);

import { detachCertificateFromTrustRegistry } from "@vaultie/document-rails";

await detachCertificateFromTrustRegistry(
    client,
    accessToken,
    organizationId,
    trustRegistryId,
    certificateId,
);