@friggframework/core 2.0.0--canary.683.f45da33.0 → 2.0.0--canary.684.e113124.0

package/credential/use-cases/credential-operations-for-user.js

@@ -1,12 +1,28 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const {
+    createScopePolicy,
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+    SCOPES,
+} = require('../../modules/entity-scope');
 const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
- * Management API v2 credential operations. A credential has no module name
- * of its own; its `type` and the entities that use it come from the
- * caller's entities. A missing or foreign credential is a 404.
+ * Management API v2 credential operations (ADR-056 §3.4, §3.6). A credential
+ * has no module name and no organization of its own:
+ *
+ * - its `type` and `entityIds` come from the entities that use it that the
+ *   caller may see, so the same person's account connected in two
+ *   organizations (one credential, two entities) lists in each organization
+ *   with that organization's entity only;
+ * - who it belongs to is its OWNER (`credential.userId`), never the entities:
+ *   a credential an individual entity and an organization entity both point at
+ *   (possible only through legacy data) is described by whoever owns the
+ *   credential, so the answer cannot change with the order the entities load;
+ * - a credential whose entities are all out of sight (another organization's)
+ *   is a 404, and one with no entities at all (its entity was deleted) is
+ *   visible to its owner only, as it was before scoping.
  */
 
 const credentialIdOf = (entity) => {
@@ -39,31 +55,82 @@ function withEntityUsage(credentials, entities) {
     });
 }
 
-/** The caller's credentials with their type and entity usage. */
+/**
+ * `{scope, owner, organizationId, access}` of a credential for this caller, or
+ * null when its owner is neither the caller nor the active organization. Built
+ * by `describeRecord` over the row a connection by this owner has: the
+ * organization of a visible entity, else the one a new entity would get.
+ */
+function credentialTenancy(credential, visibleEntities, ctx) {
+    const entityOrg = visibleEntities.find(
+        (entity) => entity.organizationId !== undefined && entity.organizationId !== null
+    )?.organizationId;
+    const organizationId =
+        entityOrg ?? (ctx.individualAcross === 'all' ? null : ctx.activeOrgId);
+    return describeRecord({ userId: credential.userId, organizationId }, ctx, 'entity');
+}
+
+/** The entities of `entities` the caller may see, each with its `tenancy`. */
+function visibleOf(entities, ctx) {
+    const visible = [];
+    for (const entity of entities || []) {
+        const tenancy = describeRecord(entity, ctx, 'entity');
+        if (tenancy) visible.push({ ...entity, tenancy });
+    }
+    return visible;
+}
+
+/**
+ * The caller's credentials with their type, the entities of them they may see
+ * and `tenancy`. Credentials with no entity at all are listed too, for the
+ * person and the active organization that own them.
+ */
 class ListCredentialsForUser {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
-    async execute(user) {
-        const userId = user.getId();
-        const [credentials, entities] = await Promise.all([
-            this.credentialRepository.findCredentialsByUserId(userId),
-            this.moduleRepository.findEntitiesByUserId(userId),
+    /** @param {{scope?: string, owner?: string}} [filters] */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const owners = [...new Set([ctx.callerId, ctx.activeOrgId].filter(Boolean))];
+        const [found, perOwner, owned] = await Promise.all([
+            this.moduleRepository.findEntitiesByOwnership(visibilityClauses(ctx, 'entity')),
+            Promise.all(owners.map((id) => this.credentialRepository.findCredentialsByUserId(id))),
+            // Every entity of those owners, in any organization: only to tell a credential
+            // with no entity at all from one used elsewhere.
+            Promise.all(owners.map((id) => this.moduleRepository.findEntitiesByUserId(id))),
         ]);
-        return withEntityUsage(credentials || [], entities);
+        const visible = visibleOf(found, ctx);
+        const usedAnywhere = new Set(owned.flat().map(credentialIdOf).filter(Boolean));
+        const listed = [];
+        for (const credential of perOwner.flat().filter(Boolean)) {
+            const id = String(credential.id);
+            const referencing = visible.filter((entity) => credentialIdOf(entity) === id);
+            if (referencing.length === 0 && usedAnywhere.has(id)) continue;
+            const tenancy = credentialTenancy(credential, referencing, ctx);
+            if (!tenancy || !matchesListFilters(tenancy, filters)) continue;
+            listed.push({ ...withEntityUsage([credential], referencing)[0], tenancy });
+        }
+        return listed;
     }
 }
 
-/** One credential the caller owns, with its type and entity usage. */
+/** One credential the caller may see: see the header. 404 otherwise. */
 class GetCredentialForUserV2 {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
     async execute(credentialId, user) {
+        const notFound = () =>
+            Boom.notFound(`Credential ${credentialId} not found`, {
+                code: 'CREDENTIAL_NOT_FOUND',
+            });
         let credential = null;
         try {
             credential = await this.credentialRepository.findCredentialById(
@@ -74,26 +141,32 @@ class GetCredentialForUserV2 {
                 throw error;
             }
         }
-        if (!credential || !userOwns(user, credential.userId)) {
-            throw Boom.notFound(`Credential ${credentialId} not found`, {
-                code: 'CREDENTIAL_NOT_FOUND',
-            });
-        }
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            credential.userId
-        );
-        return withEntityUsage([credential], entities)[0];
+        if (!credential) throw notFound();
+        const ctx = this.scopePolicy.accessContext(user);
+
+        const referencing =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        const visible = visibleOf(referencing, ctx);
+        if (referencing.length > 0 && visible.length === 0) throw notFound();
+        const tenancy = credentialTenancy(credential, visible, ctx);
+        if (!tenancy) throw notFound();
+        return { ...withEntityUsage([credential], visible)[0], tenancy };
     }
 }
 
 /**
- * Deletes a credential the caller owns. The entities that used it stay, with
- * their credential unset, so they show as needing re-authorization rather
+ * Deletes a credential the caller may manage. The entities that used it stay,
+ * with their credential unset, so they show as needing re-authorization rather
  * than disappearing from integrations.
+ *
+ * Refuses with 409 `CREDENTIAL_SHARED` while an entity the caller cannot see
+ * still uses it: one credential row serves the same provider account in every
+ * organization, and deleting it from one would break the other. The message
+ * says nothing about the other connections (not even how many): remove the
+ * entities that use it, and it goes with the last one.
  */
 class DeleteCredentialForUser {
-    constructor({ credentialRepository, moduleRepository, getCredentialForUser, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
         this.getCredentialForUser = getCredentialForUser;
@@ -104,11 +177,15 @@ class DeleteCredentialForUser {
             credentialId,
             user
         );
-        // A credential an organization owns: the organization's admins only.
-        // (null: not the person's or the active organization's, which the
-        // owner check above already decided.)
-        const access = this.scopePolicy.accessToOwnedBy(user, credential.userId);
-        if (access !== null) assertCanManage(access, `credential ${credential.id}`);
+        assertCanManage(credential.tenancy.access, `credential ${credential.id}`);
+        const usedBy =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        if (usedBy.length > credential.entityIds.length) {
+            throw Boom.conflict(
+                `Credential ${credential.id} is still in use by other connections and cannot be deleted from here`,
+                { code: 'CREDENTIAL_SHARED' }
+            );
+        }
         for (const entityId of credential.entityIds) {
             await this.moduleRepository.unsetCredential(entityId);
         }

package/credential/use-cases/reauthorize-credential-for-user.js

@@ -1,5 +1,4 @@
 const Boom = require('@hapi/boom');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
 const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
@@ -19,7 +18,9 @@ async function credentialEntityType(getCredentialForUser, credentialId, user) {
     return {
         entityType: credential.type,
         credentialId: String(credential.id),
-        ownerId: credential.userId,
+        // A re-authorization keeps the scope the connection already has.
+        fixedScope: credential.tenancy?.scope,
+        access: credential.tenancy?.access,
     };
 }
 
@@ -31,14 +32,12 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const { ownerId, ...binding } = await credentialEntityType(
-            this.getCredentialForUser,
-            credentialId,
-            user
-        );
+        const { entityType, credentialId: boundCredentialId } =
+            await credentialEntityType(this.getCredentialForUser, credentialId, user);
         return this.getAuthorizationStep.execute({
             user,
-            ...binding,
+            entityType,
+            credentialId: boundCredentialId,
             step,
             sessionId,
             state,
@@ -48,21 +47,19 @@ class GetCredentialReauthorization {
 
 /** POST /api/v2/credentials/:credentialId/reauthorize */
 class ReauthorizeCredentialForUser {
-    constructor({ getCredentialForUser, submitAuthorizationStep, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    constructor({ getCredentialForUser, submitAuthorizationStep }) {
         this.getCredentialForUser = getCredentialForUser;
         this.submitAuthorizationStep = submitAuthorizationStep;
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const { ownerId, ...binding } = await credentialEntityType(
+        const { access, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
         );
         // A credential an organization owns: the organization's admins only.
-        const access = this.scopePolicy.accessToOwnedBy(user, ownerId);
-        if (access !== null) assertCanManage(access, `credential ${credentialId}`);
+        assertCanManage(access, `credential ${credentialId}`);
         return this.submitAuthorizationStep.execute({
             user,
             ...binding,

package/management-api/openapi/components.js

@@ -206,6 +206,7 @@ const SCHEMAS = {
             authIsValid: nullable({ type: 'boolean' }),
             entityIds: { type: 'array', items: { type: 'string' } },
             entityCount: { type: 'integer', minimum: 0 },
+            ...tenancyProperties,
             createdAt: nullable({ type: 'string', format: 'date-time' }),
             updatedAt: nullable({ type: 'string', format: 'date-time' }),
             data: {

package/management-api/openapi/v2-operations.js

@@ -184,6 +184,9 @@ const V2_OPERATIONS = {
     // Credentials
     listCredentials: {
         summary: "List the caller's credentials (masked)",
+        description:
+            'A credential is listed through the entities that use it that the caller may see, so each organization lists only its own connections; one no entity uses is listed to its owner. Each carries `scope`, `owner`, `organizationId` and `access`, taken from who owns the credential.',
+        parameters: listFilters,
         responses: { 200: ok('Credentials', ref('ListCredentialsResponse')), ...errors('Unauthorized') },
     },
     getCredential: {

package/management-api/v2/dependencies.js

@@ -124,6 +124,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
         credentialRepository,
         moduleRepository,
+        scopePolicy,
     });
     const getAuthorizationRequirements = new GetAuthorizationRequirements({
         moduleDefinitions,
@@ -246,13 +247,13 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         listCredentialsForUser: new credentialOps.ListCredentialsForUser({
             credentialRepository,
             moduleRepository,
+            scopePolicy,
         }),
         getCredentialForUser,
         deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({
             credentialRepository,
             moduleRepository,
             getCredentialForUser,
-            scopePolicy,
         }),
         getCredentialReauthorization: new GetCredentialReauthorization({
             getCredentialForUser,
@@ -261,7 +262,6 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         reauthorizeCredentialForUser: new ReauthorizeCredentialForUser({
             getCredentialForUser,
             submitAuthorizationStep,
-            scopePolicy,
         }),
 
         // Authorization (multi-step)

package/management-api/v2/dto.js

@@ -75,6 +75,8 @@ const CREDENTIAL_METADATA = new Set([
     'type',
     'entityIds',
     'status',
+    // Added by the credential use cases (ADR-056 §3.4); never provider data.
+    'tenancy',
 ]);
 
 /**
@@ -126,6 +128,7 @@ function maskCredential(credential) {
         entityCount: entityIds.length,
         createdAt: toIso(credential.createdAt),
         updatedAt: toIso(credential.updatedAt),
+        ...tenancyFields(credential.tenancy),
         data,
     };
 }

package/management-api/v2/handlers/credentials.js

@@ -1,4 +1,5 @@
 const { maskCredential } = require('../dto');
+const { parseListFilters } = require('../request');
 
 /** Management API v2 credential handlers, keyed by operationId. */
 function createCredentialHandlers(useCases) {
@@ -6,8 +7,11 @@ function createCredentialHandlers(useCases) {
         useCases;
 
     return {
-        async listCredentials(_req, res, user) {
-            const credentials = await listCredentialsForUser.execute(user);
+        async listCredentials(req, res, user) {
+            const credentials = await listCredentialsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ credentials: credentials.map(maskCredential) });
         },
 

package/modules/scope-policy.js

@@ -69,6 +69,20 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         };
     };
 
+    /**
+     * The owner and organization for a scope that is already decided: a
+     * re-authorization keeps the scope its connection has, whatever the config
+     * says now. The admin gate applies as it does on create.
+     */
+    const ownershipForScope = ({ scope, user }) => {
+        const ctx = contextFor(user);
+        return {
+            ...resolveOwnerForScope(scope, ctx),
+            legacyOrgId: ctx.legacyOrgId,
+            source: 'fixed',
+        };
+    };
+
     /** Whether `user` may load this stored entity for use (same clauses as the list). */
     const canUseEntity = (user, entity) =>
         describeRecord(entity, contextFor(user), 'entity') !== null;
@@ -86,6 +100,7 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         accessContext: contextFor,
         resolveScope: resolveEntityScope,
         resolveOwnership,
+        ownershipForScope,
         canUseEntity,
     });
 }

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

@@ -19,9 +19,11 @@ class AuthorizeEntityForUser {
      * 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
+     * @param {{user: Object, entityType: string, scope?: string, fixedScope?: string}} params
+     *   `fixedScope`: a re-authorization keeps the scope its connection has
      */
-    resolveOwnership({ user, entityType, scope }) {
+    resolveOwnership({ user, entityType, scope, fixedScope }) {
+        if (fixedScope) return this.scopePolicy.ownershipForScope({ scope: fixedScope, user });
         return this.scopePolicy.resolveOwnership({
             entityType,
             requestScope: scope,

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

@@ -166,8 +166,10 @@ class SubmitAuthorizationStep {
      * @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 }) {
+    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',
@@ -183,6 +185,7 @@ class SubmitAuthorizationStep {
             user,
             entityType,
             scope,
+            fixedScope,
         });
 
         if (!isMultiStep(definition)) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.683.f45da33.0",
+    "version": "2.0.0--canary.684.e113124.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.683.f45da33.0",
-        "@friggframework/prettier-config": "2.0.0--canary.683.f45da33.0",
-        "@friggframework/test": "2.0.0--canary.683.f45da33.0",
+        "@friggframework/eslint-config": "2.0.0--canary.684.e113124.0",
+        "@friggframework/prettier-config": "2.0.0--canary.684.e113124.0",
+        "@friggframework/test": "2.0.0--canary.684.e113124.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "f45da337e62262988666a166b3d721020dae9161"
+    "gitHead": "e1131240a890bf30cfee08ba3786458c9e2d1135"
 }