@sphereon/ssi-sdk.w3c-vc-api

W3C VC API

---

Warning: This package is in early development. Breaking changes without notice will happen at this point!

---

This module provides a W3C Verifiable Credential API, to allow issuance and verification of VCs and VPs.

VC API

For more information about the W3C VC API visit the W3C VC API Github. This module allows you to issue, persist, retrieve and verify Verifiable Credentials (other endpoints are not supported yet)

There are 3 modes of resolution, controlled by a query parameter, when calling the resolution endpoint. You can also set a default mode when no query parameter is being used.

The modes are:

• local: Only DIDs managed by the agent can be resolved. DID:web and it's keys are translated to DID documents
• global: Resolves DIDs by using the supported resolvers of the agent, allowing external DID resolution
• hybrid (default): Tries to resolve locally first. If not found it will fallback to the global mode

Issuance example

The below example resolves the provided did:web DID using external resolution by looking up the domain from the provided host at https://ddip.sphereon.com.

curl -X POST\
-H "Accept: application/json"\
"https://agent/credentials/issue"
-d '<json body below>'

Body:

{
  "verifiableCredential": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "id": "https://example.com/8790171",
    "type": ["VerifiableCredential", "GS1CompanyPrefixLicenseCredential"],
    "issuer": "did:web:example.com",
    "issuanceDate": "2023-06-22T00:00:00.000Z",
    "validUntil": "2024-06-22T00:00:00.000Z",
    "credentialSubject": {
      "id": "did:web:subject.example.com",
      "example": "value"
    },
    "proof": {
      "type": "JsonWebSignature2020",
      "created": "2023-06-29T22:20:27.000Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:web:example.com#key-1",
      "jws": "ey......."
    }
  }
}

{}

Configure API

You can configure and build the API in multiple ways. This module also exposes functions for every endpoint, so you are able to create your own Express router and then use functions to enable certain endpoints in your solution. The more easy route is to use the VcApiServer class. This class has configuration support, allowing to enable/disable certain features, like for instance whether VCs can be created, persisted, and/or verified.

Note: You can have multiple instances of the VcApiServer, as long as you make sure that the basePaths differs for each instance and that the same express is being used.

// agent is a configured SSI-SDK/Veramo agent (see below for an example)

// Let's first build express to listen on port 5000
const expressBuilder = ExpressBuilder.fromServerOpts({
  port: 5000,
  hostname: '0.0.0.0',
}).withPassportAuth(false)
const expressArgs = expressBuilder.build({ startListening: true })

// Now create the VC PI, with VC issuance, persistence and verification enabled and authentication disabled
new VcApiServer({
  opts: {
    endpointOpts: {
      globalAuth: {
        authentication: {
          enabled: false,
        },
      },
    },
    issueCredentialOpts: {
      enableFeatures: ['vc-issue', 'vc-persist', 'vc-verify'],
      proofFormat: 'lds', // Issue JSON-LD VCs, can also be changed to `jwt`
      fetchRemoteContexts: true, // Whether to allow fetching remote contexts, mainly used when verifying VCs
      keyRef: '89a4661e446b46401325a38d3b20582d1dd277eb448a3181012a671b7ae15837', // The key to use when signing VCs
    },
  },
  expressArgs,
  agent,
})
// At this point you can execute the example above, as the VC API is now listening on port 5000

Requirements

For this plugin a DID resolver is also required. A DID resolver can be added to the agent as plugin as seen in the example below. You can find resolvers in the Veramo project and our SSI-SDK-crypto-extensions

Agent setup

export const resolver = new Resolver({
  ...getDidWebResolver(),
  ...getDidKeyResolver(),
  ...getDidJwkResolver(),
  ...getDidIonResolver(),
})

export const didProviders = {
  [`did:web`]: new WebDIDProvider({
    defaultKms: 'local',
  }),
  [`did:key`]: new KeyDIDProvider({
    defaultKms: 'local',
  }),
  [`did:ion`]: new IonDIDProvider({
    defaultKms: 'local',
  }),
  [`did:jwk`]: new JwkDIDProvider({
    defaultKms: 'local',
  }),
}

const agent = createAgent<
  IDIDManager &
    IKeyManager &
    IDataStore &
    IDataStoreORM &
    IResolver &
    IPresentationExchange &
    ICredentialVerifier &
    ICredentialHandlerLDLocal &
    ICredentialPlugin
>({
  plugins: [
    new DataStore(dbConnection),
    new DataStoreORM(dbConnection),
    new KeyManager({
      store: new KeyStore(dbConnection),
      kms: {
        local: new KeyManagementSystem(privateKeyStore),
      },
    }),
    new DIDManager({
      store: new DIDStore(dbConnection),
      defaultProvider: `${DID_PREFIX}:${SupportedDidMethodEnum.DID_JWK}`,
      providers: didProviders,
    }),
    new DIDResolverPlugin({
      resolver,
    }),
    new PresentationExchange(),
    new CredentialPlugin(),
    new CredentialHandlerLDLocal({
      contextMaps: [LdDefaultContexts],
      suites: [
        new SphereonEd25519Signature2018(),
        new SphereonEd25519Signature2020(),
        new SphereonBbsBlsSignature2020(),
        new SphereonJsonWebSignature2020(),
        new SphereonEcdsaSecp256k1RecoverySignature2020(),
      ],
      bindingOverrides: new Map([
        ['createVerifiableCredentialLD', MethodNames.createVerifiableCredentialLDLocal],
        ['createVerifiablePresentationLD', MethodNames.createVerifiablePresentationLDLocal],
      ]),
      keyStore: privateKeyStore,
    }),
  ],
})

Installation

pnpm add @sphereon/ssi-sdk.w3c-vc-api

Build

pnpm build