@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

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-authorization-requirements.js

@@ -3,7 +3,7 @@ const { findDefinition, getAuthStepCount } = require('./entity-types');
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 /**
@@ -80,7 +80,7 @@ class GetAuthorizationRequirements {
         if (typeof definition.getAuthRequirementsForStep === 'function') {
             raw = await definition.getAuthRequirementsForStep(step);
         } else {
-            const module = this.createModule({
+            const module = await this.createModule({
                 userId,
                 definition,
                 ...(state ? { state } : {}),

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,21 +14,31 @@ 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);
+        return Promise.all(
+            entities.map(async (entity) => {
+                const definition = this.definitionMap.get(entity.moduleName);
 
-            const moduleInstance = new Module({
-                userId,
-                definition: definition,
-                entity: entity,
-            });
-            return mapModuleClassToModuleDTO(moduleInstance);
-        });
+                const moduleInstance = await Module.create({
+                    userId: entity.userId,
+                    definition: definition,
+                    entity: entity,
+                });
+                return mapModuleClassToModuleDTO(moduleInstance);
+            })
+        );
     }
 }
 

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
  */
@@ -14,7 +20,7 @@ function userOwns(user, ownerId) {
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 /**
@@ -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;
@@ -53,7 +62,7 @@ class GetEntityModuleForUser {
                 { code: 'ENTITY_TYPE_NOT_FOUND' }
             );
         }
-        const module = this.createModule({
+        const module = await this.createModule({
             userId: entity.userId,
             entity,
             definition,
@@ -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 {
             );
         }
 
-        const module = new Module({
-            userId,
+        // 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 = await Module.create({
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

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

@@ -21,7 +21,7 @@ class GetEntityOptionsByType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        const moduleInstance = new Module({
+        const moduleInstance = await Module.create({
             userId,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-module-instance-from-type.js

@@ -23,7 +23,7 @@ class GetModuleInstanceFromType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        return new Module({
+        return Module.create({
             userId,
             definition: moduleDefinition,
             state: options.state,

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 {
             );
         }
 
-        const module = new Module({
-            userId,
+        // 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 = await Module.create({
+            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 };

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

@@ -3,12 +3,14 @@ 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');
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 const isMultiStep = (definition) =>
@@ -144,21 +146,30 @@ 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`.
+     * @param {string} [params.fixedScope] - re-authorization keeps the scope the
+     *   credential already has, whatever the config says now.
+     */
+    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null, scope, fixedScope }) {
         if (!data || typeof data !== 'object' || Array.isArray(data)) {
             throw Boom.badRequest('data must be an object', {
                 code: 'VALIDATION_ERROR',
@@ -166,7 +177,16 @@ 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,
+            fixedScope,
+        });
 
         if (!isMultiStep(definition)) {
             if (step !== 1) {
@@ -174,7 +194,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 +225,7 @@ class SubmitAuthorizationStep {
             );
         }
 
-        const module = this.createModule({ userId, definition });
+        const module = await this.createModule({ userId: ownership.ownerId, definition });
         let result;
         try {
             result = await definition.processAuthorizationStep(
@@ -224,7 +244,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 +282,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 +298,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)) {

package/modules/use-cases/process-authorization-callback.js

@@ -1,5 +1,16 @@
 const { Module } = require('../module');
 const { ModuleConstants } = require('../ModuleConstants');
+const { pickExistingEntity } = require('../scope-resolution');
+
+/**
+ * What an entity belongs to when the caller says nothing: the person's own,
+ * outside any organization.
+ */
+const DEFAULT_TENANCY = Object.freeze({
+    scope: 'individual',
+    organizationId: null,
+    legacyOrgId: null,
+});
 const { getLogger } = require('../../logs');
 
 const log = getLogger('frigg.modules.authorization_callback');
@@ -30,7 +41,17 @@ class ProcessAuthorizationCallback {
         this.integrationRepository = integrationRepository;
     }
 
-    async execute(userId, entityType, params) {
+    /**
+     * @param {string} userId - the OWNER of what this creates (ADR-056 §3.2): the
+     *   person for `individual`, the organization's user for `organization`.
+     *   Not necessarily the caller; callers resolve it from the scope.
+     * @param {string} entityType
+     * @param {Object} params - what the module's authorization needs
+     * @param {{scope: string, organizationId: (string|null), legacyOrgId: (string|null)}} [tenancy]
+     *   the entity's scope and organization (§3.6); default: the person's own,
+     *   with no organization
+     */
+    async execute(userId, entityType, params, tenancy = DEFAULT_TENANCY) {
         log.debug('Authorization callback started', {
             eventName: `${log.name}.started`,
             userId,
@@ -57,10 +78,7 @@ class ProcessAuthorizationCallback {
                 userId,
                 entityType
             );
-        const existingEntity =
-            existingEntities && existingEntities.length > 0
-                ? existingEntities[0]
-                : null;
+        const existingEntity = pickExistingEntity(existingEntities, tenancy);
 
         if (existingEntity) {
             log.debug('Existing entity found', {
@@ -70,7 +88,7 @@ class ProcessAuthorizationCallback {
             });
         }
 
-        const module = new Module({
+        const module = await Module.create({
             userId,
             entity: existingEntity,
             definition: moduleDefinition,
@@ -156,7 +174,8 @@ class ProcessAuthorizationCallback {
         const persistedEntity = await this.findOrCreateEntity(
             entityDetails,
             entityType,
-            module.credential.id
+            module.credential.id,
+            tenancy
         );
         log.debug('Authorization callback completed', {
             eventName: `${log.name}.completed`,
@@ -233,7 +252,12 @@ class ProcessAuthorizationCallback {
         module.credential = persisted;
     }
 
-    async findOrCreateEntity(entityDetails, moduleName, credentialId) {
+    async findOrCreateEntity(
+        entityDetails,
+        moduleName,
+        credentialId,
+        tenancy = DEFAULT_TENANCY
+    ) {
         const { identifiers, details } = entityDetails;
 
         // Support both 'user' and 'userId' field names from module definitions
@@ -247,11 +271,16 @@ class ProcessAuthorizationCallback {
             );
         }
 
-        const existingEntity = await this.moduleRepository.findEntity({
-            externalId: identifiers.externalId,
-            user: userId,
-            moduleName: moduleName,
-        });
+        // The same provider account in two organizations is two entities
+        // (ADR-056 §3.6), so the match is per organization.
+        const existingEntity = pickExistingEntity(
+            await this.moduleRepository.findEntities({
+                externalId: identifiers.externalId,
+                user: userId,
+                moduleName: moduleName,
+            }),
+            tenancy
+        );
 
         if (existingEntity) {
             // Repoint the entity's credentialId when re-auth produced a
@@ -282,12 +311,17 @@ class ProcessAuthorizationCallback {
             return existingEntity;
         }
 
-        return await this.moduleRepository.createEntity({
-            ...identifiers,
-            ...details,
-            moduleName: moduleName,
-            credential: credentialId,
-        });
+        // `organizationId` is not part of the entity data: that carries provider
+        // fields, and one that happens to be called organizationId is theirs.
+        return await this.moduleRepository.createEntity(
+            {
+                ...identifiers,
+                ...details,
+                moduleName: moduleName,
+                credential: credentialId,
+            },
+            { organizationId: tenancy.organizationId ?? null }
+        );
     }
 }