@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

package/modules/use-cases/create-entity-from-credential.js

@@ -0,0 +1,113 @@
+const Boom = require('@hapi/boom');
+const { Module } = require('../module');
+
+const sameId = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null &&
+    String(a) === String(b);
+
+/**
+ * Creates (or finds) the entity for a credential the caller already holds:
+ * the v1 `POST /api/entity`. The owner and organization follow the scope of
+ * `entityType`, exactly as an authorization does (ADR-056 §3.2, §3.6), so the
+ * owner is decided by `AuthorizeEntityForUser.resolveOwnership` and never by
+ * `user.getId()`. Whatever that resolution refuses (a missing identity, and
+ * an organization-level connection by a non-admin) is refused here too.
+ *
+ * The credential must belong to that owner: an organization entity is built
+ * on the organization's credential, an individual one on the person's own.
+ */
+class CreateEntityFromCredential {
+    /**
+     * @param {Object} params
+     * @param {import('./authorize-entity-for-user').AuthorizeEntityForUser} params.authorizeEntityForUser
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     * @param {Object} params.credentialRepository
+     * @param {Array<Object>} params.moduleDefinitions
+     * @param {Function} [params.createModule] - builds a Module; injectable for tests
+     */
+    constructor({
+        authorizeEntityForUser,
+        processAuthorizationCallback,
+        credentialRepository,
+        moduleDefinitions,
+        createModule,
+    }) {
+        this.authorizeEntityForUser = authorizeEntityForUser;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.credentialRepository = credentialRepository;
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.createModule = createModule || ((params) => Module.create(params));
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {string} params.credentialId
+     * @returns {Promise<Object>} the persisted entity
+     */
+    async execute({ user, entityType, credentialId }) {
+        const definition = this.moduleDefinitions.find(
+            (def) =>
+                def.moduleName === entityType ||
+                (typeof def.getName === 'function' && def.getName() === entityType)
+        );
+        if (!definition) {
+            throw Boom.badRequest(`Unknown entity type ${entityType}`, {
+                code: 'ENTITY_TYPE_NOT_FOUND',
+            });
+        }
+
+        const ownership = this.authorizeEntityForUser.resolveOwnership({
+            user,
+            entityType,
+        });
+
+        const credential =
+            await this.credentialRepository.findCredentialById(credentialId);
+        // A missing credential and someone else's are the same answer, so ids
+        // cannot be probed.
+        if (!credential || !sameId(credential.userId, ownership.ownerId)) {
+            throw Boom.badRequest('Invalid credential ID', {
+                code: 'INVALID_CREDENTIAL',
+            });
+        }
+
+        // Built for the owner, with the credential loaded (the repository
+        // returns its tokens flat; a Module reads them from `data`), so the
+        // API can call the provider and a token refresh during
+        // getEntityDetails updates the owner's credential.
+        const { id, userId, externalId, authIsValid, ...data } = credential;
+        const module = await this.createModule({
+            userId: ownership.ownerId,
+            definition,
+            entity: {
+                credential: { id, userId, externalId, authIsValid, data },
+            },
+        });
+        const entityDetails =
+            await definition.requiredAuthMethods.getEntityDetails(
+                module.api,
+                null,
+                null,
+                ownership.ownerId
+            );
+        Object.assign(
+            entityDetails.details,
+            module.apiParamsFromEntity(module.api)
+        );
+
+        return this.processAuthorizationCallback.findOrCreateEntity(
+            entityDetails,
+            definition.moduleName,
+            credential.id,
+            {
+                scope: ownership.scope,
+                organizationId: ownership.organizationId,
+                legacyOrgId: ownership.legacyOrgId,
+            }
+        );
+    }
+}
+
+module.exports = { CreateEntityFromCredential };

package/modules/use-cases/entity-operations-for-user.js

@@ -0,0 +1,162 @@
+const Boom = require('@hapi/boom');
+const {
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+} = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
+const { assertCanManage } = require('./manage-access');
+
+/**
+ * Management API v2 entity operations. Each one starts from
+ * GetEntityModuleForUser, so ownership is checked the same way everywhere
+ * (missing or foreign entity = 404).
+ */
+
+/**
+ * The entities the caller may see in the active organization (ADR-056 §3.4,
+ * §3.6): the organization's own, and the caller's individual ones by the
+ * visibility rule. Each carries `tenancy` ({scope, owner, organizationId,
+ * access}); the stored entity is otherwise untouched.
+ */
+class ListEntitiesForUser {
+    constructor({ moduleRepository, scopePolicy }) {
+        this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    }
+
+    /**
+     * @param {Object} user - authenticated User
+     * @param {{scope?: string, owner?: string}} [filters] - `?scope=` and `?owner=`
+     */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const entities = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
+        );
+        const listed = [];
+        for (const entity of Array.isArray(entities) ? entities : []) {
+            // The query is the filter; this is the same rule applied again,
+            // so a repository that returns too much cannot widen the list.
+            const tenancy = describeRecord(entity, ctx, 'entity');
+            if (tenancy && matchesListFilters(tenancy, filters)) {
+                listed.push({ ...entity, tenancy });
+            }
+        }
+        return listed;
+    }
+}
+
+/** One entity the caller may use, with its `tenancy`. */
+class GetEntityForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user) {
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        return {
+            ...entity,
+            tenancy: this.getEntityModuleForUser.describe(entity, user),
+        };
+    }
+}
+
+/** Runs the module's testAuthRequest against the stored credential. */
+class TestEntityAuthForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    /** @returns {Promise<boolean>} */
+    async execute(entityId, user) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return Boolean(await module.testAuth());
+    }
+}
+
+/** The module's entity options (e.g. objects a user can pick). */
+class GetEntityOptionsForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return module.getEntityOptions();
+    }
+}
+
+/** Refreshes the module's entity options with caller input, then returns them. */
+class RefreshEntityOptionsForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user, options = {}) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return module.refreshEntityOptions(options);
+    }
+}
+
+/**
+ * Deletes an entity the caller may manage (the owner; for an organization
+ * entity, an organization admin). Refuses with 409 while integrations still
+ * use it, so an integration never points at a missing entity. The credential
+ * is left alone (others may share it); delete it through /api/v2/credentials.
+ */
+class DeleteEntityForUser {
+    constructor({ getEntityModuleForUser, moduleRepository, integrationRepository }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+        this.moduleRepository = moduleRepository;
+        this.integrationRepository = integrationRepository;
+    }
+
+    async execute(entityId, user) {
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        assertCanManage(
+            this.getEntityModuleForUser.describe(entity, user)?.access,
+            `entity ${entity.id}`
+        );
+        const integrations =
+            (await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            )) || [];
+        if (integrations.length > 0) {
+            throw Boom.conflict(
+                `Entity ${entity.id} is used by ${integrations.length} integration(s); delete them first`,
+                {
+                    code: 'ENTITY_IN_USE',
+                    details: {
+                        integrationIds: integrations.map((i) => String(i.id)),
+                    },
+                }
+            );
+        }
+        await this.moduleRepository.deleteEntity(entity.id);
+    }
+}
+
+module.exports = {
+    ListEntitiesForUser,
+    GetEntityForUser,
+    TestEntityAuthForUser,
+    GetEntityOptionsForUser,
+    RefreshEntityOptionsForUser,
+    DeleteEntityForUser,
+};

package/modules/use-cases/entity-types.js

@@ -0,0 +1,139 @@
+const Boom = require('@hapi/boom');
+const { ModuleConstants } = require('../ModuleConstants');
+const { usedByOf } = require('../entity-type-registry');
+
+const AUTH_TYPE_BY_REQUESTER = {
+    [ModuleConstants.authType.oauth2]: 'oauth2',
+    [ModuleConstants.authType.oauth1]: 'oauth1',
+    [ModuleConstants.authType.apiKey]: 'api-key',
+    [ModuleConstants.authType.basic]: 'basic',
+};
+
+const callIfFunction = (target, name) =>
+    typeof target?.[name] === 'function' ? target[name]() : undefined;
+
+/** Number of authorization steps a module declares (1 unless multi-step). */
+function getAuthStepCount(definition) {
+    const count = callIfFunction(definition, 'getAuthStepCount');
+    return Number.isInteger(count) && count > 0 ? count : 1;
+}
+
+/**
+ * Public description of an API module (an "entity type"). Reads only the
+ * definition: display metadata, auth type and step count. Never credentials
+ * or env values.
+ */
+function describeEntityType(definition, typeName = definition.moduleName) {
+    const stepCount = getAuthStepCount(definition);
+    const display = definition.display || {};
+    const description = {
+        type: typeName,
+        name:
+            callIfFunction(definition, 'getDisplayName') ??
+            display.label ??
+            display.name ??
+            typeName,
+        authType:
+            callIfFunction(definition, 'getAuthType') ??
+            AUTH_TYPE_BY_REQUESTER[definition.API?.requesterType] ??
+            'custom',
+        isMultiStep: stepCount > 1,
+        stepCount,
+    };
+    const text = callIfFunction(definition, 'getDescription') ?? display.description;
+    if (text) description.description = text;
+    const capabilities = callIfFunction(definition, 'getCapabilities');
+    if (capabilities !== undefined) description.capabilities = capabilities;
+    return description;
+}
+
+function findDefinition(moduleDefinitions, entityType) {
+    const definition = moduleDefinitions.find(
+        (def) => def.moduleName === entityType
+    );
+    if (!definition) {
+        throw Boom.notFound(`Entity type '${entityType}' not found`, {
+            code: 'ENTITY_TYPE_NOT_FOUND',
+        });
+    }
+    return definition;
+}
+
+/**
+ * With a scope policy the entry also says which scope a new connection gets
+ * and which a request may choose (ADR-056 §3.1), so a UI can offer the choice.
+ * `global` is never offered: a tenant request cannot create one.
+ */
+const scopeOf = (scopePolicy, name, user) => {
+    if (!scopePolicy) return {};
+    const { scope, source, allow } = scopePolicy.resolveScope({
+        entityType: name,
+        user,
+    });
+    return {
+        scope: {
+            default: scope,
+            allow: allow.filter((value) => value !== 'global'),
+            source,
+        },
+    };
+};
+
+const describeEntry = (name, entry, scopePolicy, user) => ({
+    // The registry key is the name the API uses, whatever the definition spells.
+    ...describeEntityType(entry.definition, name),
+    usedBy: usedByOf(entry),
+    ...scopeOf(scopePolicy, name, user),
+});
+
+function requireRegistry(entityTypeRegistry) {
+    if (!(entityTypeRegistry instanceof Map)) {
+        throw new TypeError('entityTypeRegistry is required (see getEntityTypeRegistry)');
+    }
+    return entityTypeRegistry;
+}
+
+/**
+ * Lists the entity types this app can authorize: registry entries plus every
+ * module an integration binds (ADR-059). `usedBy` names the integrations that
+ * bind each type; it is empty for a registry-only type.
+ */
+class ListEntityTypes {
+    constructor({ entityTypeRegistry, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
+    }
+
+    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
+    async execute({ user } = {}) {
+        return [...this.registry]
+            .map(([name, entry]) => describeEntry(name, entry, this.scopePolicy, user))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+}
+
+/** Describes one entity type, looked up by its registry key; 404 when absent. */
+class GetEntityType {
+    constructor({ entityTypeRegistry, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
+    }
+
+    async execute(entityType, { user } = {}) {
+        const entry = this.registry.get(entityType);
+        if (!entry) {
+            throw Boom.notFound(`Entity type '${entityType}' not found`, {
+                code: 'ENTITY_TYPE_NOT_FOUND',
+            });
+        }
+        return describeEntry(entityType, entry, this.scopePolicy, user);
+    }
+}
+
+module.exports = {
+    ListEntityTypes,
+    GetEntityType,
+    describeEntityType,
+    getAuthStepCount,
+    findDefinition,
+};