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

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

@@ -0,0 +1,155 @@
+/*
+ * 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 { hexToJwkKeyTransformer } = require('@verii/jwt');
+const {
+  generateKeyPair,
+  KeyAlgorithms,
+  KeyPurposes,
+} = require('@verii/crypto');
+const newError = require('http-errors');
+const { kebabCase, includes } = require('lodash/fp');
+const {
+  mapKeyResponse,
+  validateNonCustodialKey,
+  validateOrganizationKey,
+  buildOrganizationKey,
+  KeyErrorMessages,
+} = require('../domains');
+const { addKeyToDidDoc } = require('./add-key-to-did-doc');
+const { addOperatorKeys } = require('./add-operator-keys');
+const {
+  resolveVerificationMethodFromByoDID,
+} = require('./resolve-verification-method-byo-did');
+
+const addKey = async (did, newKey, context) => {
+  const { repos } = context;
+  const organization = await repos.organizations.findOneByDid(did);
+
+  validateNonCustodialKey(newKey);
+  validateOrganizationKey(newKey);
+  const body = hexToJwkKeyTransformer(newKey);
+  await checkForKeyDuplication(body, organization, context);
+
+  let kmsEntry;
+  let keyPair;
+  let algorithm;
+  if (shouldGenerateNewKey(organization, newKey)) {
+    keyPair = generateKeyPair({ format: 'jwk' });
+    kmsEntry = await context.kms.importKey({
+      ...keyPair,
+      algorithm: 'ec',
+      curve: 'secp256k1',
+    });
+    algorithm = KeyAlgorithms.SECP256K1;
+  }
+
+  const kidFragment = defaultKidFragment(newKey);
+  const verificationMethod = isDIDDocumentCustodied(organization)
+    ? await addKeyToDidDoc(
+        {
+          organization,
+          kidFragment,
+          publicKey: shouldGenerateNewKey(organization, newKey)
+            ? keyPair.publicKey
+            : body.publicKey,
+        },
+        context
+      )
+    : await resolveVerificationMethodFromByoDID(
+        organization.didDoc.id,
+        kidFragment
+      );
+
+  const newOrganizationKey = buildOrganizationKey(
+    organization._id,
+    organization.didDoc.id,
+    {
+      purposes: body.purposes,
+      algorithm: algorithm ?? body.algorithm,
+      custodied: newKey.custodied,
+      kmsKeyId: kmsEntry?.id,
+      verificationMethod,
+    }
+  );
+
+  await repos.organizationKeys.insert(newOrganizationKey);
+
+  if (includes(KeyPurposes.DLT_TRANSACTIONS, newOrganizationKey.purposes)) {
+    await addOperatorKeys(
+      {
+        organization,
+        primaryAccount: organization.ids.ethereumAccount,
+        dltKeys: [newOrganizationKey],
+      },
+      context
+    );
+  }
+  return {
+    key: mapKeyResponse(newOrganizationKey, keyPair),
+  };
+};
+
+const checkForKeyDuplication = async (key, organization, { repos }) => {
+  const ors = [
+    {
+      id: key.kidFragment,
+    },
+  ];
+  if (key.publicKey) {
+    ors.push({
+      'publicKey.kty': key.publicKey.kty,
+      'publicKey.crv': key.publicKey.crv,
+      'publicKey.x': key.publicKey.x,
+      'publicKey.y': key.publicKey.y,
+    });
+  }
+  const existingOrganizationKey = await repos.organizationKeys.findOne({
+    filter: {
+      organizationId: organization._id,
+      $or: ors,
+    },
+  });
+
+  if (existingOrganizationKey != null) {
+    throw newError(
+      409,
+      buildDuplicateKeyErrorString(key, existingOrganizationKey)
+    );
+  }
+};
+
+const defaultKidFragment = (body) => {
+  if (!body.kidFragment) {
+    return `#${kebabCase(body.purposes[0])}-${Date.now()}`;
+  }
+
+  return body.kidFragment;
+};
+
+const buildDuplicateKeyErrorString = (key, existingKey) => {
+  if (key.kidFragment === existingKey.id) {
+    return KeyErrorMessages.KEY_WITH_ID_FRAGMENT_ALREADY_EXISTS_TEMPLATE(key);
+  }
+  return KeyErrorMessages.PUBLIC_KEY_ALREADY_EXISTS_TEMPLATE(key);
+};
+
+const shouldGenerateNewKey = (organization, newKey) =>
+  isDIDDocumentCustodied(organization) && newKey.publicKey == null;
+
+const isDIDDocumentCustodied = (organization) => !organization.didNotCustodied;
+
+module.exports = { addKey };

package/src/entities/organization-keys/orchestrators/add-operator-keys.js

@@ -0,0 +1,46 @@
+/*
+ * 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 { toEthereumAddress } = require('@verii/blockchain-functions');
+const { map } = require('lodash/fp');
+const {
+  initPermissionsContractByKeyId,
+  initPermissionsContract,
+} = require('../../../helpers/init-permissions-contract');
+
+const addOperatorKeys = async (
+  { primaryAccount, organization, permissioningKeyId, dltKeys },
+  context
+) => {
+  const permissionContract =
+    permissioningKeyId != null
+      ? await initPermissionsContractByKeyId(permissioningKeyId, context)
+      : await initPermissionsContract(organization, context);
+
+  await Promise.all(
+    map(
+      ({ publicKey: dltPublicKey }) =>
+        permissionContract.addOperatorKey({
+          primary: primaryAccount,
+          operator: toEthereumAddress(dltPublicKey),
+        }),
+      dltKeys
+    )
+  );
+};
+
+module.exports = { addOperatorKeys };

package/src/entities/organization-keys/orchestrators/delete-key.js

@@ -0,0 +1,93 @@
+/*
+ * 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 { toRelativeServiceId, removeKeyFromDidDoc } = require('@verii/did-doc');
+const { ObjectId } = require('mongodb');
+const newError = require('http-errors');
+const { includes } = require('lodash/fp');
+const { KeyPurposes } = require('@verii/crypto');
+const { hexFromJwk } = require('@verii/jwt');
+const { toEthereumAddress } = require('@verii/blockchain-functions');
+const {
+  initPermissionsContract,
+} = require('../../../helpers/init-permissions-contract');
+
+const deleteKey = async (did, keyId, context) => {
+  const { repos, log } = context;
+
+  const organization = await repos.organizations.findOneByDid(did, {
+    didDoc: 1,
+    ids: 1,
+    didNotCustodied: 1,
+  });
+
+  const relativeKeyId = toRelativeServiceId(keyId);
+  const organizationKey = await repos.organizationKeys.findOne({
+    filter: {
+      id: relativeKeyId,
+      organizationId: new ObjectId(organization._id),
+    },
+  });
+
+  if (!organizationKey) {
+    throw new newError.NotFound(
+      `Key ${relativeKeyId} was not found in organization ${did}`
+    );
+  }
+  if (includes(organizationKey.purposes, KeyPurposes.ISSUING_METADATA)) {
+    throw new newError.BadRequest('ISSUING_METADATA Key may not be removed');
+  }
+
+  // Update DID Document
+  await removeOperatorKeyFromBlockchain(organizationKey, organization, context);
+
+  await repos.organizationKeys.delUsingFilter({
+    filter: {
+      id: relativeKeyId,
+      organizationId: new ObjectId(organization._id),
+    },
+  });
+
+  if (!organization.didNotCustodied) {
+    const { didDoc } = removeKeyFromDidDoc({
+      didDoc: organization.didDoc,
+      keyId: relativeKeyId,
+    });
+
+    await repos.organizations.update(organization._id, {
+      didDoc,
+    });
+  }
+
+  log.info({ keyId }, 'Remove key');
+};
+
+const removeOperatorKeyFromBlockchain = async (key, organization, context) => {
+  if (!key.purposes.includes(KeyPurposes.DLT_TRANSACTIONS)) {
+    return;
+  }
+  const permissionContract = await initPermissionsContract(
+    organization,
+    context
+  );
+
+  await permissionContract.removeOperatorKey({
+    primary: organization.ids.ethereumAccount,
+    operator: toEthereumAddress(hexFromJwk(key.publicKey, false)),
+  });
+};
+
+module.exports = { deleteKey };

package/src/entities/organization-keys/orchestrators/get-key.js

@@ -0,0 +1,39 @@
+/*
+ * 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 { toRelativeServiceId } = require('@verii/did-doc');
+const newError = require('http-errors');
+const { mapKeyResponse } = require('../domains');
+
+const getKey = async (did, kid, { repos }) => {
+  const organization = await repos.organizations.findOneByDid(did);
+
+  const keyId = toRelativeServiceId(kid);
+  const key = await repos.organizationKeys.findOne({
+    filter: {
+      id: keyId,
+      organizationId: organization._id,
+    },
+  });
+
+  if (key == null) {
+    throw newError.NotFound('Key not found');
+  }
+
+  return { key: mapKeyResponse(key), custodied: key.custodied };
+};
+
+module.exports = { getKey };

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

@@ -0,0 +1,24 @@
+/*
+ * 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('./add-key-to-did-doc'),
+  ...require('./add-operator-keys'),
+  ...require('./add-key'),
+  ...require('./delete-key'),
+  ...require('./get-key'),
+  ...require('./resolve-verification-method-byo-did'),
+};

package/src/entities/organization-keys/orchestrators/resolve-verification-method-byo-did.js

@@ -0,0 +1,28 @@
+/*
+ * 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 { resolveDidWeb } = require('@verii/did-web');
+const { extractVerificationMethodFromByoDID } = require('../domains');
+
+const resolveVerificationMethodFromByoDID = async (did, kidFragment) => {
+  const didDocument = await resolveDidWeb(did);
+
+  return extractVerificationMethodFromByoDID({ didDocument, kidFragment });
+};
+
+module.exports = {
+  resolveVerificationMethodFromByoDID,
+};

package/src/entities/organization-keys/repos/repo.js

@@ -0,0 +1,48 @@
+/*
+ * 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 {
+  repoFactory,
+  autoboxIdsExtension,
+} = require('@spencejs/spence-mongo-repos');
+
+module.exports = (app, options, next = () => {}) => {
+  next();
+  return repoFactory(
+    {
+      name: 'organizationKeys',
+      entityName: 'organizationKey',
+      defaultProjection: {
+        _id: 1,
+        id: 1,
+        purposes: 1,
+        algorithm: 1,
+        encoding: 1,
+        publicKey: 1,
+        kmsKeyId: 1,
+        controller: 1,
+        organizationId: 1,
+        custodied: 1,
+        type: 1,
+        createdAt: 1,
+        updatedAt: 1,
+      },
+      extensions: [autoboxIdsExtension],
+    },
+    app
+  );
+};

package/src/entities/organization-services/adapters/index.js

@@ -0,0 +1,21 @@
+/*
+ * 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('./init-provision-auth0-clients'),
+  ...require('./init-provision-auth0-client-grants'),
+  ...require('./update-blockchain-permissions-from-permitted-services'),
+};

package/src/entities/organization-services/adapters/init-provision-auth0-client-grants.js

@@ -0,0 +1,44 @@
+/*
+ * 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 { find, map, isEmpty } = require('lodash/fp');
+
+const initProvisionAuth0ClientGrants =
+  ({ provisionAuth0SystemClientGrants }) =>
+  async (organization, activatedServiceIds = []) => {
+    const { authClients, services } = organization;
+    return Promise.all(
+      map(async (authClient) => {
+        if (
+          !activatedServiceIds.includes(authClient.serviceId) ||
+          !isEmpty(authClient.clientGrantIds)
+        ) {
+          return authClient;
+        }
+
+        const service = find({ id: authClient.serviceId }, services);
+        const clientGrant = await provisionAuth0SystemClientGrants(
+          authClient.clientId,
+          service?.type
+        );
+
+        return { ...authClient, clientGrantIds: [clientGrant.id] };
+      }, authClients)
+    );
+  };
+
+module.exports = { initProvisionAuth0ClientGrants };

package/src/entities/organization-services/adapters/init-provision-auth0-clients.js

@@ -0,0 +1,56 @@
+/*
+ * 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 { filter, flow, includes, map } = require('lodash/fp');
+const { NodeServiceCategories } = require('../domains');
+
+const initProvisionAuth0Clients =
+  ({ provisionAuth0SystemClient }) =>
+  async (organization, services, activatedServiceIds, context) => {
+    const {
+      log,
+      server: { sendError },
+    } = context;
+    try {
+      return await Promise.all(
+        flow(
+          filter((service) => includes(service.type, NodeServiceCategories)),
+          map((nodeService) =>
+            provisionAuth0SystemClient(
+              organization.didDoc.id,
+              organization.profile,
+              nodeService,
+              activatedServiceIds.includes(nodeService.id)
+            )
+          )
+        )(services)
+      );
+    } catch (error) {
+      const message = 'Error Provisioning Auth0 Apps';
+      const messageContext = {
+        did: organization.didDoc.id,
+        newServices: services,
+      };
+      log.error({ err: error, ...messageContext }, message);
+      sendError(error, { ...messageContext, message });
+      return [];
+    }
+  };
+
+module.exports = {
+  initProvisionAuth0Clients,
+};

package/src/entities/organization-services/adapters/update-blockchain-permissions-from-permitted-services.js

@@ -0,0 +1,118 @@
+const {
+  isEmpty,
+  values,
+  pullAll,
+  flatten,
+  map,
+  uniq,
+  flow,
+  compact,
+} = require('lodash/fp');
+const {
+  initPermissions,
+  AddressScopePermissions,
+} = require('@verii/contract-permissions');
+const { ServiceCategories } = require('@verii/organizations-registry');
+
+const ServiceCategoryToPermissions = {
+  [ServiceCategories.CredentialAgentOperator]: [],
+  [ServiceCategories.HolderAppProvider]: [],
+  [ServiceCategories.NodeOperator]: [],
+  [ServiceCategories.IdDocumentIssuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialIdentityIssue,
+  ],
+  [ServiceCategories.NotaryIdDocumentIssuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialIdentityIssue,
+  ],
+  [ServiceCategories.ContactIssuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialContactIssue,
+  ],
+  [ServiceCategories.NotaryContactIssuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialContactIssue,
+  ],
+  [ServiceCategories.IdentityIssuer]: [],
+  [ServiceCategories.Inspector]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialInspect,
+  ],
+  [ServiceCategories.Issuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialIssue,
+  ],
+  [ServiceCategories.NotaryIssuer]: [
+    AddressScopePermissions.TransactionsWrite,
+    AddressScopePermissions.CredentialRevoke,
+    AddressScopePermissions.CredentialIssue,
+  ],
+};
+
+const mapPermissionsToServiceTypes = (permittedVelocityServiceCategories) => {
+  if (isEmpty(permittedVelocityServiceCategories)) {
+    return {
+      permissionsToAdd: [],
+      permissionsToRemove: values(AddressScopePermissions),
+    };
+  }
+
+  const permissionsOfCategories = flow(
+    map((serviceCategory) => {
+      return ServiceCategoryToPermissions[serviceCategory];
+    }),
+    flatten,
+    uniq,
+    compact
+  )(permittedVelocityServiceCategories);
+  const permissionsToAdd = permissionsOfCategories;
+  const permissionsToRemove = pullAll(
+    permissionsOfCategories,
+    values(AddressScopePermissions)
+  );
+
+  return {
+    permissionsToAdd,
+    permissionsToRemove,
+  };
+};
+
+const updateBlockchainPermissionsFromPermittedServices = async (
+  { organization },
+  ctx
+) => {
+  const { config, rpcProvider } = ctx;
+  const { rootPrivateKey, permissionsContractAddress } = config;
+  const {
+    profile: { permittedVelocityServiceCategory },
+    ids: { ethereumAccount: primary },
+  } = organization;
+
+  const permissionContractClient = await initPermissions(
+    {
+      privateKey: rootPrivateKey,
+      contractAddress: permissionsContractAddress,
+      rpcProvider,
+    },
+    ctx
+  );
+
+  const { permissionsToAdd, permissionsToRemove } =
+    mapPermissionsToServiceTypes(permittedVelocityServiceCategory);
+
+  await permissionContractClient.updateAddressScopes({
+    address: primary,
+    scopesToAdd: permissionsToAdd,
+    scopesToRemove: permissionsToRemove,
+  });
+};
+
+module.exports = {
+  updateBlockchainPermissionsFromPermittedServices,
+};

package/src/entities/organization-services/domains/activate-services.js

@@ -0,0 +1,12 @@
+const { map } = require('lodash/fp');
+
+const activateServices = (did, services, { headers, config: { isProd } }) => {
+  if (!isProd && headers['x-auto-activate'] !== '0') {
+    return map('id', services);
+  }
+
+  return [];
+};
+module.exports = {
+  activateServices,
+};