@friggframework/core 2.0.0--canary.681.2df9ef0.0 → 2.0.0--canary.682.cbca9e2.0

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

@@ -0,0 +1,59 @@
+/**
+ * Authorizes an entity for a caller: decides who will own it and in which
+ * organization (ADR-056 §3.2, §3.6), then runs the module's authorization.
+ * Shared by the v1 `POST /api/authorize` and the v2 authorize flow, so the
+ * owner is decided in one place and never by `user.primary`.
+ */
+class AuthorizeEntityForUser {
+    /**
+     * @param {Object} params
+     * @param {Object} params.scopePolicy - from createScopePolicy
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     */
+    constructor({ scopePolicy, processAuthorizationCallback }) {
+        this.scopePolicy = scopePolicy;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+    }
+
+    /**
+     * The scope, owner and organization a new entity of `entityType` gets for
+     * this caller. Throws a 400/403 when the request cannot have one.
+     *
+     * @param {{user: Object, entityType: string, scope?: string}} params
+     */
+    resolveOwnership({ user, entityType, scope }) {
+        return this.scopePolicy.resolveOwnership({
+            entityType,
+            requestScope: scope,
+            user,
+        });
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {Object} params.data - what the module's authorization needs
+     * @param {string} [params.scope] - the scope the request asks for
+     * @param {Object} [params.ownership] - from `resolveOwnership`, when the
+     *   caller needed it earlier (a multi-step flow does)
+     * @returns {Promise<{result: Object, ownership: Object}>} the callback's
+     *   `{ credential_id, entity_id, type }` and the ownership it ran with
+     */
+    async execute({ user, entityType, data, scope, ownership }) {
+        const resolved = ownership ?? this.resolveOwnership({ user, entityType, scope });
+        const result = await this.processAuthorizationCallback.execute(
+            resolved.ownerId,
+            entityType,
+            data,
+            {
+                scope: resolved.scope,
+                organizationId: resolved.organizationId,
+                legacyOrgId: resolved.legacyOrgId,
+            }
+        );
+        return { result, ownership: resolved };
+    }
+}
+
+module.exports = { AuthorizeEntityForUser };

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

@@ -1,4 +1,10 @@
 const Boom = require('@hapi/boom');
+const {
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+} = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 /**
  * Management API v2 entity operations. Each one starts from
@@ -6,29 +12,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,7 +111,7 @@ class RefreshEntityOptionsForUser {
 }
 
 /**
- * Deletes an entity the caller owns. Refuses with 409 while integrations
+ * Deletes an entity the caller may use. 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.

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

@@ -1,5 +1,6 @@
 const Boom = require('@hapi/boom');
 const { ModuleConstants } = require('../ModuleConstants');
+const { usedByOf } = require('../entity-type-registry');
 
 const AUTH_TYPE_BY_REQUESTER = {
     [ModuleConstants.authType.oauth2]: 'oauth2',
@@ -22,16 +23,16 @@ function getAuthStepCount(definition) {
  * definition: display metadata, auth type and step count. Never credentials
  * or env values.
  */
-function describeEntityType(definition) {
+function describeEntityType(definition, typeName = definition.moduleName) {
     const stepCount = getAuthStepCount(definition);
     const display = definition.display || {};
     const description = {
-        type: definition.moduleName,
+        type: typeName,
         name:
             callIfFunction(definition, 'getDisplayName') ??
             display.label ??
             display.name ??
-            definition.moduleName,
+            typeName,
         authType:
             callIfFunction(definition, 'getAuthType') ??
             AUTH_TYPE_BY_REQUESTER[definition.API?.requesterType] ??
@@ -58,27 +59,74 @@ function findDefinition(moduleDefinitions, entityType) {
     return definition;
 }
 
-/** Lists the entity types (API modules) this app can authorize. */
+/**
+ * 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({ moduleDefinitions }) {
-        this.moduleDefinitions = moduleDefinitions || [];
+    constructor({ entityTypeRegistry, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute() {
-        return this.moduleDefinitions
-            .map(describeEntityType)
+    /** @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; 404 when the app does not configure it. */
+/** Describes one entity type, looked up by its registry key; 404 when absent. */
 class GetEntityType {
-    constructor({ moduleDefinitions }) {
-        this.moduleDefinitions = moduleDefinitions || [];
+    constructor({ entityTypeRegistry, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute(entityType) {
-        return describeEntityType(findDefinition(this.moduleDefinitions, 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, this.scopePolicy, user);
     }
 }
 

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

@@ -98,9 +98,24 @@ class ExecuteEntityProxyRequest {
             audit.requestBytes = validated.requestBytes;
             const path = normalizeProxyPath(validated.path);
 
+            // Access is `use` in the active organization (ADR-056 §3.5, §3.6): the
+            // owner's entity there, or the organization's. A `global` entity is
+            // never the tenant's.
             const { entity, definition, module } =
                 await this.getEntityModuleForUser.execute(entityId, user);
             audit.module = definition.moduleName;
+            // Narrowest by default (§3.5): proxying through a shared credential
+            // lets any member act on the organization's account, so only an
+            // individual entity may be proxied until `managementApi.proxy.scopes`
+            // lets an app opt in to `organization`.
+            // TODO(F6): read proxy.scopes here instead of refusing outright.
+            if (this.getEntityModuleForUser.describe(entity, user)?.scope !== 'individual') {
+                throw new ProxyRequestError(
+                    'PROXY_NOT_ALLOWED',
+                    'The entity proxy only accepts individual entities; organization-level entities are not proxied',
+                    { module: definition.moduleName, reason: 'scope' }
+                );
+            }
             const credentialRef = entity.credential;
             const credentialId =
                 credentialRef && typeof credentialRef === 'object'

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,13 @@
 const Boom = require('@hapi/boom');
+const { describeRecord } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 /**
  * 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 +35,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,7 +69,11 @@ 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 {
@@ -74,13 +86,21 @@ class GetEntityModuleForUser {
                 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) {

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) {

package/modules/use-cases/multi-step-authorization.js

@@ -3,6 +3,8 @@ const { FetchError } = require('../../errors/fetch-error');
 const { getLogger } = require('../../logs');
 const { AuthorizationSession } = require('../domain/authorization-session');
 const { findDefinition, getAuthStepCount } = require('./entity-types');
+const { describeRecord } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 const log = getLogger('frigg.api.authorize');
 
@@ -144,21 +146,28 @@ class SubmitAuthorizationStep {
         moduleDefinitions,
         getAuthorizationRequirements,
         authorizationSessionRepository,
-        processAuthorizationCallback,
+        authorizeEntityForUser,
         moduleRepository,
         credentialRepository,
         createModule,
+        scopePolicy,
     }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleDefinitions = moduleDefinitions || [];
         this.getAuthorizationRequirements = getAuthorizationRequirements;
         this.sessions = authorizationSessionRepository;
-        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.authorizeEntityForUser = authorizeEntityForUser;
         this.moduleRepository = moduleRepository;
         this.credentialRepository = credentialRepository;
         this.createModule = createModule || defaultCreateModule;
     }
 
-    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null }) {
+    /**
+     * @param {Object} params
+     * @param {string} [params.scope] - the scope the caller asks for, from the
+     *   deciding level's allow list (ADR-056 §3.1). Never `global`.
+     */
+    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null, scope }) {
         if (!data || typeof data !== 'object' || Array.isArray(data)) {
             throw Boom.badRequest('data must be an object', {
                 code: 'VALIDATION_ERROR',
@@ -166,7 +175,15 @@ class SubmitAuthorizationStep {
             });
         }
         const definition = findDefinition(this.moduleDefinitions, entityType);
+        // `userId` binds a session to the caller and is what GET /authorize
+        // computes too. The owner of the entity this creates is decided by
+        // scope (§3.2), not by user.primary, and is `ownership.ownerId`.
         const userId = user.getId();
+        const ownership = this.authorizeEntityForUser.resolveOwnership({
+            user,
+            entityType,
+            scope,
+        });
 
         if (!isMultiStep(definition)) {
             if (step !== 1) {
@@ -174,7 +191,7 @@ class SubmitAuthorizationStep {
                     code: 'INVALID_STEP',
                 });
             }
-            return this.complete({ userId, entityType, params: data, credentialId });
+            return this.complete({ ownership, user, entityType, params: data, credentialId });
         }
 
         const totalSteps = getAuthStepCount(definition);
@@ -205,7 +222,7 @@ class SubmitAuthorizationStep {
             );
         }
 
-        const module = this.createModule({ userId, definition });
+        const module = this.createModule({ userId: ownership.ownerId, definition });
         let result;
         try {
             result = await definition.processAuthorizationStep(
@@ -224,7 +241,8 @@ class SubmitAuthorizationStep {
             session.markComplete();
             await this.sessions.update(session);
             const outcome = await this.complete({
-                userId,
+                ownership,
+                user,
                 entityType,
                 params: result.authData || {},
                 credentialId,
@@ -261,14 +279,15 @@ class SubmitAuthorizationStep {
         };
     }
 
-    async complete({ userId, entityType, params, credentialId }) {
+    async complete({ ownership, user, entityType, params, credentialId }) {
         let callback;
         try {
-            callback = await this.processAuthorizationCallback.execute(
-                userId,
+            ({ result: callback } = await this.authorizeEntityForUser.execute({
+                user,
                 entityType,
-                params
-            );
+                data: params,
+                ownership,
+            }));
         } catch (error) {
             throw toAuthorizationError(error);
         }
@@ -276,13 +295,18 @@ class SubmitAuthorizationStep {
             this.moduleRepository.findEntityById(callback.entity_id),
             this.credentialRepository.findCredentialById(callback.credential_id),
         ]);
+        // What the new entity is to this caller (§3.4), so a client need not list again.
+        const tenancy = entity
+            ? describeRecord(entity, this.scopePolicy.accessContext(user), 'entity')
+            : null;
         const outcome = {
             status: 'complete',
-            entity,
+            entity: entity && tenancy ? { ...entity, tenancy } : entity,
             credential: credential && {
                 ...credential,
                 type: entityType,
                 entityIds: entity ? [String(entity.id)] : [],
+                ...(tenancy && { tenancy }),
             },
         };
         if (credentialId && String(callback.credential_id) !== String(credentialId)) {