@verii/endpoints-organizations-registrar 1.0.0-pre.1752076816

package/src/entities/oauth/orchestrators/auth0-provisioner.js

@@ -0,0 +1,293 @@
+const { ManagementClient } = require('auth0');
+const { kebabCase, trim, map, join, includes } = require('lodash/fp');
+const { nanoid } = require('nanoid');
+const {
+  ServiceCategories,
+  ServiceTypesOfServiceCategory,
+} = require('@verii/organizations-registry');
+const { AuthClientTypes, RoleNames } = require('../domain');
+
+const initRoleNameToRoleId = ({
+  auth0SuperuserRoleId,
+  auth0ClientAdminRoleId,
+  auth0ClientFinanceAdminRoleId,
+  auth0ClientSystemUserRoleId,
+}) => {
+  return (roleName) => {
+    switch (roleName) {
+      case RoleNames.Superuser:
+        return auth0SuperuserRoleId;
+      case RoleNames.TokenWalletClientFinanceAdmin:
+        return auth0ClientFinanceAdminRoleId;
+      case RoleNames.TokenWalletClientSystemUser:
+        return auth0ClientSystemUserRoleId;
+      case RoleNames.RegistrarClientAdmin:
+      default:
+        return auth0ClientAdminRoleId;
+    }
+  };
+};
+const initAuth0Provisioner = ({
+  auth0Domain,
+  auth0ManagementApiAudience,
+  auth0ClientId,
+  auth0ClientSecret,
+  auth0Connection,
+  registrarAppUiUrl,
+  blockchainApiAudience,
+  auth0SuperuserRoleId,
+  auth0ClientAdminRoleId,
+  auth0ClientFinanceAdminRoleId,
+  auth0ClientSystemUserRoleId,
+}) => {
+  const auth0ManagementClient = new ManagementClient({
+    domain: auth0Domain,
+    audience: auth0ManagementApiAudience,
+    clientId: auth0ClientId,
+    clientSecret: auth0ClientSecret,
+  });
+
+  const roleNameToRoleId = initRoleNameToRoleId({
+    auth0SuperuserRoleId,
+    auth0ClientAdminRoleId,
+    auth0ClientFinanceAdminRoleId,
+    auth0ClientSystemUserRoleId,
+  });
+
+  const setAuth0UserGroupId = async (did, { user }) => {
+    await auth0ManagementClient.users.update(
+      { id: user.sub },
+      {
+        app_metadata: { groupId: did },
+      }
+    );
+  };
+
+  const provisionAuth0SystemClient = async (
+    did,
+    profile,
+    service,
+    provisionClientGrant
+  ) => {
+    const clientDetails = buildClientDetails(did, profile, service);
+    if (clientDetails == null) {
+      return clientDetails;
+    }
+
+    const { name, description, clientType } = clientDetails;
+
+    const { data: auth0Client } = await auth0ManagementClient.clients.create({
+      name,
+      description,
+      logo_uri: trim(profile.logo),
+      app_type: 'non_interactive',
+      custom_login_page_on: false,
+      is_first_party: true,
+      is_token_endpoint_ip_header_trusted: true,
+      token_endpoint_auth_method: 'client_secret_post',
+      oidc_conformant: true,
+      grant_types: ['client_credentials'],
+      jwt_configuration: {
+        lifetime_in_seconds: 36000,
+        secret_encoded: true,
+        alg: 'RS256',
+      },
+      client_metadata: {
+        did,
+        service_id: service.id,
+      },
+    });
+
+    const response = {
+      type: 'auth0',
+      clientType,
+      serviceId: service.id,
+      clientId: auth0Client.client_id,
+      clientSecret: auth0Client.client_secret,
+    };
+
+    if (provisionClientGrant) {
+      const clientGrant = await provisionAuth0SystemClientGrants(
+        auth0Client.client_id,
+        service.type
+      );
+      response.clientGrantIds = [clientGrant.id];
+    }
+
+    return response;
+  };
+  const provisionAuth0SystemClientGrants = async (clientId, serviceType) => {
+    const clientGrantDetails = buildClientGrantDetails(serviceType);
+    if (clientGrantDetails == null) {
+      return clientGrantDetails;
+    }
+
+    const { audience, scope } = clientGrantDetails;
+    const { data: clientGrant } =
+      await auth0ManagementClient.clientGrants.create({
+        client_id: clientId,
+        audience,
+        scope,
+      });
+    return clientGrant;
+  };
+
+  const removeAuth0Client = async (authClient) => {
+    for (const clientGrantId of authClient.clientGrantIds ?? []) {
+      // eslint-disable-next-line no-await-in-loop
+      await auth0ManagementClient.clientGrants.delete({ id: clientGrantId });
+    }
+
+    await auth0ManagementClient.clients.delete({
+      client_id: authClient.clientId,
+    });
+  };
+
+  const removeAuth0Grants = async (authClient) => {
+    for (const clientGrantId of authClient.clientGrantIds ?? []) {
+      // eslint-disable-next-line no-await-in-loop
+      await auth0ManagementClient.clientGrants.delete({ id: clientGrantId });
+    }
+  };
+
+  const createAuth0User = async ({ user }) => {
+    const { data: createUserResult } = await auth0ManagementClient.users.create(
+      {
+        email: user.email,
+        given_name: user.givenName,
+        family_name: user.familyName,
+        password: nanoid(28),
+        verify_email: false,
+        email_verified: false,
+        connection: auth0Connection,
+        app_metadata: {
+          groupId: user.groupId,
+        },
+      }
+    );
+    return {
+      ...user,
+      id: createUserResult.user_id,
+    };
+  };
+
+  const getUsersByIds = async ({ userIds, fields = ['email'] }) => {
+    const query = join(
+      ' OR ',
+      map((userId) => `user_id:${userId}`, userIds)
+    );
+    const { data: users } = await auth0ManagementClient.getUsers({
+      search_engine: 'v3',
+      q: query,
+      fields: fields.join(','),
+      per_page: 25,
+      page: 0,
+    });
+    return users;
+  };
+
+  const addRoleToAuth0User = async ({ user, roleName }) => {
+    const { data: roles } = await auth0ManagementClient.users.assignRoles(
+      {
+        id: user.id,
+      },
+      {
+        roles: [roleNameToRoleId(roleName)],
+      }
+    );
+    return roles;
+  };
+
+  const createPasswordChangeTicket = async ({
+    user,
+    resultUrl = registrarAppUiUrl,
+  }) => {
+    const { data: ticket } = await auth0ManagementClient.tickets.changePassword(
+      {
+        user_id: user.id,
+        result_url: resultUrl,
+        mark_email_as_verified: true,
+        ttl_sec: 604800,
+      }
+    );
+    return ticket;
+  };
+
+  // See https://velocitycareerlabs.visualstudio.com/velocity/_wiki/wikis/velocity.wiki/171/Authentication?anchor=org-signup-instructions&_a=edit
+  const buildClientDetails = (did, profile, service) => {
+    if (
+      ServiceTypesOfServiceCategory[
+        ServiceCategories.CredentialAgentOperator
+      ].includes(service?.type)
+    ) {
+      return {
+        name: `${namePrefix(profile)}-${
+          AuthClientTypes.CAO_NODE_CLIENT
+        }-${did}${service.id}`,
+        description: `Credential Agent for "${profile.name}" permitted to issue and verify credentials`,
+        clientType: AuthClientTypes.CAO_NODE_CLIENT,
+      };
+    }
+
+    if (
+      ServiceTypesOfServiceCategory[ServiceCategories.NodeOperator].includes(
+        service?.type
+      )
+    ) {
+      return {
+        name: `${namePrefix(profile)}-${AuthClientTypes.NODE_OPERATOR}-${did}${
+          service.id
+        }`,
+        description: `Administrator for the Node operated by "${profile.name}"`,
+        clientType: AuthClientTypes.NODE_OPERATOR,
+      };
+    }
+
+    return undefined;
+  };
+
+  const buildClientGrantDetails = (serviceType) => {
+    if (
+      includes(
+        serviceType,
+        ServiceTypesOfServiceCategory[ServiceCategories.CredentialAgentOperator]
+      )
+    ) {
+      return {
+        scope: ['eth:*'],
+        audience: blockchainApiAudience,
+      };
+    }
+
+    if (
+      ServiceTypesOfServiceCategory[ServiceCategories.NodeOperator].includes(
+        serviceType
+      )
+    ) {
+      return {
+        scope: ['*:*'],
+        audience: blockchainApiAudience,
+      };
+    }
+
+    return undefined;
+  };
+
+  return {
+    provisionAuth0SystemClient,
+    provisionAuth0SystemClientGrants,
+    setAuth0UserGroupId,
+    removeAuth0Client,
+    createAuth0User,
+    addRoleToAuth0User,
+    createPasswordChangeTicket,
+    getUsersByIds,
+    removeAuth0Grants,
+  };
+};
+
+const namePrefix = (profile) => kebabCase(profile.name);
+
+module.exports = {
+  initAuth0Provisioner,
+};

package/src/entities/oauth/orchestrators/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  ...require('./auth0-provisioner'),
+};

package/src/entities/organization-keys/domains/build-organization-key.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025 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 { omitBy, isNil, omit } = require('lodash/fp');
+const { toRelativeKeyId } = require('@verii/did-doc');
+
+const buildOrganizationKey = (organizationId, controller, spec) => {
+  const { purposes, algorithm, custodied, kmsKeyId, ...restOfSpec } = spec;
+  return omitBy(isNil, {
+    purposes,
+    algorithm,
+    controller,
+    organizationId,
+    custodied,
+    ...(restOfSpec.verificationMethod != null
+      ? buildFromVerificationMethod(restOfSpec)
+      : buildFromPublicKey(restOfSpec)),
+    ...(custodied ? { kmsKeyId } : {}),
+  });
+};
+
+const buildFromVerificationMethod = ({ verificationMethod }) => ({
+  id: toRelativeKeyId(verificationMethod.id),
+  publicKey: verificationMethod?.publicKeyJwk,
+  ...omit(['publicKeyJwk', 'id', 'purposes'], verificationMethod),
+});
+
+const buildFromPublicKey = ({ id, publicKey, ...rest }) => ({
+  id,
+  type: 'EcdsaSecp256k1VerificationKey2019',
+  publicKey,
+  ...rest,
+});
+
+module.exports = {
+  buildOrganizationKey,
+};

package/src/entities/organization-keys/domains/constants.js

@@ -0,0 +1,30 @@
+// const KeyAlgorithms = {
+//   SECP256K1: 'SECP256K1',
+// };
+//
+// const KeyEncodings = {
+//   HEX: 'hex',
+// };
+
+const KeyErrorMessages = {
+  UNRECOGNIZED_PURPOSE_DETECTED: 'Unrecognized purpose detected',
+  DUPLICATE_PURPOSE_DETECTED: 'Duplicate key purposes detected',
+  PUBLIC_KEY_MUST_BE_SPECIFIED_IF_ENCODING_IS_SPECIFIED:
+    'publicKey must be specified if encoding is specified',
+  ENCODING_MUST_BE_SPECIFIED_IF_PUBLIC_KEY_IS_SPECIFIED:
+    'encoding must be specified if publicKey is specified',
+  PUBLIC_KEY_ENCODING_DOES_NOT_MATCH_SPECIFIED_ENCODING:
+    'publicKey encoding does not match specified encoding',
+  KEY_WITH_ID_FRAGMENT_ALREADY_EXISTS_TEMPLATE: ({ kidFragment }) =>
+    `Key with kidFragment ${kidFragment} already exists`,
+  PUBLIC_KEY_ALREADY_EXISTS_TEMPLATE: ({ publicKey }) =>
+    `publicKey ${publicKey} already exists`,
+  // UNRECOGNIZED_ALGORITHM: 'Unrecognized algorithm',
+  // UNRECOGNIZED_ENCODING: 'Unrecognized encoding',
+};
+
+module.exports = {
+  // KeyAlgorithms,
+  // KeyEncodings,
+  KeyErrorMessages,
+};

package/src/entities/organization-keys/domains/extract-verification-method-from-byo-did-document.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 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 { extractVerificationMethod } = require('@verii/did-doc');
+const newError = require('http-errors');
+const { isEmpty } = require('lodash/fp');
+
+const extractVerificationMethodFromByoDID = ({ didDocument, kidFragment }) => {
+  const verificationMethod = extractVerificationMethod(
+    didDocument,
+    kidFragment
+  );
+  if (isEmpty(verificationMethod)) {
+    throw newError(400, 'Key not found in BYO DID', {
+      code: 'key_not_found_in_byo_did_doc',
+    });
+  }
+
+  return verificationMethod;
+};
+
+module.exports = {
+  extractVerificationMethodFromByoDID,
+};

package/src/entities/organization-keys/domains/find-key-by-purpose.js

@@ -0,0 +1,6 @@
+const { includes, find } = require('lodash/fp');
+
+const findKeyByPurpose = (purpose, keys) =>
+  find((key) => includes(purpose, key.purposes), keys);
+
+module.exports = { findKeyByPurpose };

package/src/entities/organization-keys/domains/index.js

@@ -0,0 +1,10 @@
+module.exports = {
+  ...require('./constants'),
+  ...require('./build-organization-key'),
+  ...require('./extract-verification-method-from-byo-did-document'),
+  ...require('./find-key-by-purpose'),
+  ...require('./jwk-to-hex-key-transformer'),
+  ...require('./map-key-response'),
+  ...require('./validate-non-custodial-key'),
+  ...require('./validate-organization-key'),
+};

package/src/entities/organization-keys/domains/jwk-to-hex-key-transformer.js

@@ -0,0 +1,13 @@
+const { isEmpty } = require('lodash/fp');
+const { hexFromJwk } = require('@verii/jwt');
+
+const jwkToHexKeyTransformer = (key) => ({
+  ...key,
+  encoding: 'hex',
+  publicKey: hexFromJwk(key.publicKey, false),
+  ...(!isEmpty(key.key) ? { key: hexFromJwk(key.key) } : {}),
+});
+
+module.exports = {
+  jwkToHexKeyTransformer,
+};

package/src/entities/organization-keys/domains/map-key-response.js

@@ -0,0 +1,29 @@
+const { hexFromJwk } = require('@verii/jwt');
+const { omit, isEmpty } = require('lodash/fp');
+
+/* eslint-disable better-mutation/no-mutation */
+const mapKeyResponse = (key, keyPair) => {
+  const response = omit(['publicKey'], key);
+  response.kidFragment = key.id;
+  response.didDocumentKey = {
+    id: key.id,
+    type: key.type,
+    controller: key.controller,
+    ...(key.type === 'JsonWebKey2020'
+      ? {
+          publicKeyJwk: key.publicKey,
+        }
+      : {
+          publicKeyMultibase: hexFromJwk(key.publicKey, false),
+        }),
+  };
+
+  if (!isEmpty(keyPair)) {
+    response.key = hexFromJwk(keyPair.privateKey);
+    response.encoding = 'hex';
+  }
+
+  return response;
+};
+
+module.exports = { mapKeyResponse };

package/src/entities/organization-keys/domains/validate-non-custodial-key.js

@@ -0,0 +1,11 @@
+const newError = require('http-errors');
+
+const validateNonCustodialKey = (newKey) => {
+  if (!newKey.custodied && newKey.kidFragment == null) {
+    throw newError(400, 'Non custodial keys must specify kidFragment', {
+      code: 'kid_fragment_required',
+    });
+  }
+};
+
+module.exports = { validateNonCustodialKey };

package/src/entities/organization-keys/domains/validate-organization-key.js

@@ -0,0 +1,42 @@
+const { all, includes, uniq, values } = require('lodash/fp');
+const newError = require('http-errors');
+const { KeyPurposes, isStringHex } = require('@verii/crypto');
+const { KeyErrorMessages } = require('./constants');
+
+const validKeyPurposes = values(KeyPurposes);
+
+const arePurposesRecognized = (purposes) => {
+  return all((purpose) => includes(purpose, validKeyPurposes), purposes);
+};
+
+const containsDuplicatePurposes = (purposes) =>
+  !(uniq(purposes).length === purposes.length);
+
+const validatePublicKeyAndEncoding = (key) => {
+  if (!key.publicKey) {
+    return;
+  }
+
+  if (!isStringHex(key.publicKey)) {
+    throw newError(
+      400,
+      KeyErrorMessages.PUBLIC_KEY_ENCODING_DOES_NOT_MATCH_SPECIFIED_ENCODING
+    );
+  }
+};
+
+const validateOrganizationKey = (key) => {
+  const { purposes } = key;
+  if (!arePurposesRecognized(purposes)) {
+    throw newError(400, KeyErrorMessages.UNRECOGNIZED_PURPOSE_DETECTED);
+  }
+  if (containsDuplicatePurposes(purposes)) {
+    throw newError(400, KeyErrorMessages.DUPLICATE_PURPOSE_DETECTED);
+  }
+
+  validatePublicKeyAndEncoding(key);
+};
+
+module.exports = {
+  validateOrganizationKey,
+};

package/src/entities/organization-keys/factories/index.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025 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('./organization-keys-factory') };

package/src/entities/organization-keys/factories/organization-keys-factory.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2025 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 { register } = require('@spencejs/spence-factories');
+const { ObjectId } = require('mongodb');
+const { KeyPurposes, KeyEncodings, KeyAlgorithms } = require('@verii/crypto');
+
+const initOrganizationFactory = require('../../organizations/factories/organizations-factory');
+const initKmsFactory = require('../../kms/factories/kms-factory');
+
+const organizationKeysRepoPlugin = require('../repos/repo');
+
+module.exports = (app) =>
+  register(
+    'organizationKey',
+    organizationKeysRepoPlugin(app)({ config: app.config }),
+    async (overrides, { getOrBuild }) => {
+      const organization = await getOrBuild(
+        'organization',
+        initOrganizationFactory(app)
+      );
+      const kmsEntry = await getOrBuild('kmsEntry', initKmsFactory(app));
+      return {
+        id: '#key-1',
+        purposes: [
+          KeyPurposes.DLT_TRANSACTIONS,
+          KeyPurposes.ISSUING_METADATA,
+          KeyPurposes.EXCHANGES,
+        ],
+        publicKey: kmsEntry.publicJwk,
+        kmsKeyId: new ObjectId(kmsEntry._id),
+        algorithm: KeyAlgorithms.SECP256K1,
+        encoding: KeyEncodings.HEX,
+        controller: organization.didDoc.id,
+        organizationId: new ObjectId(organization._id),
+        custodied: true,
+        type: 'EcdsaSecp256k1VerificationKey2019',
+        ...overrides(),
+      };
+    }
+  );

package/src/entities/organization-keys/index.js

@@ -0,0 +1,5 @@
+// TODO If we create a keys entity package, most of the stuff in this directory should probably be moved to there
+module.exports = {
+  ...require('./domains'),
+  ...require('./orchestrators'),
+};

package/src/entities/organization-keys/orchestrators/add-key-to-did-doc.js

@@ -0,0 +1,19 @@
+const { first } = require('lodash/fp');
+const { addKeysToDidDoc } = require('@verii/did-doc');
+
+const addKeyToDidDoc = async (
+  { organization, kidFragment, publicKey },
+  { repos }
+) => {
+  const { didDoc, newVerificationMethods } = addKeysToDidDoc({
+    didDoc: organization.didDoc,
+    keys: [{ id: kidFragment, publicKey }],
+  });
+
+  await repos.organizations.update(organization._id, { didDoc });
+  return first(newVerificationMethods);
+};
+
+module.exports = {
+  addKeyToDidDoc,
+};