@friggframework/core 2.0.0--canary.681.d970b9e.0 → 2.0.0--canary.684.9d19f43.0

package/README.md

@@ -393,7 +393,7 @@ value that is not a three-part JWT is not offered to the verifier at all; it fal
 | `clockToleranceSec` | `30` | Skew allowed on `exp` and `nbf`. |
 | `userIdClaim` | `sub` | App user id (required in the token). |
 | `orgIdClaim` | `org_id` | App organization id (optional). |
-| `roleClaim` | `org_role` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). |
+| `roleClaim` | `org_role` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). A token with no role is a member for permissions too: it cannot create or change organization-level entities or integrations; `user.orgAdminRoles` (default `['ADMIN']`) names the roles that can. |
 
 Rules worth knowing:
 
@@ -421,6 +421,42 @@ Rules worth knowing:
 - Two first logins for the same new person or organization, even in different organizations, both
   succeed: a create that loses to a unique constraint finds the winner's row.
 
+#### Entity scopes and ownership (ADR-056 §3)
+
+Who owns an entity (a connected account) or an integration follows its **scope**, not `user.primary`:
+
+| Scope | Owned by | Created with |
+|---|---|---|
+| `individual` | the person (`individualUser`) | the active organization (`organizationId`), or none under `individualAcross: 'all'` |
+| `organization` | the active organization's user | that organization |
+| `global` | nobody (the app owner) | none; refused by the tenant API (admin routes only) |
+
+The scope of a new connection is the first of: the request (`scope` on `POST /api/v2/authorize`, only from
+the deciding level's `allow` list), the integration binding (`Definition.modules[key].scope` or
+`Definition.entities[key].scope`), `Definition.ownership.scope`, the entity type
+(`appDefinition.entities[name].scope`), `appDefinition.ownership.scope`, then `organization` for an
+organization-primary app and `individual` otherwise. A setting is `'organization'` or
+`{ default: 'individual', allow: ['individual', 'organization'] }`.
+
+```javascript
+const appDefinition = {
+    user: { primary: 'individual', authModes: { adopterJwt: true } },
+    ownership: { scope: 'individual', individualAcross: 'organization' }, // the defaults
+    entities: {
+        google: { definition: google, scope: 'individual' },
+        xero: { definition: xero, scope: { default: 'organization', allow: ['organization', 'individual'] } },
+    },
+    integrations: [Sync], // Sync.Definition.ownership = { owner: 'derive' }
+};
+```
+
+`GET /api/v2/entities` and `/integrations` return, for the active organization, its own
+rows and the caller's, each with `scope`, `owner`, `organizationId` and `access`, and take `?scope=` and
+`?owner=me|org`. An individual entity is only visible and usable in the organization it was connected in
+(or in all of them, with `individualAcross: 'all'`). Rows written before this existed keep working: see
+[Entity scopes](../../docs/guides/entity-scopes.md), which also covers the schema (`organizationId` on
+`Entity` and `Integration`, no `scope` column) and what is deferred.
+
 ### 8. Lambda Utilities (`/lambda`)
 
 AWS Lambda-specific utilities and helpers.

package/application/commands/integration-commands.js

@@ -18,7 +18,7 @@ const {
     ListIntegrationsByEntityExternalIdUseCase,
 } = require('../../integrations/use-cases/list-integrations-by-entity-external-id');
 const {
-    GetIntegrationsForUser,
+    GetIntegrationsByUserId,
 } = require('../../integrations/use-cases/get-integrations-for-user');
 const {
     CreateIntegration,
@@ -30,8 +30,9 @@ const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../../modules/entity-type-registry');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
@@ -51,7 +52,16 @@ function mapErrorToResponse(error) {
     };
 }
 
-function createIntegrationCommands({ integrationClass } = {}) {
+/**
+ * @param {Object} [params]
+ * @param {Function} [params.integrationClass]
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module
+ *   definitions (`loadAppDefinition().moduleDefinitions`). Integration code
+ *   calls this from a constructor with no app definition in hand, so when it
+ *   is omitted the commands hydrate with this integration's own modules only
+ *   (a registry built from `{ integrations: [integrationClass] }`).
+ */
+function createIntegrationCommands({ integrationClass, moduleDefinitions } = {}) {
     // Always use Frigg's default repositories and use cases
     const integrationRepository = createIntegrationRepository();
 
@@ -108,13 +118,13 @@ function createIntegrationCommands({ integrationClass } = {}) {
 
     const moduleRepository = createModuleRepository();
 
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses([
-        integrationClass,
-    ]);
-
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions,
+        moduleDefinitions:
+            moduleDefinitions ??
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
     });
 
     const loadIntegrationContextUseCase = new LoadIntegrationContextUseCase({
@@ -142,7 +152,7 @@ function createIntegrationCommands({ integrationClass } = {}) {
             moduleRepository,
         });
 
-    const getIntegrationsForUserUseCase = new GetIntegrationsForUser({
+    const getIntegrationsForUserUseCase = new GetIntegrationsByUserId({
         integrationRepository,
         integrationClasses: [integrationClass],
         moduleFactory,

package/application/index.js

@@ -17,6 +17,7 @@ const { createUsageCommands } = require('./commands/usage-commands');
  *
  * @param {Object} params
  * @param {Object} params.integrationClass - Integration class (required)
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module definitions; defaults to the integration's own modules
  * @returns {Object} Unified commands object with all CRUD operations
  *
  * @example
@@ -24,9 +25,12 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass }) {
+function createFriggCommands({ integrationClass, moduleDefinitions }) {
     // All commands use Frigg's default repositories and use cases
-    const integrationCommands = createIntegrationCommands({ integrationClass });
+    const integrationCommands = createIntegrationCommands({
+        integrationClass,
+        moduleDefinitions,
+    });
 
     const userCommands = createUserCommands();
 

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

@@ -1,10 +1,28 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+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) => {
@@ -37,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(
@@ -72,22 +141,29 @@ 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 }) {
@@ -101,6 +177,15 @@ class DeleteCredentialForUser {
             credentialId,
             user
         );
+        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,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
  * Re-authorization of a credential the caller owns (Management API v2). It
@@ -14,7 +15,13 @@ async function credentialEntityType(getCredentialForUser, credentialId, user) {
             { code: 'CREDENTIAL_TYPE_UNKNOWN' }
         );
     }
-    return { entityType: credential.type, credentialId: String(credential.id) };
+    return {
+        entityType: credential.type,
+        credentialId: String(credential.id),
+        // A re-authorization keeps the scope the connection already has.
+        fixedScope: credential.tenancy?.scope,
+        access: credential.tenancy?.access,
+    };
 }
 
 /** GET /api/v2/credentials/:credentialId/reauthorize */
@@ -25,14 +32,12 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const 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,11 +53,13 @@ class ReauthorizeCredentialForUser {
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const binding = await credentialEntityType(
+        const { access, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
         );
+        // A credential an organization owns: the organization's admins only.
+        assertCanManage(access, `credential ${credentialId}`);
         return this.submitAuthorizationStep.execute({
             user,
             ...binding,

package/database/encryption/encryption-schema-registry.js

@@ -180,6 +180,13 @@ function loadModuleEncryptionSchemas(integrations) {
         return;
     }
 
+    // NOTE: this path does not exist ('../integrations' resolves to
+    // database/integrations), so today this function throws MODULE_NOT_FOUND,
+    // loadCustomEncryptionSchema swallows it, and module credentialFields are
+    // effectively NOT registered. Fixing it changes which fields are encrypted
+    // and needs a decrypt that tolerates plaintext, so it ships separately:
+    // branch claude/internal-mcp-03b-module-credential-encryption. Left as is
+    // here on purpose (ADR-059 must not change what gets encrypted).
     const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
 
     const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);

package/database/organization-where.js

@@ -0,0 +1,18 @@
+/**
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
+ * §3.6), shared by the entity and integration adapters.
+ *
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
+ * only a missing field. A row written before the column existed is the common
+ * "no organization" case, so `null` here means both.
+ */
+function organizationWhere(organizationId) {
+    if (organizationId === null) {
+        return {
+            OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
+        };
+    }
+    return { organizationId };
+}
+
+module.exports = { organizationWhere };