@verii/verii-issuing 1.0.0-pre.1754543687

package/src/domain/prepare-jsonld-credential.js

@@ -0,0 +1,219 @@
+/*
+ * Copyright 2024 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+const { VeriiProtocolVersions } = require('@verii/vc-checks');
+const { toRelativeServiceId } = require('@verii/did-doc');
+const { castArray, isEmpty, isObject, omit, uniq } = require('lodash/fp');
+const { VelocityRevocationListType } = require('@verii/vc-checks');
+
+/** @import { Issuer, CredentialTypeMetadata, CredentialOffer, Context, JsonLdCredential, LinkedData, CredentialSubject } from "../types/types" */
+
+/**
+ * Prepares a json-ld credential from an offer
+ * @param {Issuer} issuer the issuer
+ * @param {string | undefined} credentialSubjectId id of the credential subject to bind into the credential
+ * @param {CredentialOffer} offer offer to generate from
+ * @param {string} credentialId id of the credential
+ * @param {string} contentHash hash of the raw credentialSubject and validity values
+ * @param {CredentialTypeMetadata} credentialTypeMetadata credentialType metadata
+ * @param {string} revocationUrl revocationUrl for this offer
+ * @param {Context} context context
+ * @returns {JsonLdCredential} a json-ld formatted unsigned credential
+ */
+const prepareJsonLdCredential = (
+  issuer,
+  credentialSubjectId,
+  offer,
+  credentialId,
+  contentHash,
+  credentialTypeMetadata,
+  revocationUrl,
+  context
+) => {
+  const {
+    config: { credentialExtensionsContextUrl },
+  } = context;
+
+  const credentialContexts = uniq([
+    'https://www.w3.org/2018/credentials/v1',
+    ...buildCredentialTypeJsonLdContext(credentialTypeMetadata),
+    ...extractJsonLdContext(offer),
+    credentialExtensionsContextUrl,
+  ]);
+  const jsonldCredential = {
+    ...cleanOffer(offer),
+    '@context': credentialContexts,
+    id: credentialId,
+    type: uniq([...castArray(offer.type), 'VerifiableCredential']),
+    issuer: buildIssuer(offer, issuer),
+    issuanceDate: new Date().toISOString(),
+    credentialSubject: buildCredentialSubject(
+      offer,
+      credentialSubjectId,
+      credentialContexts,
+      context
+    ),
+    credentialSchema: offer.credentialSchema ?? {
+      type: 'JsonSchemaValidator2018',
+      id: credentialTypeMetadata.schemaUrl,
+    },
+    credentialStatus: buildCredentialStatus(offer, revocationUrl),
+    contentHash: {
+      type: 'VelocityContentHash2020',
+      value: contentHash,
+    },
+    vnfProtocolVersion: isEmpty(credentialSubjectId)
+      ? VeriiProtocolVersions.PROTOCOL_VERSION_1
+      : VeriiProtocolVersions.PROTOCOL_VERSION_2,
+  };
+
+  const refreshService = buildRefreshService(issuer, offer);
+  if (refreshService != null) {
+    jsonldCredential.refreshService = refreshService;
+  }
+
+  return jsonldCredential;
+};
+
+const cleanOffer = omit([
+  // these values shouldn't have been selected from the db
+  '_id',
+  'exchangeId',
+  'offerId',
+  'offerCreationDate',
+  'offerExpirationDate',
+  'issuer.vendorOrganizationId',
+  'createdAt',
+  'updatedAt',
+  'linkedCredentials',
+  'consentedAt',
+  'rejectedAt',
+]);
+
+/**
+ * Prepares an issuer for jsonld credential
+ * @param {CredentialOffer} offer the offer
+ * @param {Issuer} issuer the issuer
+ * @returns { string | { id: string, type?: string | string[], name?: string, image?: string }} the Issuer
+ */
+const buildIssuer = (offer, issuer) =>
+  offer.issuer != null && isObject(offer.issuer)
+    ? {
+        id: issuer.did,
+        ...omit(['vendorOrganizationId'], offer.issuer),
+      }
+    : { id: issuer.did };
+
+/**
+ * Builds credential status for the credential
+ * @param {CredentialOffer} offer the offer
+ * @param {string} credentialSubjectId the credential subject id
+ * @param {Array} credentialContexts the credential contexts
+ * @param {Context} context the context
+ * @returns {CredentialSubject} the credential subject
+ */
+const buildCredentialSubject = (
+  { credentialSubject },
+  credentialSubjectId,
+  credentialContexts,
+  context
+) => {
+  const result = omit(['vendorUserId'], credentialSubject);
+  if (!isEmpty(credentialSubjectId)) {
+    // eslint-disable-next-line better-mutation/no-mutation
+    result.id = credentialSubjectId;
+  }
+  if (context.config.credentialSubjectContext === true) {
+    // eslint-disable-next-line better-mutation/no-mutation
+    result['@context'] = credentialContexts;
+  }
+  return result;
+};
+
+/**
+ * Builds credential status for the credential
+ * @param {CredentialOffer} offer the offer
+ * @param {string} velocityRevocationUrl the revocation url
+ * @returns {LinkedData | LinkedData[]} the credential status
+ */
+const buildCredentialStatus = (offer, velocityRevocationUrl) => {
+  const velocityCredentialStatus = {
+    type: VelocityRevocationListType,
+    id: velocityRevocationUrl,
+  };
+
+  return addToPolymorphicArray(
+    velocityCredentialStatus,
+    offer.credentialStatus
+  );
+};
+
+/**
+ * Builds refresh service(s)
+ * @param {Issuer} issuer the issuer
+ * @param {CredentialOffer} offer the offer
+ * @returns {LinkedData | LinkedData[] | undefined} the refreshservices for this offer
+ */
+const buildRefreshService = (issuer, offer) => {
+  if (issuer.issuingRefreshServiceId == null) {
+    return undefined;
+  }
+
+  const defaultRefreshService = {
+    type: 'VelocityNetworkRefreshService2024',
+    id: `${issuer.did}${toRelativeServiceId(issuer.issuingRefreshServiceId)}`,
+  };
+  return addToPolymorphicArray(defaultRefreshService, offer.refreshService);
+};
+
+/**
+ * Adds to a polymorphic string array
+ * @param {string} newVal the new value to add
+ * @param {undefined | null | string | string[]} existingVal the existing value if any
+ * @returns {string | string[]} the new value
+ */
+const addToPolymorphicArray = (newVal, existingVal) => {
+  if (existingVal == null) {
+    return newVal;
+  }
+  const array = castArray(existingVal);
+  // eslint-disable-next-line better-mutation/no-mutating-methods
+  array.push(newVal);
+  return array;
+};
+
+/**
+ * Extracts json ld context values as an string array
+ * @param {{"@context"?: string | string[]}} jsonLd any jsonLd
+ * @returns {string[]} the array of jsonLD contexts
+ */
+const extractJsonLdContext = ({ '@context': jsonLdContext } = {}) =>
+  jsonLdContext == null ? [] : castArray(jsonLdContext);
+
+/**
+ * Builds json ld context for the credential type
+ * @param {CredentialTypeMetadata} credentialTypeMetadata credential type metadata
+ * @returns {string[]} an array of strings
+ */
+const buildCredentialTypeJsonLdContext = (credentialTypeMetadata) =>
+  credentialTypeMetadata.jsonldContext != null
+    ? castArray(credentialTypeMetadata.jsonldContext)
+    : [];
+
+module.exports = {
+  prepareJsonLdCredential,
+};

package/src/index.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2024 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+module.exports = {
+  ...require('./issue-verii-credentials'),
+  ...require('./domain/hash-offer'),
+  ...require('./adapters/mongo-allocation-list-queries'),
+  ...require('./adapters/get-revocation-registry'),
+};

package/src/issue-verii-credentials.js

@@ -0,0 +1,104 @@
+/**
+ * Copyright 2023 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const { filter, flow, map } = require('lodash/fp');
+const { allocateListEntries } = require('./allocate-list-entries');
+const {
+  initCredentialMetadataContract,
+} = require('./adapters/init-credential-metadata-contract');
+const { createRevocationList } = require('./adapters/create-revocation-list');
+const {
+  buildVerifiableCredentials,
+} = require('./domain/build-verifiable-credentials');
+
+const REVOCATION_LIST_SIZE = 10240;
+const METADATA_LIST_SIZE = 10000;
+
+/** @import { Issuer, AllocationListEntry, CredentialOffer, CredentialMetadata, CredentialTypeMetadata, Context } from "../types/types" */
+
+/**
+ * Creates verifiable credential from a local offer. Current assumption is that offers contain all required fields
+ * including @context, type, contentHash
+ * @param {CredentialOffer[]} offers  array of offers
+ * @param {string} credentialSubjectId  optional field if credential subject needs to be bound into the offer
+ * @param {{[Name: string]: CredentialTypeMetadata}} credentialTypesMap the credential types metadata
+ * @param {Issuer} issuer  the issuer
+ * @param {Context} context the context
+ * @returns {Promise<string[]>} Returns signed credentials for each offer in vc-jwt format
+ */
+const issueVeriiCredentials = async (
+  offers,
+  credentialSubjectId,
+  credentialTypesMap,
+  issuer,
+  context
+) => {
+  // pre-allocate list entries using internal tables/collections
+  const revocationListEntries = await allocateListEntries(
+    offers.length,
+    issuer,
+    'revocationListAllocations',
+    REVOCATION_LIST_SIZE,
+    context
+  );
+
+  const metadataEntries = await allocateListEntries(
+    offers.length,
+    issuer,
+    'metadataListAllocations',
+    METADATA_LIST_SIZE,
+    context
+  );
+
+  // build credential and metadata
+  const vcs = await buildVerifiableCredentials(
+    offers,
+    credentialSubjectId,
+    issuer,
+    metadataEntries,
+    revocationListEntries,
+    credentialTypesMap,
+    context
+  );
+
+  // create any necessary revocation lists on dlt
+  await Promise.all(
+    flow(
+      filter({ isNewList: true }),
+      map((entry) => createRevocationList(entry.listId, issuer, context))
+    )(revocationListEntries)
+  );
+
+  const { addEntry, createList } = await initCredentialMetadataContract(
+    issuer,
+    context
+  );
+
+  // create any necessary metadata lists on dlt
+  await Promise.all(
+    flow(
+      filter({ metadata: { isNewList: true } }),
+      map(({ metadata: { listId } }) => createList(listId, issuer, context))
+    )(vcs)
+  );
+
+  // create credential metadata entries on dlt
+  await Promise.all(map(({ metadata }) => addEntry(metadata), vcs));
+
+  return map('vcJwt', vcs);
+};
+
+module.exports = { issueVeriiCredentials };

package/src/utils/allocate-array.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+const { shuffle } = require('fast-shuffle');
+
+/**
+ * Generates a random set of numbers in an array up to `size`
+ * @param {number} size the size of the array to allocate
+ * @returns {number[]} the array of random numbers
+ */
+const allocateArray = (size) =>
+  shuffle(Array.from({ length: size }, (v, i) => i));
+
+module.exports = { allocateArray };

package/src/utils/constants.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+const OfferType = {
+  PREPREPARED_ONLY: 'PREPREPARED_ONLY',
+  ALL: 'ALL',
+  LEGACY: 'LEGACY',
+};
+
+const ISSUING_CHALLENGE_SIZE = 16;
+
+module.exports = {
+  OfferType,
+  ISSUING_CHALLENGE_SIZE,
+};

package/src/utils/generate-list-index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024 Velocity Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Generates a random 6 byte value
+ * @returns {number} a random number 6 bytes in length
+ */
+const generateListIndex = () => crypto.randomBytes(16).readUIntBE(0, 6);
+
+module.exports = { generateListIndex };

package/types/types.d.ts

@@ -0,0 +1,251 @@
+export interface CredentialMetadata extends AllocationListEntry {
+  contentHash: string;
+  credentialType: string;
+  credentialTypeByteEncoding: string;
+  publicKey: string;
+}
+
+export interface DbKey {
+  privateKey: string;
+  kidFragment: string;
+}
+
+export interface AllocationListQueries {
+  allocateNextEntry: (
+    entityName: string,
+    issuer: Issuer
+  ) => AllocationListEntry;
+  createNewAllocationList: (
+    entityName: string,
+    issuer: Issuer,
+    newListId: number,
+    allocations: number[]
+  ) => AllocationListEntry;
+}
+
+// TODO add support for signing transactions and jwts without keys leaving the KMS sandbox
+/**
+ * Loads keys and in the future signs transactions or JWTs
+ */
+export interface KMS {
+  loadKey: (keyId: string) => DbKey;
+  // signJwt: (jwtJson: object, keyId: string) => string
+  // signTransaction: (transaction: string, keyId: string) => string
+}
+
+export interface Context {
+  // contracts
+  /**
+   * Config for the nominated CAO whos creds need to be used for DLT node calls.
+   * TODO make this id & credentials instead OR make the contract services injection much smarter
+   */
+  caoDid: string;
+  /**
+   * config object containing the contract addresses for the chain.
+   * TODO tighten up type safety
+   */
+  config: object;
+  /**
+   * A RPC provider.
+   * TODO explore removing
+   */
+  rpcProvider?: unknown;
+  // db
+  /**
+   * The db connection object.
+   */
+  allocationListQueries: AllocationListQueries;
+  // credentialTypes
+  /**
+   * a registrar fetcher for loading credential types.
+   * TODO explore having credential types as a dependency and remvoing fetcher and cache
+   */
+  registrarFetch: unknown;
+  /**
+   * a cache for fetch results
+   */
+  cache?: unknown;
+  // key signing
+  /**
+   * A KMS interface for loading keys.
+   *
+   */
+  kms: KMS;
+}
+
+export interface Entity {
+  id: string;
+  did: string;
+  dltOperatorAddress: string;
+  dltOperatorKMSKeyId: string;
+  issuingServiceDIDKeyId: string;
+  dltPrimaryAddress: string;
+}
+
+export interface Issuer extends Entity {
+  issuingRefreshServiceId: string;
+  issuingServiceKMSKeyId: string;
+  issuingServiceDIDKeyId: string;
+}
+
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export interface CredentialTypeMetadata {
+  id: string;
+  credentialType: string;
+  jsonldContext: string[];
+  schemaUrl: string;
+  defaultSignatureAlgorithm: string;
+}
+
+export interface BaseCredential {
+  /**
+   * json-ld context
+   */
+  '@context'?: string | string[];
+  /**
+   * type is identical to the standard based type found on verifiable credentials but does not accept a plane string,
+   * it only accepts an array to indicate an unordered set of type URIs
+   */
+  type: string[];
+  /**
+   * when the credential will start being valid
+   */
+  validFrom?: string;
+  /**
+   * when the credential will expire
+   */
+  validUntil?: string;
+  replaces?: NewResourceReference[];
+  relatedResource?: NewResourceReference[];
+}
+
+/**
+ * A DLT list entry is used for managing entries on dlt lists
+ */
+export interface AllocationListEntry {
+  isNewList: boolean;
+  listId: number;
+  index: number;
+}
+
+export interface CredentialOffer extends BaseCredential {
+  /**
+   * Contains all the claims of the credential
+   */
+  credentialSubject: {
+    [k: string]: unknown;
+  };
+  /**
+   * issuer to include if using branding for the issuer
+   */
+  issuer: {
+    id: string;
+    name?: string;
+    image?: string;
+  };
+  [k: string]: unknown;
+}
+
+export interface JsonLdCredential extends BaseCredential {
+  /**
+   * id of the credential
+   */
+  id: string;
+  /**
+   * Contains all the claims of the credential
+   */
+  credentialSubject: CredentialSubject;
+  /**
+   * issuer is either a DID or an object containig DID and optional branding information
+   */
+  issuer:
+    | string
+    | {
+        id: string;
+        type?: string | string[];
+        name?: string;
+        image?: string;
+      };
+  issued: string;
+  /**
+   * content hash of the offer
+   */
+  contentHash: {
+    type: string;
+    value: string;
+  };
+  refreshService?: LinkedData | LinkedData[];
+  credentialSchema?: LinkedData | LinkedData[];
+  vnfProtocolVersion: string;
+  [k: string]: unknown;
+}
+
+export interface CredentialSubject {
+  /**
+   * json-ld context
+   */
+  '@context': string | string[];
+  /**
+   * type is identical to the standard based type found on verifiable credentials but does not accept a plane string,
+   * it only accepts an array to indicate an unordered set of type URIs
+   */
+  type: string | string[];
+  /**
+   * Optional id property identifies the credential subject
+   */
+  id?: string;
+  [k: string]: unknown;
+}
+
+export type ResourceReference = {
+  /**
+   * the id of the resource that is an alternative
+   */
+  id: string;
+  /**
+   * the type of alternative. PDF or VC
+   */
+  type?: string | string[];
+  /**
+   * the media type of the URI. Can be used to validate what is download  ed
+   */
+  mediaType?: string;
+  /**
+   * the digest of the object
+   */
+  digestSRI?: string;
+  /**
+   * the name of the referenced resource
+   */
+  name?: string;
+  /**
+   * rendering hints for wallets. Can be used to validate the downloaded credential
+   */
+  hint?: string | string[];
+};
+
+export type NewResourceReference =
+  | ResourceReference
+  | {
+      /**
+       * a reference to an offerId in the same exchange
+       */
+      offerId: string;
+      /**
+       * the type of alternative. PDF or VC
+       */
+      type?: string | string[];
+    };
+
+/**
+ * A linked data reference in JSON-LD.
+ */
+export interface LinkedData {
+  id: string;
+  type?: string | string[];
+}