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

package/src/controllers/organizations/full/controller.js

@@ -0,0 +1,285 @@
+/*
+ * 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 { map } = require('lodash/fp');
+const { wrapValidationError } = require('@verii/validation');
+const {
+  RegistrarScopes,
+  buildFullOrganizationResponse,
+  buildProfileResponse,
+  initCreateOrganization,
+  initTransformOrganizationFilter,
+  validateProfileName,
+  validateProfileWebsite,
+  verifyProfileWebsiteUnique,
+} = require('../../../entities');
+const {
+  verifyUserOrganizationReadAuthorized,
+  verifyUserOrganizationWriteAuthorized,
+} = require('../../../plugins/authorization');
+const { registeredCredentialTypesPreHandler } = require('../plugins');
+const {
+  invitationCodePropertySchema,
+  addKeyBodySchema,
+} = require('../schemas');
+
+const fullOrganizationController = async (fastify) => {
+  const transformToFinder = initTransformOrganizationFilter();
+  const createOrganization = initCreateOrganization(fastify);
+
+  fastify
+    .get(
+      '/',
+      {
+        onRequest: [
+          fastify.verifyAccessToken([
+            RegistrarScopes.ReadOrganizations,
+            RegistrarScopes.AdminOrganizations,
+          ]),
+        ],
+        preHandler: [verifyUserOrganizationReadAuthorized],
+        schema: fastify.autoSchema({
+          security: [
+            {
+              RegistrarOAuth2: [
+                RegistrarScopes.ReadOrganizations,
+                RegistrarScopes.AdminOrganizations,
+              ],
+            },
+          ],
+          querystring: { $ref: 'organization-search-query-params#' },
+          response: {
+            200: {
+              type: 'object',
+              properties: {
+                result: {
+                  type: 'array',
+                  items: {
+                    $ref: 'https://velocitycareerlabs.io/full-organization.json#',
+                  },
+                },
+              },
+            },
+          },
+        }),
+      },
+      async (req) => {
+        const { repos, query } = req;
+        const organizations = await repos.organizations.find(
+          transformToFinder(query)
+        );
+        return {
+          result: map(
+            (organization) => buildFullOrganizationResponse({ organization }),
+            organizations
+          ),
+        };
+      }
+    )
+    .get(
+      '/:did',
+      {
+        onRequest: fastify.verifyAccessToken([
+          RegistrarScopes.ReadOrganizations,
+          RegistrarScopes.AdminOrganizations,
+        ]),
+        preHandler: [verifyUserOrganizationReadAuthorized],
+        schema: fastify.autoSchema({
+          security: [
+            {
+              RegistrarOAuth2: [
+                RegistrarScopes.ReadOrganizations,
+                RegistrarScopes.AdminOrganizations,
+              ],
+            },
+          ],
+          params: {
+            type: 'object',
+            properties: {
+              did: {
+                type: 'string',
+              },
+            },
+          },
+          response: {
+            200: {
+              $ref: 'https://velocitycareerlabs.io/full-organization.json#',
+            },
+          },
+        }),
+      },
+      async ({ repos, params }) => {
+        const organization = await repos.organizations.findOneByDid(params.did);
+        return buildFullOrganizationResponse({ organization });
+      }
+    )
+    .post(
+      '/',
+      {
+        onRequest: fastify.verifyAccessToken([
+          RegistrarScopes.AdminOrganizations,
+          RegistrarScopes.WriteOrganizations,
+        ]),
+        preHandler: [
+          verifyUserOrganizationWriteAuthorized,
+          validateFullOrganizationBody,
+          registeredCredentialTypesPreHandler,
+        ],
+        schema: fastify.autoSchema({
+          security: [
+            {
+              RegistrarOAuth2: [
+                RegistrarScopes.WriteOrganizations,
+                RegistrarScopes.AdminOrganizations,
+              ],
+            },
+          ],
+          body: {
+            type: 'object',
+            properties: {
+              profile: {
+                $ref: 'organization-profile-creation#',
+              },
+              serviceEndpoints: {
+                type: 'array',
+                items: { $ref: 'create-did-service#' },
+              },
+              invitationCode: invitationCodePropertySchema,
+              byoDid: {
+                type: 'string',
+                pattern: '^did:web:[A-Za-z0-9._:?=&%;-]+$',
+              },
+              keys: {
+                type: 'array',
+                items: addKeyBodySchema,
+              },
+            },
+            required: ['profile'],
+          },
+          response: {
+            201: {
+              allOf: [
+                {
+                  $ref: 'https://velocitycareerlabs.io/full-organization.json#',
+                },
+                {
+                  type: 'object',
+                  properties: {
+                    keys: {
+                      type: 'array',
+                      items: { $ref: 'did-key#' },
+                    },
+                    authClients: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          type: { type: 'string' },
+                          clientType: { type: 'string' },
+                          clientId: { type: 'string' },
+                          clientSecret: { type: 'string' },
+                          serviceId: { type: 'string' },
+                        },
+                      },
+                    },
+                    messageCode: {
+                      type: 'string',
+                    },
+                  },
+                },
+              ],
+              required: ['didDoc', 'profile', 'keys'],
+            },
+            400: { $ref: 'error#' },
+          },
+        }),
+      },
+      async (req, reply) => {
+        const {
+          body: {
+            serviceEndpoints,
+            invitationCode,
+            byoDid,
+            profile,
+            keys: byoKeys,
+          },
+        } = req;
+
+        const { organization, keys, keyPairs, authClients, messageCode } =
+          await createOrganization(
+            {
+              byoDid,
+              byoKeys,
+              serviceEndpoints,
+              invitationCode,
+              profile,
+            },
+            req
+          );
+        reply.code(201);
+        return buildFullOrganizationResponse({
+          organization,
+          profile: buildProfileResponse(organization, true),
+          keys,
+          keyPairs,
+          authClients,
+          messageCode,
+        });
+      }
+    );
+};
+
+const validateFullOrganizationBody = async (req) => {
+  const schema =
+    req.config.isProd || req.headers['x-validate-kyb-profile'] === '1'
+      ? newKybFullOrganizationSchema
+      : newFullOrganizationSchema;
+
+  const validate = req.compileValidationSchema(schema, 'body');
+
+  if (!validate(req.body)) {
+    throw wrapValidationError(validate.errors, 'body');
+  }
+
+  const { profile } = req.body;
+  await validateProfileName(profile.name, null, req);
+  validateProfileWebsite({ profile });
+  await verifyProfileWebsiteUnique({ profile }, req);
+};
+
+const buildNewFullOrganizationSchema = (profileRef) => ({
+  type: 'object',
+  properties: {
+    profile: {
+      $ref: profileRef,
+    },
+    serviceEndpoints: {
+      type: 'array',
+      items: { $ref: 'create-did-service#' },
+    },
+    invitationCode: invitationCodePropertySchema,
+  },
+  required: ['profile'],
+});
+
+const newFullOrganizationSchema = buildNewFullOrganizationSchema(
+  'organization-profile-creation#'
+);
+const newKybFullOrganizationSchema = buildNewFullOrganizationSchema(
+  'organization-kyb-profile-creation#'
+);
+
+module.exports = fullOrganizationController;

package/src/controllers/organizations/plugins.js

@@ -0,0 +1,21 @@
+const { map } = require('lodash/fp');
+
+const loadCredentialTypes = async (req) => {
+  const allCredentialSchemas = await req.repos.credentialSchemas.find(
+    { filter: {} },
+    { credentialType: 1, _id: 0 }
+  );
+  return map('credentialType', allCredentialSchemas);
+};
+
+const registeredCredentialTypesPreHandler = async (req) => {
+  // eslint-disable-next-line better-mutation/no-mutation
+  req.registeredCredentialTypes = await loadCredentialTypes(req);
+};
+
+const CredentialTypesPlugin = (fastify, options, next) => {
+  fastify.decorateRequest('registeredCredentialTypes', null);
+  next();
+};
+
+module.exports = { CredentialTypesPlugin, registeredCredentialTypesPreHandler };

package/src/controllers/organizations/schemas/add-key-body.schema.json

@@ -0,0 +1,35 @@
+{
+  "title": "add-key-body",
+  "$id": "https://velocitycareerlabs.io/add-key-body.json",
+  "type": "object",
+  "description": "payload for adding a key to an organization in the registrar",
+  "additionalProperties": true,
+  "properties": {
+    "kidFragment": {
+      "type": "string",
+      "pattern": "^#[a-zA-Z0-9-_:?=&;]+$"
+    },
+    "purposes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "algorithm": {
+      "type": "string",
+      "enum": [
+        "SECP256K1"
+      ],
+      "default": "SECP256K1"
+    },
+    "custodied": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "purposes",
+    "algorithm"
+  ]
+}

package/src/controllers/organizations/schemas/create-did-service.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-did-service",
+  "title": "create-did-service",
+  "additionalProperties": true,
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "VlcCredentialAgentOperator_v1",
+        "VlcCareerIssuer_v1",
+        "VlcIdentityIssuer_v1",
+        "VlcNotaryIssuer_v1",
+        "VlcInspector_v1",
+        "VlcNodeOperator_v1",
+        "VlcIdDocumentIssuer_v1",
+        "VlcNotaryIdDocumentIssuer_v1",
+        "VlcContactIssuer_v1",
+        "VlcNotaryContactIssuer_v1",
+        "VlcHolderAppProvider_v1",
+        "VlcWebWalletProvider_v1"
+      ],
+      "minLength": 1,
+      "maxLength": 30
+    },
+    "id": {
+      "type": "string",
+      "description": "Just the id fragment, without the hash"
+    },
+    "serviceEndpoint": {
+      "type": "string"
+    },
+    "logoUrl": {
+      "type": "string",
+      "format": "uri"
+    },
+    "playStoreUrl": {
+      "type": "string",
+      "format": "uri"
+    },
+    "appleAppStoreUrl": {
+      "type": "string",
+      "format": "uri"
+    },
+    "appleAppId": {
+      "type": "string"
+    },
+    "googlePlayId": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "supportedExchangeProtocols": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "VN_API",
+          "OPENID4VC"
+        ]
+      },
+      "minItems": 1
+    }
+  },
+  "required": [
+    "id"
+  ]
+}

package/src/controllers/organizations/schemas/did-key.schema.json

@@ -0,0 +1,178 @@
+{
+  "$id": "did-key",
+  "title": "did-key",
+  "type": "object",
+  "description": "A registered organization's key",
+  "properties": {
+    "kidFragment": {
+      "type": "string",
+      "pattern": "^#[a-zA-Z0-9-_:?=&;]+$",
+      "description": "the fragment of the key's id value within the did document. Includes the starting #. The full kid used will be {did}{kidFragment}"
+    },
+    "purposes": {
+      "type": "array",
+      "description": "the purposes of the key",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "DLT_TRANSACTIONS",
+          "ISSUING_METADATA",
+          "EXCHANGES"
+        ]
+      }
+    },
+    "algorithm": {
+      "type": "string",
+      "enum": [
+        "SECP256K1"
+      ],
+      "deprecated": true,
+      "description": "the algorithm used",
+      "default": "SECP256K1"
+    },
+    "encoding": {
+      "type": "string",
+      "deprecated": true,
+      "description": "the encoding of the `key` value. Always set to \"hex\". \nDeprecated"
+    },
+    "key": {
+      "type": "string",
+      "pattern": "^#.+$",
+      "description": "hex representation of the private key"
+    },
+    "didDocumentKey": {
+      "$ref": "#/definitions/PublicKey"
+    },
+    "custodied": {
+      "type": "boolean",
+      "description": "indicates the key is custodied on the server"
+    }
+
+  },
+  "required": [
+    "kidFragment",
+    "purposes",
+    "algorithm"
+  ],
+  "definitions": {
+    "EcdsaSecp256k1VerificationKey2019": {
+      "type": "object",
+      "title": "EcdsaSecp256k1VerificationKey2019",
+      "description": "https://w3c.github.io/did-core-registries/#EcdsaSecp256k1VerificationKey2019",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "title": "Public Key ID",
+          "type": "string"
+        },
+        "type": {
+          "title": "Public Key Type",
+          "type": "string",
+          "enum": [
+            "EcdsaSecp256k1VerificationKey2019"
+          ]
+        },
+        "controller": {
+          "title": "Controller",
+          "description": "https://w3c.github.io/did-core-registries/#controller",
+          "type": "string"
+        },
+        "publicKeyMultibase": {
+          "title": "Public Key Base58",
+          "description": "https://w3c.github.io/did-core-registries/#publicKeyBase58",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "controller"
+      ]
+    },
+    "Ed25519VerificationKey2018": {
+      "type": "object",
+      "title": "EcdsaSecp256k1VerificationKey2019",
+      "description": "https://w3c.github.io/did-core-registries/#EcdsaSecp256k1VerificationKey2019",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "title": "Public Key ID",
+          "type": "string"
+        },
+        "type": {
+          "title": "Public Key Type",
+          "type": "string",
+          "enum": [
+            "Ed25519VerificationKey2018"
+          ]
+        },
+        "controller": {
+          "title": "Controller",
+          "description": "https://w3c.github.io/did-core-registries/#controller",
+          "type": "string"
+        },
+        "publicKeyMultibase": {
+          "title": "Public Key Base58",
+          "description": "https://w3c.github.io/did-core-registries/#publicKeyBase58",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "controller"
+      ]
+    },
+    "JsonWebKey2020": {
+      "type": "object",
+      "title": "JsonWebKey2020",
+      "description": "https://w3c.github.io/did-core-registries/#JwsVerificationKey2020",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "title": "Public Key ID",
+          "type": "string"
+        },
+        "type": {
+          "title": "Public Key Type",
+          "type": "string",
+          "enum": [
+            "JsonWebKey2020"
+          ]
+        },
+        "controller": {
+          "title": "Controller",
+          "description": "https://w3c.github.io/did-core-registries/#controller",
+          "type": "string"
+        },
+        "publicKeyJwk": {
+          "title": "Public Key JWK",
+          "description": "https://w3c.github.io/did-core-registries/#publicKeyJwk",
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "controller"
+      ]
+    },
+    "PublicKey": {
+      "title": "Public Key",
+      "description": "A public key is a verification method. Public keys are used for digital signatures, encryption and other cryptographic operations, which in turn are the basis for purposes such as authentication.",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/EcdsaSecp256k1VerificationKey2019"
+        },
+        {
+          "$ref": "#/definitions/Ed25519VerificationKey2018"
+        },
+        {
+          "$ref": "#/definitions/JsonWebKey2020"
+        }
+      ]
+    }
+  }
+}

package/src/controllers/organizations/schemas/full-organization.schema.json

@@ -0,0 +1,35 @@
+{
+  "title": "full-organization",
+  "$id": "https://velocitycareerlabs.io/full-organization.json",
+  "description": "represents a full organization including didDoc if custodied",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "didDoc": {
+      "$ref": "did-doc#"
+    },
+    "profile": {
+      "$ref": "organization-profile#"
+    },
+    "ids": {
+      "$ref": "https://velocitycareerlabs.io/organization-ids.json#"
+    },
+    "custodied": {
+      "type": "boolean"
+    },
+    "activatedServiceIds": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "services": {
+      "type": "array",
+      "items": {
+        "$ref": "https://velocitycareerlabs.io/organization-registry-service-response.schema.json#"
+      }
+    }
+  }
+}

package/src/controllers/organizations/schemas/index.js

@@ -0,0 +1,33 @@
+const addKeyBodySchema = require('./add-key-body.schema.json');
+const organizationIdsSchema = require('./organization-ids.schema.json');
+const invitationCodePropertySchema = require('./invitationCodeProperty.schema.json');
+const organizationRegistryServiceResponseSchema = require('./organization-registry-service-response.schema.json');
+const fullOrganizationSchema = require('./full-organization.schema.json');
+const createDidServiceSchema = require('./create-did-service.schema.json');
+const organizationProfileCreationSchema = require('./organization-profile-creation.schema.json');
+const organizationKybProfileCreationSchema = require('./organization-kyb-profile-creation.schema.json');
+const organizationProfileUpdateSchema = require('./organization-profile-update.schema.json');
+const organizationSearchQueryParamsSchema = require('./organization.search.query-params.schema.json');
+const organizationSearchQueryProfileParamsSchema = require('./organization.search-profile.query-params.schema.json');
+const organizationProfileVerifiableCredentialSchema = require('./organization-profile-verifiable-credential.schema.json');
+const organizationVerifiedProfileSchema = require('./organization-verified-profile.schema.json');
+const didKeySchema = require('./did-key.schema.json');
+const organizationServiceSchema = require('./organization-service.schema.json');
+
+module.exports = {
+  addKeyBodySchema,
+  invitationCodePropertySchema,
+  organizationIdsSchema,
+  organizationRegistryServiceResponseSchema,
+  fullOrganizationSchema,
+  createDidServiceSchema,
+  organizationProfileCreationSchema,
+  organizationKybProfileCreationSchema,
+  organizationProfileUpdateSchema,
+  organizationSearchQueryParamsSchema,
+  organizationSearchQueryProfileParamsSchema,
+  organizationProfileVerifiableCredentialSchema,
+  organizationVerifiedProfileSchema,
+  didKeySchema,
+  organizationServiceSchema,
+};

package/src/controllers/organizations/schemas/invitationCodeProperty.schema.json

@@ -0,0 +1,3 @@
+{
+  "type": "string"
+}

package/src/controllers/organizations/schemas/organization-ids.schema.json

@@ -0,0 +1,34 @@
+{
+  "title": "organization-ids",
+  "$id": "https://velocitycareerlabs.io/organization-ids.json",
+  "type": "object",
+  "description": "represents the ids associated with an organization",
+  "properties": {
+    "tokenAccountId": {
+      "type": "string"
+    },
+    "stakesAccountId": {
+      "type": "string"
+    },
+    "fineractClientId": {
+      "type": "string"
+    },
+    "escrowAccountId": {
+      "type": "string"
+    },
+    "ethereumAccount": {
+      "type": "string"
+    },
+    "stripeConnectAccountId": {
+      "type": "string"
+    },
+    "did": {
+      "type": "string"
+    },
+    "brokerClientId": {
+      "type": "string"
+    }
+  },
+  "required": [
+  ]
+}