@friggframework/core 2.0.0--canary.679.a2bcc2f.0 → 2.0.0--canary.686.87e9875.0

package/modules/repositories/module-repository-postgres.js

@@ -1,5 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * PostgreSQL Module Repository Adapter
@@ -108,6 +109,26 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         return credentialMap;
     }
 
+    /**
+     * The one place a stored entity row becomes the entity the application sees.
+     * The provider's `data` is spread FIRST and every column is pinned after it:
+     * a stored `id`, `userId` or `organizationId` in `data` must not decide who
+     * owns the entity or who sees it.
+     * @private
+     */
+    _mapEntity(row, credential) {
+        return {
+            ...(row.data || {}),
+            id: row.id.toString(),
+            credential,
+            userId: row.userId?.toString(),
+            name: row.name,
+            externalId: row.externalId,
+            moduleName: row.moduleName,
+            organizationId: row.organizationId?.toString() ?? null,
+        };
+    }
+
     /**
      * Find entity by ID with credential
      * Replaces: Entity.findById(entityId).populate('credential')
@@ -124,20 +145,12 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -157,15 +170,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -185,15 +190,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -217,15 +214,32 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
+    }
+
+    /**
+     * Find entities matching any of the owner/organization pairs, in one query.
+     * `organizationId: null` matches rows with no organization. The caller
+     * (a use case) decides which pairs; this only runs them.
+     *
+     * @param {Array<{userId: string, organizationId: (string|null)}>} clauses
+     * @returns {Promise<Array>} Array of entity objects with string IDs
+     */
+    async findEntitiesByOwnership(clauses) {
+        if (!Array.isArray(clauses) || clauses.length === 0) return [];
+        const entities = await this.prisma.entity.findMany({
+            where: {
+                OR: clauses.map(({ userId, organizationId }) => ({
+                    userId: this._convertId(userId),
+                    organizationId: this._convertId(organizationId),
+                })),
+            },
+        });
+
+        const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
+        const credentialMap = await this._fetchCredentialsBulk(credentialIds);
+
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -264,15 +278,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -292,15 +298,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
             .filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -308,9 +306,13 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
      * Replaces: Entity.create(entityData)
      *
      * @param {Object} entityData - Entity data (with string IDs from application layer)
+     * @param {{organizationId?: (string|null)}} [tenancy] - the organization the entity
+     *   belongs to (ADR-056 §3.6). A separate argument, not a field of `entityData`,
+     *   because `entityData` carries provider fields and one named `organizationId`
+     *   must not be taken for ours.
      * @returns {Promise<Object>} Created entity object with string IDs
      */
-    async createEntity(entityData) {
+    async createEntity(entityData, tenancy = {}) {
         const {
             user,
             userId,
@@ -328,6 +330,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
             name,
             moduleName,
             externalId,
+            organizationId: this._convertId(tenancy.organizationId ?? null),
             data: dynamicData,
         };
 
@@ -337,15 +340,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
         const credentialObj = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential: credentialObj,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credentialObj);
     }
 
     /**
@@ -401,15 +396,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
             const credentialObj = await this._fetchCredential(entity.credentialId);
 
-            return {
-                id: entity.id.toString(),
-                credential: credentialObj,
-                userId: entity.userId?.toString(),
-                name: entity.name,
-                externalId: entity.externalId,
-                moduleName: entity.moduleName,
-                ...(entity.data || {}),
-            };
+            return this._mapEntity(entity, credentialObj);
         } catch (error) {
             if (error.code === 'P2025') {
                 return null;
@@ -474,6 +461,11 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         if (filter.moduleName) where.moduleName = filter.moduleName;
         if (filter.externalId) where.externalId = this._toString(filter.externalId);
 
+        // `null` means "no organization"; absent means "any".
+        if (filter.organizationId !== undefined) {
+            where.organizationId = this._convertId(filter.organizationId);
+        }
+
         return where;
     }
 }

package/modules/repositories/module-repository.js

@@ -1,5 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * Prisma-based Module Repository
@@ -37,7 +38,7 @@ class ModuleRepository extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         return {

package/modules/scope-config.js

@@ -0,0 +1,192 @@
+/**
+ * Reading and validating ownership settings in an app definition (ADR-056
+ * §3.1, §3.3). Called once by loadAppDefinition, so a bad setting stops the app
+ * at load, not on the first request. No I/O.
+ */
+
+const {
+    SCOPES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    DEFAULT_ORG_ADMIN_ROLES,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    resolveScope,
+} = require('./scope-resolution');
+const { entityTypeNameOf } = require('./entity-type-registry');
+
+/** The binding scope an integration declares for `modules[key]`, if any. */
+function bindingScopeSetting(Definition, key) {
+    const binding = Definition?.modules?.[key];
+    if (binding?.scope !== undefined) return binding.scope;
+    const entityEntry = Definition?.entities?.[key];
+    if (entityEntry?.scope !== undefined) return entityEntry.scope;
+    // Deprecated alias from the global-entities branch: `global: true`.
+    if (entityEntry?.global === true) return SCOPES.GLOBAL;
+    return undefined;
+}
+
+function readAppOwnership(appDefinition) {
+    const raw = appDefinition?.ownership;
+    if (raw === undefined || raw === null) {
+        return { scope: null, individualAcross: 'organization' };
+    }
+    if (!isPlainObject(raw)) {
+        throw configError('appDefinition.ownership', 'must be an object');
+    }
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'individualAcross'
+    );
+    if (unknown.length) {
+        throw configError(
+            'appDefinition.ownership',
+            `unknown setting(s): ${unknown.join(', ')}`
+        );
+    }
+    const individualAcross = raw.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+    return {
+        scope: parseScopeSetting(raw.scope, 'appDefinition.ownership.scope'),
+        individualAcross,
+    };
+}
+
+function readIntegrationOwnership(integrationClass) {
+    const name = integrationClass?.Definition?.name || 'unnamed';
+    const raw = integrationClass?.Definition?.ownership;
+    if (raw === undefined || raw === null) return { scope: null, owner: 'derive' };
+    const where = `integration '${name}' ownership`;
+    if (!isPlainObject(raw)) throw configError(where, 'must be an object');
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'owner'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown setting(s): ${unknown.join(', ')}`);
+    }
+    const owner = raw.owner ?? 'derive';
+    if (!OWNER_RULES.includes(owner)) {
+        throw configError(where, `owner must be one of ${OWNER_RULES.join(', ')}`);
+    }
+    return { scope: parseScopeSetting(raw.scope, `${where}.scope`), owner };
+}
+
+/**
+ * `user.orgAdminRoles`: the token roles that may manage organization-level
+ * things. Default `['ADMIN']`. A shared-secret caller needs no role.
+ */
+function readOrgAdminRoles(appDefinition) {
+    const raw = appDefinition?.user?.orgAdminRoles;
+    if (raw === undefined || raw === null) return [...DEFAULT_ORG_ADMIN_ROLES];
+    if (
+        !Array.isArray(raw) ||
+        raw.length === 0 ||
+        raw.some((role) => typeof role !== 'string' || role.trim() === '')
+    ) {
+        throw configError(
+            'appDefinition.user.orgAdminRoles',
+            'must be a non-empty array of role names'
+        );
+    }
+    return [...raw];
+}
+
+/**
+ * `user.orgAdminGateBearerTokens`: judge Frigg bearer-token callers by role
+ * like adopter-token callers. Default false: they keep their pre-roles
+ * behaviour and may manage the organization they act in.
+ */
+function readGateBearerTokens(appDefinition) {
+    const raw = appDefinition?.user?.orgAdminGateBearerTokens;
+    if (raw === undefined || raw === null) return false;
+    if (typeof raw !== 'boolean') {
+        throw configError('appDefinition.user.orgAdminGateBearerTokens', 'must be a boolean');
+    }
+    return raw;
+}
+
+/**
+ * Every binding of every integration with its resolved scope and where it came
+ * from, parsing each integration's settings once. Throws OwnershipConfigError
+ * for any invalid one. Exported for tooling that wants to show the chain.
+ */
+function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
+    const app = readAppOwnership(appDefinition);
+    const rows = [];
+    for (const integrationClass of appDefinition?.integrations || []) {
+        const Definition = integrationClass?.Definition;
+        const name = Definition?.name || 'unnamed';
+        const ownership = readIntegrationOwnership(integrationClass);
+        for (const [key, binding] of Object.entries(Definition?.modules || {})) {
+            const moduleName = entityTypeNameOf(binding?.definition);
+            const resolved = resolveScope({
+                binding: parseScopeSetting(
+                    bindingScopeSetting(Definition, key),
+                    `integration '${name}' binding '${key}' scope`
+                ),
+                integration: ownership.scope,
+                entityType: moduleName
+                    ? entityTypeRegistry?.get(moduleName)?.settings?.scope
+                    : undefined,
+                app: app.scope,
+                primary,
+            });
+            rows.push({
+                integration: name,
+                binding: key,
+                moduleName: moduleName ?? null,
+                scope: resolved.scope,
+                source: resolved.source,
+                owner: ownership.owner,
+            });
+        }
+    }
+    return rows;
+}
+
+/**
+ * Validates every ownership setting in one pass and returns the app-level
+ * config the runtime needs.
+ *
+ * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[], gateBearerTokens: boolean}}
+ * @throws {OwnershipConfigError}
+ */
+function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
+    const app = readAppOwnership(appDefinition);
+    for (const [name, entry] of entityTypeRegistry || []) {
+        parseScopeSetting(entry?.settings?.scope, `entity type '${name}' scope`);
+    }
+    const rows = listBindingScopes(
+        appDefinition,
+        entityTypeRegistry,
+        appDefinition?.user?.primary
+    );
+    // §3.3: a shared integration must not run on one person's credential.
+    for (const row of rows) {
+        if (row.owner === 'organization' && row.scope === SCOPES.INDIVIDUAL) {
+            throw configError(
+                `integration '${row.integration}' binding '${row.binding}'`,
+                "an organization-owned integration cannot bind an 'individual' entity"
+            );
+        }
+    }
+    return Object.freeze({
+        scope: app.scope,
+        individualAcross: app.individualAcross,
+        orgAdminRoles: Object.freeze(readOrgAdminRoles(appDefinition)),
+        gateBearerTokens: readGateBearerTokens(appDefinition),
+    });
+}
+
+module.exports = {
+    bindingScopeSetting,
+    readAppOwnership,
+    readIntegrationOwnership,
+    listBindingScopes,
+    resolveOwnershipConfig,
+};

package/modules/scope-policy.js

@@ -0,0 +1,112 @@
+/**
+ * The object a use case asks about scopes (ADR-056 §3): the app's ownership
+ * config and entity type registry bound once, as closures. With no arguments it
+ * is the behaviour of an app that configures nothing.
+ */
+
+const {
+    INDIVIDUAL_ACROSS_VALUES,
+    DEFAULT_ORG_ADMIN_ROLES,
+    configError,
+    parseScopeSetting,
+    resolveScope,
+    resolveOwnerForScope,
+} = require('./scope-resolution');
+const {
+    accessContext,
+    accessToOwner,
+    describeRecord,
+} = require('./scope-visibility');
+
+/**
+ * @param {Object} [params]
+ * @param {{scope: *, individualAcross: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [params.ownership] - the raw
+ *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
+ *   `{ default, allow }` parses to itself)
+ * @param {Map} [params.entityTypeRegistry]
+ */
+function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
+    const appScope = parseScopeSetting(
+        ownership?.scope,
+        'appDefinition.ownership.scope'
+    );
+    const individualAcross = ownership?.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+
+    const orgAdminRoles = ownership?.orgAdminRoles ?? DEFAULT_ORG_ADMIN_ROLES;
+    const gateBearerTokens = ownership?.gateBearerTokens === true;
+
+    const contextFor = (user) =>
+        accessContext(user, { individualAcross, orgAdminRoles, gateBearerTokens });
+
+    /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
+    const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
+        resolveScope({
+            request: requestScope,
+            binding,
+            integration,
+            entityType: entityTypeRegistry?.get?.(entityType)?.settings?.scope,
+            app: appScope,
+            primary: user?.config?.primary,
+        });
+
+    /**
+     * Scope, then owner and organization, for a new entity. `legacyOrgId` (the
+     * person's legacy organization pointer) rides along so a later lookup can
+     * reuse an entity written before scoping.
+     */
+    const resolveOwnership = ({ entityType, requestScope, user }) => {
+        const ctx = contextFor(user);
+        const resolved = resolveEntityScope({ entityType, requestScope, user });
+        return {
+            ...resolveOwnerForScope(resolved.scope, ctx),
+            legacyOrgId: ctx.legacyOrgId,
+            source: resolved.source,
+        };
+    };
+
+    /**
+     * 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;
+
+    /**
+     * What `user` may do with a record owned by `ownerId` that has no
+     * organization of its own (a credential): manage, or null when not theirs.
+     */
+    const accessToOwnedBy = (user, ownerId) => accessToOwner(ownerId, contextFor(user));
+
+    return Object.freeze({
+        individualAcross,
+        orgAdminRoles,
+        accessToOwnedBy,
+        accessContext: contextFor,
+        resolveScope: resolveEntityScope,
+        resolveOwnership,
+        ownershipForScope,
+        canUseEntity,
+    });
+}
+
+/** The policy of an app that configures nothing; what a use case gets by default. */
+const DEFAULT_SCOPE_POLICY = createScopePolicy();
+
+module.exports = { createScopePolicy, DEFAULT_SCOPE_POLICY };