@friggframework/core 2.0.0--canary.679.a2bcc2f.0 → 2.0.0--canary.686.87e9875.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) => new Module(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 = 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

@@ -1,4 +1,11 @@
 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
@@ -6,29 +13,55 @@ const Boom = require('@hapi/boom');
  * (missing or foreign entity = 404).
  */
 
-/** The caller's connected entities. */
+/**
+ * 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 }) {
+    constructor({ moduleRepository, scopePolicy }) {
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
-    /** @param {Object} user - authenticated User */
-    async execute(user) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            user.getId()
+    /**
+     * @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')
         );
-        return Array.isArray(entities) ? entities : [];
+        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 owns. */
+/** One entity the caller may use, with its `tenancy`. */
 class GetEntityForUser {
     constructor({ getEntityModuleForUser }) {
         this.getEntityModuleForUser = getEntityModuleForUser;
     }
 
     async execute(entityId, user) {
-        return this.getEntityModuleForUser.loadOwnedEntity(entityId, user);
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        return {
+            ...entity,
+            tenancy: this.getEntityModuleForUser.describe(entity, user),
+        };
     }
 }
 
@@ -79,10 +112,10 @@ class RefreshEntityOptionsForUser {
 }
 
 /**
- * Deletes an entity the caller owns. 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.
+ * 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 }) {
@@ -96,6 +129,10 @@ class DeleteEntityForUser {
             entityId,
             user
         );
+        assertCanManage(
+            this.getEntityModuleForUser.describe(entity, user)?.access,
+            `entity ${entity.id}`
+        );
         const integrations =
             (await this.integrationRepository.findIntegrationsByEntityId(
                 entity.id

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

@@ -59,10 +59,31 @@ function findDefinition(moduleDefinitions, entityType) {
     return definition;
 }
 
-const describeEntry = (name, entry) => ({
+/**
+ * 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) {
@@ -78,31 +99,34 @@ function requireRegistry(entityTypeRegistry) {
  * bind each type; it is empty for a registry-only type.
  */
 class ListEntityTypes {
-    constructor({ entityTypeRegistry }) {
+    constructor({ entityTypeRegistry, scopePolicy }) {
         this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute() {
+    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
+    async execute({ user } = {}) {
         return [...this.registry]
-            .map(([name, entry]) => describeEntry(name, entry))
+            .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 }) {
+    constructor({ entityTypeRegistry, scopePolicy }) {
         this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute(entityType) {
+    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);
+        return describeEntry(entityType, entry, this.scopePolicy, user);
     }
 }
 

package/modules/use-cases/execute-entity-proxy-request.js

@@ -2,6 +2,8 @@ const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
 const { getTelemetry } = require('../../telemetry/telemetry-runtime');
 const { ProxyRequestError } = require('../proxy/proxy-errors');
+const { SCOPES } = require('../scope-resolution');
+const { grantsUse } = require('../scope-visibility');
 const { normalizeProxyPath, matchAllowRule } = require('../proxy/proxy-path');
 const {
     validateProxyRequest,
@@ -55,9 +57,11 @@ const authHeaderNamesOf = (api) =>
  * through its module with the stored credential, inside the limits the app
  * and the module set.
  *
- * Order of checks: request shape and size, path rules, entity ownership
- * (404), the module's allow-list (403, deny by default), credential
- * readiness (401), then the call through Requester._proxyRequest. Every call,
+ * Order of checks: request shape and size, path rules, entity visibility in
+ * the active organization (404), `use` access (403), the entity's scope
+ * against `managementApi.proxy.scopes` (403), the module's allow-list (403,
+ * deny by default), credential readiness (401), then the call through
+ * Requester._proxyRequest. Every call,
  * allowed or denied, writes one audit record and one usage count. Bodies,
  * headers, query values and the raw path are never logged.
  */
@@ -98,9 +102,14 @@ class ExecuteEntityProxyRequest {
             audit.requestBytes = validated.requestBytes;
             const path = normalizeProxyPath(validated.path);
 
+            // Visible in the active organization, or 404 (ADR-056 §3.6): the
+            // same clauses the v2 lists use, so a missing entity, another
+            // person's and one paired with another organization look alike.
             const { entity, definition, module } =
                 await this.getEntityModuleForUser.execute(entityId, user);
             audit.module = definition.moduleName;
+            this.assertProxyable(entityId, entity, definition, user);
+
             const credentialRef = entity.credential;
             const credentialId =
                 credentialRef && typeof credentialRef === 'object'
@@ -202,6 +211,44 @@ class ExecuteEntityProxyRequest {
         }
     }
 
+    /**
+     * ADR-056 §3.5: the caller needs `use` access to the entity in the active
+     * organization, and the entity's scope must be one the app lets the proxy
+     * accept. `access` and `scope` come from the description the v2 lists
+     * return (GetEntityModuleForUser.describe), never from a second rule.
+     *
+     * Both refusals are 403 PROXY_NOT_ALLOWED: the caller can already see the
+     * entity, so saying it exists leaks nothing. `details.reason` tells them
+     * apart ('access' or 'scope').
+     */
+    assertProxyable(entityId, entity, definition, user) {
+        const tenancy = this.getEntityModuleForUser.describe(entity, user);
+        if (!tenancy) {
+            // Not visible after all: the same 404 as a missing entity.
+            throw Boom.notFound(`Entity ${entityId} not found`, {
+                code: 'ENTITY_NOT_FOUND',
+            });
+        }
+        if (!grantsUse(tenancy.access)) {
+            throw new ProxyRequestError(
+                'PROXY_NOT_ALLOWED',
+                'Proxying through an entity needs use access to it; you can only view this one',
+                { module: definition.moduleName, reason: 'access' }
+            );
+        }
+        // Narrowest by default (§3.5): with no setting only individual
+        // entities are proxied, because proxying through a shared credential
+        // lets any member act on the organization's account.
+        const acceptedScopes = this.proxyConfig.scopes ?? [SCOPES.INDIVIDUAL];
+        if (!acceptedScopes.includes(tenancy.scope)) {
+            throw new ProxyRequestError(
+                'PROXY_NOT_ALLOWED',
+                `The entity proxy does not accept ${tenancy.scope} entities in this app`,
+                { module: definition.moduleName, reason: 'scope', scope: tenancy.scope }
+            );
+        }
+    }
+
     /** A module may pin its proxy base URL (string, or a function of the api). */
     resolveBaseUrl(definition, api) {
         const declared = definition.proxy?.baseUrl;

package/modules/use-cases/get-entities-for-user.js

@@ -1,8 +1,11 @@
 const { Module } = require('../module');
 const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+const { describeRecord, visibilityClauses } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntitiesForUser {
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
 
         this.definitionMap = new Map();
@@ -11,16 +14,24 @@ class GetEntitiesForUser {
         }
     }
 
-    async execute(userId) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            userId
+    /**
+     * The entities a `User` may see in the active organization (ADR-056 §3.6).
+     * @param {Object} user - authenticated User
+     */
+    async execute(user) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const found = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
+        );
+        const entities = (found || []).filter((entity) =>
+            describeRecord(entity, ctx, 'entity')
         );
 
         return entities.map((entity) => {
             const definition = this.definitionMap.get(entity.moduleName);
 
             const moduleInstance = new Module({
-                userId,
+                userId: entity.userId,
                 definition: definition,
                 entity: entity,
             });

package/modules/use-cases/get-entity-module-for-user.js

@@ -1,8 +1,14 @@
 const Boom = require('@hapi/boom');
+const { describeRecord } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
+const { isEntityNotFound } = require('../repositories/entity-not-found');
 
 /**
  * True when `user` may act on records owned by `ownerId`. Uses the User
  * domain object's rule (individual or organisation user model) when present.
+ * This is the owner-only rule: it ignores the organization a record belongs
+ * to, so it no longer decides access to an entity or an integration
+ * (modules/scope-visibility.js does). Credentials still use it.
  * @param {Object} user - authenticated User (or a plain { getId } double)
  * @param {string|number} ownerId
  */
@@ -30,8 +36,11 @@ class GetEntityModuleForUser {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {Array<Object>} params.moduleDefinitions
      * @param {Function} [params.createModule] - builds a Module; injectable for tests.
+     * @param {Object} [params.scopePolicy] - from createScopePolicy; with none the
+     *   app configures nothing (ADR-056 §3.1).
      */
-    constructor({ moduleRepository, moduleDefinitions, createModule }) {
+    constructor({ moduleRepository, moduleDefinitions, createModule, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions || [];
         this.createModule = createModule || defaultCreateModule;
@@ -61,26 +70,44 @@ class GetEntityModuleForUser {
         return { entity, definition, module };
     }
 
-    /** The entity record, or a 404 when it is missing or not the caller's. */
+    /**
+     * The entity record, or a 404 when it is missing or the caller may not use
+     * it: not theirs, or paired with another organization (ADR-056 §3.6). A
+     * `global` entity is never the tenant's to load.
+     */
     async loadOwnedEntity(entityId, user) {
         let entity = null;
         try {
             entity = await this.moduleRepository.findEntityById(entityId);
         } catch (error) {
-            // A malformed id (e.g. not an integer on Postgres) is "not found".
-            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+            // Every adapter throws for a missing row, and a malformed id (e.g.
+            // not an integer on Postgres) is "not found" too. Both must be the
+            // 404 another tenant's entity gets, or the status says which ids
+            // exist. Anything else is a real failure.
+            if (
+                isEntityNotFound(error) ||
+                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '')
+            ) {
                 entity = null;
             } else {
                 throw error;
             }
         }
-        if (!entity || !userOwns(user, entity.userId)) {
+        if (!entity || !this.describe(entity, user)) {
             throw Boom.notFound(`Entity ${entityId} not found`, {
                 code: 'ENTITY_NOT_FOUND',
             });
         }
         return entity;
     }
+
+    /**
+     * `{ scope, owner, organizationId, access }` of an entity to this caller,
+     * or null when they may not see it (§3.4).
+     */
+    describe(entity, user) {
+        return describeRecord(entity, this.scopePolicy.accessContext(user), 'entity');
+    }
 }
 
 module.exports = { GetEntityModuleForUser, userOwns };

package/modules/use-cases/get-entity-options-by-id.js

@@ -1,4 +1,5 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntityOptionsById {
     /**
@@ -6,9 +7,11 @@ class GetEntityOptionsById {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {} params.moduleDefinitions
      */
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -35,7 +38,7 @@ class GetEntityOptionsById {
 
         // Validate entity ownership
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
@@ -57,8 +60,11 @@ class GetEntityOptionsById {
             );
         }
 
+        // Built for the entity's OWNER, not the caller: a caller may use an
+        // organization's entity, and a token refresh during this call must
+        // update the owner's credential, not create one under the caller.
         const module = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-module.js

@@ -1,9 +1,12 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetModule {
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -32,7 +35,7 @@ class GetModule {
         // If User object provided, use ownsUserId to check linked users
         // Otherwise fall back to simple equality check
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
@@ -53,8 +56,11 @@ class GetModule {
             );
         }
 
+        // Built for the entity's OWNER, not the caller: a caller may use an
+        // organization's entity, and a token refresh during this call must
+        // update the owner's credential, not create one under the caller.
         const module = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/modules/use-cases/manage-access.js

@@ -0,0 +1,21 @@
+const Boom = require('@hapi/boom');
+const { ACCESS } = require('../scope-resolution');
+
+/**
+ * The one check behind every "may this caller change or delete it" gate
+ * (ADR-056 §3 permissions): the caller may use it but not manage it, so 403
+ * `ORG_ADMIN_REQUIRED`. `access` comes from describeRecord (entities,
+ * integrations) or scopePolicy.accessToOwnedBy (credentials).
+ *
+ * @param {string|null} access - ACCESS value
+ * @param {string} subject - e.g. `entity 5`, for the message
+ */
+function assertCanManage(access, subject) {
+    if (access !== ACCESS.MANAGE) {
+        throw Boom.forbidden(`You may use ${subject} but not change or delete it`, {
+            code: 'ORG_ADMIN_REQUIRED',
+        });
+    }
+}
+
+module.exports = { assertCanManage };