@friggframework/core 2.0.0--canary.682.3c8b68a.0 → 2.0.0--canary.683.8a84ab1.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). For permissions the token's role wins; a token with none uses the role stored on the person's membership of the active organization, and is a member when there is none: it cannot create or change organization-level entities or integrations. `user.orgAdminRoles` (default `['ADMIN']`) names the roles that can. Frigg bearer tokens are not gated unless `user.orgAdminGateBearerTokens: true`. |
 
 Rules worth knowing:
 

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

@@ -1,5 +1,7 @@
 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 { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
  * Management API v2 credential operations. A credential has no module name
@@ -90,7 +92,8 @@ class GetCredentialForUserV2 {
  * than disappearing from integrations.
  */
 class DeleteCredentialForUser {
-    constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
+    constructor({ credentialRepository, moduleRepository, getCredentialForUser, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
         this.getCredentialForUser = getCredentialForUser;
@@ -101,6 +104,11 @@ 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}`);
         for (const entityId of credential.entityIds) {
             await this.moduleRepository.unsetCredential(entityId);
         }

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

@@ -1,4 +1,6 @@
 const Boom = require('@hapi/boom');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
  * Re-authorization of a credential the caller owns (Management API v2). It
@@ -14,7 +16,11 @@ 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),
+        ownerId: credential.userId,
+    };
 }
 
 /** GET /api/v2/credentials/:credentialId/reauthorize */
@@ -25,7 +31,7 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const binding = await credentialEntityType(
+        const { ownerId, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
@@ -42,17 +48,21 @@ class GetCredentialReauthorization {
 
 /** POST /api/v2/credentials/:credentialId/reauthorize */
 class ReauthorizeCredentialForUser {
-    constructor({ getCredentialForUser, submitAuthorizationStep }) {
+    constructor({ getCredentialForUser, submitAuthorizationStep, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.getCredentialForUser = getCredentialForUser;
         this.submitAuthorizationStep = submitAuthorizationStep;
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const binding = await credentialEntityType(
+        const { ownerId, ...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}`);
         return this.submitAuthorizationStep.execute({
             user,
             ...binding,

package/index.js

@@ -71,6 +71,7 @@ const {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
+    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
 } = require('./integrations/index');
 const {
@@ -166,6 +167,8 @@ module.exports = {
     Options,
     checkRequiredParams,
     createIntegrationRouter,
+    // Deprecated (ADR-059): use getEntityTypeRegistry.
+    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     CreateProcess,
     UpdateProcessState,

package/integrations/index.js

@@ -4,6 +4,9 @@ const {
     createIntegrationRouter,
     checkRequiredParams,
 } = require('./integration-router');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('./utils/map-integration-dto');
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
@@ -18,6 +21,8 @@ module.exports = {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
+    // Deprecated (ADR-059): a wrapper over getEntityTypeRegistry.
+    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     validateExtensionBinding,
     getExtensionRoutes,

package/integrations/integration-router.js

@@ -65,6 +65,9 @@ const { createScopePolicy } = require('../modules/scope-policy');
 const {
     AuthorizeEntityForUser,
 } = require('../modules/use-cases/authorize-entity-for-user');
+const {
+    CreateEntityFromCredential,
+} = require('../modules/use-cases/create-entity-from-credential');
 const {
     ResolveIntegrationOwnership,
 } = require('./use-cases/resolve-integration-ownership');
@@ -199,14 +202,22 @@ function createIntegrationRouter() {
     });
 
     // The owner of what an authorization creates follows its scope (ADR-056 §3.2).
+    const processAuthorizationCallback = new ProcessAuthorizationCallback({
+        moduleRepository,
+        credentialRepository,
+        integrationRepository,
+        moduleDefinitions,
+    });
     const authorizeEntityForUser = new AuthorizeEntityForUser({
         scopePolicy,
-        processAuthorizationCallback: new ProcessAuthorizationCallback({
-            moduleRepository,
-            credentialRepository,
-            integrationRepository,
-            moduleDefinitions,
-        }),
+        processAuthorizationCallback,
+    });
+    // v1 POST /api/entity: same owner resolution as /api/authorize.
+    const createEntityFromCredential = new CreateEntityFromCredential({
+        authorizeEntityForUser,
+        processAuthorizationCallback,
+        credentialRepository,
+        moduleDefinitions,
     });
 
     const router = express();
@@ -231,6 +242,7 @@ function createIntegrationRouter() {
         getEntityOptionsById,
         refreshEntityOptions,
         authorizeEntityForUser,
+        createEntityFromCredential,
     });
     return router;
 }
@@ -279,9 +291,11 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
     } = useCases;
 
     // The owner of an integration the caller may reach (404 otherwise), which is
-    // what the id-and-owner use cases below expect.
-    const ownerOf = async (integrationId, user) =>
-        (await getOwnedIntegrationRecord.execute(integrationId, user)).userId;
+    // what the id-and-owner use cases below expect. `manage: true` is for
+    // changing or deleting: an organization's integration needs an admin (403).
+    const ownerOf = async (integrationId, user, options) =>
+        (await getOwnedIntegrationRecord.execute(integrationId, user, options))
+            .userId;
 
     router.route('/api/integrations').get(
         catchAsyncError(async (req, res) => {
@@ -333,7 +347,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
 
             const integration = await updateIntegration.execute(
                 req.params.integrationId,
-                await ownerOf(req.params.integrationId, user),
+                await ownerOf(req.params.integrationId, user, { manage: true }),
                 params.config
             );
             res.json(integration);
@@ -346,7 +360,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             await deleteIntegrationForUser.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                await ownerOf(params.integrationId, user, { manage: true })
             );
             res.status(204).json({});
         })
@@ -527,6 +541,7 @@ function setEntityRoutes(router, authenticateUser, useCases) {
         getEntityOptionsById,
         refreshEntityOptions,
         authorizeEntityForUser,
+        createEntityFromCredential,
     } = useCases;
 
     router.route('/api/authorize').get(
@@ -601,35 +616,20 @@ function setEntityRoutes(router, authenticateUser, useCases) {
     router.route('/api/entity').post(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
-            const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
                 'data',
             ]);
             checkRequiredParams(req.body.data, ['credential_id']);
 
-            // May want to pass along the user ID as well so credential ID's can't be fished???
-            const credential = await getCredentialForUser.execute(
-                params.data.credential_id,
-                userId
-            );
-
-            if (!credential) {
-                throw Boom.badRequest('Invalid credential ID');
-            }
-
-            const module = await getModuleInstanceFromType.execute(
-                userId,
-                params.entityType
-            );
-            const entityDetails = await module.getEntityDetails(
-                module.api,
-                null,
-                null,
-                userId
+            // The owner follows the entity type's scope, as /api/authorize.
+            res.json(
+                await createEntityFromCredential.execute({
+                    user,
+                    entityType: params.entityType,
+                    credentialId: params.data.credential_id,
+                })
             );
-
-            res.json(await module.findOrCreateEntity(entityDetails));
         })
     );
 

package/integrations/repositories/integration-repository-documentdb.js

@@ -40,7 +40,8 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
      */
     async findIntegrationsByOwnership(clauses) {
         if (!Array.isArray(clauses) || clauses.length === 0) return [];
-        const records = await findMany(this.prisma, 'Integration', {
+        // Drained: a list can hold more than the first cursor batch (~101).
+        const records = await findManyDrained(this.prisma, 'Integration', {
             $or: clauses.map(({ userId, organizationId }) => ({
                 userId: toObjectId(userId),
                 organizationId:

package/integrations/use-cases/integration-operations-for-user.js

@@ -1,6 +1,7 @@
 const Boom = require('@hapi/boom');
 const { describeRecord } = require('../../modules/scope-visibility');
 const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 const { isIntegrationNotFound } = require('../repositories/integration-not-found');
 
 /**
@@ -32,7 +33,14 @@ class GetOwnedIntegrationRecord {
         return describeRecord(record, this.scopePolicy.accessContext(user), 'integration');
     }
 
-    async execute(integrationId, user) {
+    /**
+     * @param {string} integrationId
+     * @param {Object} user - authenticated User
+     * @param {{manage?: boolean}} [options] - `manage: true` for changing or
+     *   deleting: a person may use an organization's integration but only an
+     *   admin may change it (403 ORG_ADMIN_REQUIRED)
+     */
+    async execute(integrationId, user, { manage = false } = {}) {
         let record = null;
         try {
             record = await this.integrationRepository.findIntegrationById(
@@ -47,9 +55,9 @@ class GetOwnedIntegrationRecord {
             }
             throw error;
         }
-        if (!record || !this.describe(record, user)) {
-            throw notFound(integrationId);
-        }
+        const tenancy = record && this.describe(record, user);
+        if (!tenancy) throw notFound(integrationId);
+        if (manage) assertCanManage(tenancy.access, `integration ${integrationId}`);
         return record;
     }
 }
@@ -138,7 +146,8 @@ class UpdateIntegrationForUser {
         }
         const record = await this.getOwnedIntegrationRecord.execute(
             integrationId,
-            user
+            user,
+            { manage: true }
         );
         return this.updateIntegration.execute(record.id, record.userId, config);
     }
@@ -154,7 +163,8 @@ class RemoveIntegrationForUser {
     async execute(integrationId, user) {
         const record = await this.getOwnedIntegrationRecord.execute(
             integrationId,
-            user
+            user,
+            { manage: true }
         );
         await this.deleteIntegrationForUser.execute(record.id, record.userId);
     }

package/integrations/utils/map-integration-dto.js

@@ -19,5 +19,48 @@ function mapIntegrationClassToIntegrationDTO(integration) {
     };
 }
 
+let deprecationLogged = false;
 
-module.exports = { mapIntegrationClassToIntegrationDTO };
+/**
+ * @deprecated Since ADR-059. Read `entityTypeRegistry` / `moduleDefinitions`
+ * from `loadAppDefinition()`, or call `getEntityTypeRegistry(appDefinition)`
+ * and read each entry's `definition`.
+ *
+ * Kept as a wrapper over the entity type registry so callers that imported it
+ * keep working. It returns the registry's definitions, so it follows the
+ * registry's rules: one definition per entity type name (the first wins when
+ * two integrations bind different definitions under one name, as
+ * ModuleFactory already picked), and, when `entities` is passed, registry-only
+ * types are included and conflicts throw `EntityRegistryError`.
+ *
+ * @param {Array<Function>} integrationClasses - integration classes
+ * @param {Object} [entities] - `appDefinition.entities` (ADR-059)
+ * @returns {Array<Object>} API module definitions
+ */
+function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses,
+    entities
+) {
+    // Required here, not at the top: modules/ must not load at require time
+    // of every integration use case that only wants the DTO mapper.
+    const {
+        getEntityTypeRegistry,
+        getEntityTypeDefinitions,
+    } = require('../../modules/entity-type-registry');
+    if (!deprecationLogged) {
+        deprecationLogged = true;
+        const { getLogger } = require('../../logs');
+        getLogger('frigg.integrations').warn(
+            'getModulesDefinitionFromIntegrationClasses is deprecated; use getEntityTypeRegistry (ADR-059)',
+            { eventName: 'frigg.integrations.deprecated_module_definitions' }
+        );
+    }
+    return getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations: integrationClasses, entities })
+    );
+}
+
+module.exports = {
+    mapIntegrationClassToIntegrationDTO,
+    getModulesDefinitionFromIntegrationClasses,
+};

package/management-api/v2/dependencies.js

@@ -252,6 +252,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
             credentialRepository,
             moduleRepository,
             getCredentialForUser,
+            scopePolicy,
         }),
         getCredentialReauthorization: new GetCredentialReauthorization({
             getCredentialForUser,
@@ -260,6 +261,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         reauthorizeCredentialForUser: new ReauthorizeCredentialForUser({
             getCredentialForUser,
             submitAuthorizationStep,
+            scopePolicy,
         }),
 
         // Authorization (multi-step)

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

@@ -3,6 +3,7 @@ const {
     toObjectId,
     fromObjectId,
     findMany,
+    findManyDrained,
     findOne,
     insertOne,
     updateOne,
@@ -87,7 +88,8 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
      */
     async findEntitiesByOwnership(clauses) {
         if (!Array.isArray(clauses) || clauses.length === 0) return [];
-        const docs = await findMany(this.prisma, 'Entity', {
+        // Drained: a list can hold more than the first cursor batch (~101).
+        const docs = await findManyDrained(this.prisma, 'Entity', {
             $or: clauses.map(({ userId, organizationId }) => ({
                 userId: toObjectId(userId),
                 organizationId:
@@ -277,8 +279,9 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
             const objectIds = ids.map(id => toObjectId(id)).filter(Boolean);
             if (objectIds.length === 0) return new Map();
 
-            // Use raw findMany to bypass Prisma encryption extension
-            const rawCredentials = await findMany(this.prisma, 'Credential', {
+            // Raw read to bypass the Prisma encryption extension. Drained:
+            // more ids than the first cursor batch must all come back.
+            const rawCredentials = await findManyDrained(this.prisma, 'Credential', {
                 _id: { $in: objectIds }
             });
 

package/modules/scope-config.js

@@ -8,6 +8,7 @@ const {
     SCOPES,
     INDIVIDUAL_ACROSS_VALUES,
     OWNER_RULES,
+    DEFAULT_ORG_ADMIN_ROLES,
     configError,
     isPlainObject,
     parseScopeSetting,
@@ -75,6 +76,40 @@ function readIntegrationOwnership(integrationClass) {
     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
@@ -118,7 +153,7 @@ function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
  * 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}}
+ * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[], gateBearerTokens: boolean}}
  * @throws {OwnershipConfigError}
  */
 function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
@@ -143,6 +178,8 @@ function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
     return Object.freeze({
         scope: app.scope,
         individualAcross: app.individualAcross,
+        orgAdminRoles: Object.freeze(readOrgAdminRoles(appDefinition)),
+        gateBearerTokens: readGateBearerTokens(appDefinition),
     });
 }
 

package/modules/scope-policy.js

@@ -6,16 +6,21 @@
 
 const {
     INDIVIDUAL_ACROSS_VALUES,
+    DEFAULT_ORG_ADMIN_ROLES,
     configError,
     parseScopeSetting,
     resolveScope,
     resolveOwnerForScope,
 } = require('./scope-resolution');
-const { accessContext, describeRecord } = require('./scope-visibility');
+const {
+    accessContext,
+    accessToOwner,
+    describeRecord,
+} = require('./scope-visibility');
 
 /**
  * @param {Object} [params]
- * @param {{scope: *, individualAcross: string}} [params.ownership] - the raw
+ * @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]
@@ -33,7 +38,11 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         );
     }
 
-    const contextFor = (user) => accessContext(user, { individualAcross });
+    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 }) =>
@@ -65,8 +74,16 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
     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,

package/modules/scope-resolution.js

@@ -25,6 +25,9 @@ const INDIVIDUAL_ACROSS_VALUES = Object.freeze(['organization', 'all']);
 const OWNER_RULES = Object.freeze(['derive', 'individual', 'organization']);
 const ACCESS = Object.freeze({ MANAGE: 'manage', USE: 'use', VIEW: 'view' });
 
+/** The organization roles that may manage organization-level things unless `user.orgAdminRoles` says. */
+const DEFAULT_ORG_ADMIN_ROLES = Object.freeze(['ADMIN']);
+
 /** Raised at app-definition load for an invalid ownership setting. */
 class OwnershipConfigError extends BaseError {
     constructor(message, options) {
@@ -180,6 +183,11 @@ const MISSING_ORGANIZATION =
 const missing = (message, field) =>
     Boom.badRequest(message, { code: 'IDENTITY_REQUIRED', details: { field } });
 
+const adminRequired = (what) =>
+    Boom.forbidden(`only an organization admin can ${what}`, {
+        code: 'ORG_ADMIN_REQUIRED',
+    });
+
 /**
  * The owner and organization for a new entity of `scope` (§3.2):
  *
@@ -200,6 +208,7 @@ function resolveOwnerForScope(scope, ctx) {
     }
     if (scope === SCOPES.ORGANIZATION) {
         if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        if (!ctx.canManageOrg) throw adminRequired('connect an organization-level account');
         return { scope, ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
     }
     throw Boom.forbidden(
@@ -229,6 +238,7 @@ function integrationOwnerKind(entityScopes, rule = 'derive') {
 function resolveIntegrationOwner(kind, ctx) {
     if (kind === SCOPES.ORGANIZATION) {
         if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        if (!ctx.canManageOrg) throw adminRequired('create an organization-level integration');
         return { ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
     }
     if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
@@ -263,6 +273,7 @@ module.exports = {
     INDIVIDUAL_ACROSS_VALUES,
     OWNER_RULES,
     ACCESS,
+    DEFAULT_ORG_ADMIN_ROLES,
     OwnershipConfigError,
     configError,
     isPlainObject,

package/modules/scope-visibility.js

@@ -8,7 +8,8 @@
  */
 
 const { isPresent, idString, sameId } = require('../user/membership');
-const { SCOPES, ACCESS } = require('./scope-resolution');
+const { AUTH_SOURCES } = require('../user/user');
+const { SCOPES, ACCESS, DEFAULT_ORG_ADMIN_ROLES } = require('./scope-resolution');
 
 /**
  * One owner/organization pair a repository ORs into a single query.
@@ -66,15 +67,56 @@ function buildClauses(base, kind) {
     return clauses;
 }
 
+/**
+ * Whether the caller may manage organization-level things (create, change,
+ * delete), ADR-056 §3.6:
+ *
+ * - A shared-secret caller is the app's own backend and may.
+ * - A Frigg bearer token (`/user/login`) predates organization roles and
+ *   carries none. It keeps its pre-roles behaviour and may, unless the app
+ *   sets `user.orgAdminGateBearerTokens: true`; then it is judged like any
+ *   other caller below.
+ * - Otherwise the role is the one the token carries; when it carries none,
+ *   the role stored on the caller's membership of the active organization;
+ *   when there is none, `MEMBER`. A missing role never means admin. An
+ *   unknown source (a `User` built outside AuthenticateUser) is judged this
+ *   way too.
+ *
+ * @param {{authSource: (string|null), orgRole: (string|null), membershipRole: (string|null)}} who
+ * @param {string[]} adminRoles - `user.orgAdminRoles`, compared case-insensitively
+ * @param {{gateBearerTokens?: boolean}} [options]
+ */
+function canManageOrganization(
+    { authSource, orgRole, membershipRole },
+    adminRoles = DEFAULT_ORG_ADMIN_ROLES,
+    { gateBearerTokens = false } = {}
+) {
+    if (authSource === AUTH_SOURCES.SHARED_SECRET) return true;
+    if (authSource === AUTH_SOURCES.BEARER_TOKEN && !gateBearerTokens) return true;
+    let role = 'MEMBER';
+    if (isPresent(orgRole)) role = orgRole;
+    else if (isPresent(membershipRole)) role = membershipRole;
+    role = String(role).toUpperCase();
+    return adminRoles.some((admin) => String(admin).toUpperCase() === role);
+}
+
 /**
  * Who the caller is, for ownership and visibility: their individual user, the
- * organization this request acts in, the legacy `organizationId` pointer, and
- * the clauses that follow from them (computed once).
+ * organization this request acts in, the legacy `organizationId` pointer,
+ * whether they may manage organization-level things, and the clauses that
+ * follow from them (computed once).
  *
  * @param {Object} user - the authenticated `User` (or a `{ getId }` double)
- * @param {{individualAcross?: string}} [options]
+ * @param {{individualAcross?: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [options]
  */
-function accessContext(user, { individualAcross = 'organization' } = {}) {
+function accessContext(
+    user,
+    {
+        individualAcross = 'organization',
+        orgAdminRoles = DEFAULT_ORG_ADMIN_ROLES,
+        gateBearerTokens = false,
+    } = {}
+) {
     const hasUserModel = typeof user?.getIndividualUser === 'function';
     const individual = hasUserModel ? user.getIndividualUser() : null;
     const base = {
@@ -86,8 +128,20 @@ function accessContext(user, { individualAcross = 'organization' } = {}) {
         legacyOrgId: idString(individual?.organizationId),
         individualAcross,
     };
+    const who = {
+        authSource:
+            typeof user?.getAuthSource === 'function' ? user.getAuthSource() : null,
+        orgRole: typeof user?.getOrgRole === 'function' ? user.getOrgRole() : null,
+        membershipRole:
+            typeof user?.getMembershipRole === 'function'
+                ? user.getMembershipRole()
+                : null,
+    };
     return {
         ...base,
+        canManageOrg: canManageOrganization(who, orgAdminRoles, {
+            gateBearerTokens,
+        }),
         clauses: {
             entity: buildClauses(base, 'entity'),
             integration: buildClauses(base, 'integration'),
@@ -112,8 +166,26 @@ function scopeOf(record, ctx) {
     return null;
 }
 
-const accessFor = (scope) =>
-    scope === SCOPES.GLOBAL ? ACCESS.USE : ACCESS.MANAGE;
+/** manage for the person's own; for the organization's, only an admin; use otherwise. */
+const accessFor = (scope, ctx) => {
+    if (scope === SCOPES.INDIVIDUAL) return ACCESS.MANAGE;
+    if (scope === SCOPES.ORGANIZATION) {
+        return ctx.canManageOrg ? ACCESS.MANAGE : ACCESS.USE;
+    }
+    return ACCESS.USE;
+};
+
+/**
+ * What the caller may do with a record owned by `ownerId` that carries no
+ * organization of its own (a credential): manage the person's own, manage the
+ * active organization's only as an admin, nothing otherwise. Null when the
+ * record is not theirs.
+ */
+function accessToOwner(ownerId, ctx) {
+    const scope = scopeOf({ userId: ownerId }, ctx);
+    if (scope !== SCOPES.INDIVIDUAL && scope !== SCOPES.ORGANIZATION) return null;
+    return accessFor(scope, ctx);
+}
 
 /**
  * What a row is to this caller, or null when they may not see it.
@@ -134,7 +206,7 @@ function describeRecord(record, ctx, kind) {
             scope === SCOPES.ORGANIZATION
                 ? idString(record.userId)
                 : idString(record.organizationId),
-        access: accessFor(scope),
+        access: accessFor(scope, ctx),
     };
 }
 
@@ -154,6 +226,8 @@ function matchesListFilters(description, { scope, owner } = {}) {
 }
 
 module.exports = {
+    canManageOrganization,
+    accessToOwner,
     accessContext,
     unscopedRowsBelongHere,
     visibilityClauses,

package/modules/use-cases/create-entity-from-credential.js

@@ -0,0 +1,113 @@
+const Boom = require('@hapi/boom');
+const { Module } = require('../module');
+
+const sameId = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null &&
+    String(a) === String(b);
+
+/**
+ * Creates (or finds) the entity for a credential the caller already holds:
+ * the v1 `POST /api/entity`. The owner and organization follow the scope of
+ * `entityType`, exactly as an authorization does (ADR-056 §3.2, §3.6), so the
+ * owner is decided by `AuthorizeEntityForUser.resolveOwnership` and never by
+ * `user.getId()`. Whatever that resolution refuses (a missing identity, and
+ * an organization-level connection by a non-admin) is refused here too.
+ *
+ * The credential must belong to that owner: an organization entity is built
+ * on the organization's credential, an individual one on the person's own.
+ */
+class CreateEntityFromCredential {
+    /**
+     * @param {Object} params
+     * @param {import('./authorize-entity-for-user').AuthorizeEntityForUser} params.authorizeEntityForUser
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     * @param {Object} params.credentialRepository
+     * @param {Array<Object>} params.moduleDefinitions
+     * @param {Function} [params.createModule] - builds a Module; injectable for tests
+     */
+    constructor({
+        authorizeEntityForUser,
+        processAuthorizationCallback,
+        credentialRepository,
+        moduleDefinitions,
+        createModule,
+    }) {
+        this.authorizeEntityForUser = authorizeEntityForUser;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.credentialRepository = credentialRepository;
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.createModule = createModule || ((params) => new Module(params));
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {string} params.credentialId
+     * @returns {Promise<Object>} the persisted entity
+     */
+    async execute({ user, entityType, credentialId }) {
+        const definition = this.moduleDefinitions.find(
+            (def) =>
+                def.moduleName === entityType ||
+                (typeof def.getName === 'function' && def.getName() === entityType)
+        );
+        if (!definition) {
+            throw Boom.badRequest(`Unknown entity type ${entityType}`, {
+                code: 'ENTITY_TYPE_NOT_FOUND',
+            });
+        }
+
+        const ownership = this.authorizeEntityForUser.resolveOwnership({
+            user,
+            entityType,
+        });
+
+        const credential =
+            await this.credentialRepository.findCredentialById(credentialId);
+        // A missing credential and someone else's are the same answer, so ids
+        // cannot be probed.
+        if (!credential || !sameId(credential.userId, ownership.ownerId)) {
+            throw Boom.badRequest('Invalid credential ID', {
+                code: 'INVALID_CREDENTIAL',
+            });
+        }
+
+        // Built for the owner, with the credential loaded (the repository
+        // returns its tokens flat; a Module reads them from `data`), so the
+        // API can call the provider and a token refresh during
+        // getEntityDetails updates the owner's credential.
+        const { id, userId, externalId, authIsValid, ...data } = credential;
+        const module = this.createModule({
+            userId: ownership.ownerId,
+            definition,
+            entity: {
+                credential: { id, userId, externalId, authIsValid, data },
+            },
+        });
+        const entityDetails =
+            await definition.requiredAuthMethods.getEntityDetails(
+                module.api,
+                null,
+                null,
+                ownership.ownerId
+            );
+        Object.assign(
+            entityDetails.details,
+            module.apiParamsFromEntity(module.api)
+        );
+
+        return this.processAuthorizationCallback.findOrCreateEntity(
+            entityDetails,
+            definition.moduleName,
+            credential.id,
+            {
+                scope: ownership.scope,
+                organizationId: ownership.organizationId,
+                legacyOrgId: ownership.legacyOrgId,
+            }
+        );
+    }
+}
+
+module.exports = { CreateEntityFromCredential };

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

@@ -5,6 +5,7 @@ const {
     matchesListFilters,
 } = require('../scope-visibility');
 const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
+const { assertCanManage } = require('./manage-access');
 
 /**
  * Management API v2 entity operations. Each one starts from
@@ -111,10 +112,10 @@ class RefreshEntityOptionsForUser {
 }
 
 /**
- * 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.
+ * Deletes an entity the caller may manage (the owner; for an organization
+ * entity, an organization admin). 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.
  */
 class DeleteEntityForUser {
     constructor({ getEntityModuleForUser, moduleRepository, integrationRepository }) {
@@ -128,6 +129,10 @@ class DeleteEntityForUser {
             entityId,
             user
         );
+        assertCanManage(
+            this.getEntityModuleForUser.describe(entity, user)?.access,
+            `entity ${entity.id}`
+        );
         const integrations =
             (await this.integrationRepository.findIntegrationsByEntityId(
                 entity.id

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

@@ -60,8 +60,11 @@ class GetEntityOptionsById {
             );
         }
 
+        // 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 = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-module.js

@@ -56,8 +56,11 @@ class GetModule {
             );
         }
 
+        // 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 = new Module({
-            userId,
+            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/refresh-entity-options.js

@@ -61,8 +61,11 @@ class RefreshEntityOptions {
             );
         }
 
+        // 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 = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/modules/use-cases/test-module-auth.js

@@ -60,8 +60,11 @@ class TestModuleAuth {
             );
         }
 
+        // 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 = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.682.3c8b68a.0",
+    "version": "2.0.0--canary.683.8a84ab1.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.682.3c8b68a.0",
-        "@friggframework/prettier-config": "2.0.0--canary.682.3c8b68a.0",
-        "@friggframework/test": "2.0.0--canary.682.3c8b68a.0",
+        "@friggframework/eslint-config": "2.0.0--canary.683.8a84ab1.0",
+        "@friggframework/prettier-config": "2.0.0--canary.683.8a84ab1.0",
+        "@friggframework/test": "2.0.0--canary.683.8a84ab1.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": "3c8b68a5062138b3b869c284daceb427f055aed7"
+    "gitHead": "8a84ab14e5e56c7e7939b1b6a0b656ed9301dcfd"
 }

package/types/modules/index.d.ts

@@ -138,6 +138,16 @@ declare module "@friggframework/core" {
     appDefinition?: Pick<AppDefinition, "entities" | "integrations">
   ): EntityTypeRegistry;
 
+  /**
+   * @deprecated ADR-059. Use `getEntityTypeRegistry(appDefinition)` and read
+   * each entry's `definition`. Returns the registry's definitions for these
+   * integrations (plus registry-only types when `entities` is passed).
+   */
+  export function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses: any[],
+    entities?: AppDefinitionEntities
+  ): any[];
+
   /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
   export class EntityRegistryError extends Error {
     code: "ENTITY_REGISTRY_INVALID";

package/types/user/index.d.ts

@@ -62,6 +62,20 @@ declare module "@friggframework/core/user" {
      * at startup. `strictMembership` wins when both are set.
      */
     strictUserValidation?: boolean;
+    /**
+     * Roles that may manage organization-level things (ADR-056 §3). Default
+     * `['ADMIN']`. The role is the adopter token's role claim, else the stored
+     * membership `orgRole`, else `MEMBER` (never admin). A shared-secret
+     * (`x-frigg` header) caller needs no role, nor does a Frigg bearer token
+     * unless `orgAdminGateBearerTokens`. Compared case-insensitively.
+     * Validated at load.
+     */
+    orgAdminRoles?: string[];
+    /**
+     * Judge Frigg bearer-token callers by role like adopter-token callers.
+     * Default false: they keep their behaviour from before organization roles.
+     */
+    orgAdminGateBearerTokens?: boolean;
     authModes?: UserAuthModes;
     jwtConfig?: AdopterJwtConfig;
   }
@@ -113,5 +127,8 @@ declare module "@friggframework/core/user" {
     /** The organization role from the adopter token for this request, or null. */
     getOrgRole(): string | null;
     setOrgRole(orgRole: string | null): void;
+    /** The stored `orgRole` of the membership of the active organization, or null. Used when the token carries no role. */
+    getMembershipRole(): string | null;
+    setMembershipRole(membershipRole: string | null): void;
   }
 }

package/user/use-cases/authenticate-user.js

@@ -1,5 +1,6 @@
 const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
+const { AUTH_SOURCES } = require('../user');
 
 const log = getLogger('frigg.user.authentication');
 
@@ -68,10 +69,13 @@ class AuthenticateUser {
                 // Validate the API key (authentication)
                 await this.authenticateWithSharedSecret.execute(apiKey);
                 // Get user from x-frigg headers (authorization)
-                return await this.getUserFromXFriggHeaders.execute(
+                const user = await this.getUserFromXFriggHeaders.execute(
                     appUserId,
                     appOrgId
                 );
+                // The app's own backend: trusted to manage organization things.
+                user.setAuthSource(AUTH_SOURCES.SHARED_SECRET);
+                return user;
             }
             log.debug('No x-frigg-api-key header, skipping shared secret', {
                 eventName: `${log.name}.shared_secret_skipped`,
@@ -90,6 +94,7 @@ class AuthenticateUser {
             // Detect JWT format (3 parts separated by dots)
             if (token && token.split('.').length === 3) {
                 const user = await this.getUserFromAdopterJwt.execute(token);
+                user.setAuthSource(AUTH_SOURCES.ADOPTER_JWT);
                 // Validate x-frigg headers match JWT claims if present
                 if (appUserId || appOrgId) {
                     this.validateUserMatch(user, appUserId, appOrgId);
@@ -106,6 +111,7 @@ class AuthenticateUser {
             const user = await this.getUserFromBearerToken.execute(
                 req.headers.authorization
             );
+            user.setAuthSource(AUTH_SOURCES.BEARER_TOKEN);
             // Validate x-frigg headers match token user if present
             if (appUserId || appOrgId) {
                 this.validateUserMatch(user, appUserId, appOrgId);

package/user/use-cases/get-user-from-adopter-jwt.js

@@ -74,8 +74,14 @@ class GetUserFromAdopterJwt {
         const role = claims[roleClaim];
 
         const orgRole = typeof role === 'string' && role !== '' ? role : null;
-        const user = await this._findOrCreateUser(appUserId, appOrgId, orgRole);
+        const { user, membership } = await this._findOrCreateUser(
+            appUserId,
+            appOrgId,
+            orgRole
+        );
         user.setOrgRole(orgRole);
+        // What the membership row says: the role when the token carries none.
+        user.setMembershipRole(membership?.orgRole ?? null);
 
         log.debug('Adopter token accepted', {
             eventName: `${log.name}.accepted`,
@@ -98,12 +104,16 @@ class GetUserFromAdopterJwt {
 
         // The token's organization is the active one whether or not this is
         // the person's first time in it.
-        const { individual } = await this.ensureOrganizationMembership.execute({
-            individual: created.individual,
-            organization: created.organization,
-            orgRole,
-        });
-        return buildUser(cfg, individual, created.organization);
+        const { individual, membership } =
+            await this.ensureOrganizationMembership.execute({
+                individual: created.individual,
+                organization: created.organization,
+                orgRole,
+            });
+        return {
+            user: buildUser(cfg, individual, created.organization),
+            membership,
+        };
     }
 }
 

package/user/user.js

@@ -1,5 +1,20 @@
 const bcrypt = require('bcryptjs');
 
+/**
+ * How the request that produced a `User` proved who it is. Set by
+ * AuthenticateUser, never inferred from a missing value. Organization roles
+ * (ADR-056 §3, §3.6) depend on it: a shared-secret caller is the app's own
+ * backend and is trusted to manage; a Frigg bearer token keeps its pre-roles
+ * behaviour unless the app opts in (`user.orgAdminGateBearerTokens`); an
+ * adopter token has the role it carries, else the stored membership role,
+ * else `MEMBER`.
+ */
+const AUTH_SOURCES = Object.freeze({
+    SHARED_SECRET: 'shared-secret',
+    ADOPTER_JWT: 'adopter-jwt',
+    BEARER_TOKEN: 'bearer-token',
+});
+
 /**
  * Represents a user in the system. The User class is a domain entity,
  * @class User
@@ -18,9 +33,14 @@ class User {
         this.individualUser = individualUser;
         this.organizationUser = organizationUser;
         this.usePassword = usePassword;
-        // Organization role from an adopter token claim (ADR-056 §2). Per request:
-        // the role stored on a membership is only what the first token carried.
+        // Organization role from an adopter token claim (ADR-056 §2), per
+        // request. When present it wins over the stored membership role.
         this.orgRole = null;
+        // The role stored on the person's membership of the active organization
+        // (OrganizationMembership.orgRole); used when the token carries none.
+        this.membershipRole = null;
+        // How this request authenticated (one of AUTH_SOURCES); null until AuthenticateUser says.
+        this.authSource = null;
 
         this.config = {
             primary,
@@ -84,6 +104,14 @@ class User {
         return this.config.individualUserRequired;
     }
 
+    getAuthSource() {
+        return this.authSource;
+    }
+
+    setAuthSource(authSource) {
+        this.authSource = authSource ?? null;
+    }
+
     getOrgRole() {
         return this.orgRole;
     }
@@ -92,6 +120,14 @@ class User {
         this.orgRole = orgRole ?? null;
     }
 
+    getMembershipRole() {
+        return this.membershipRole;
+    }
+
+    setMembershipRole(membershipRole) {
+        this.membershipRole = membershipRole ?? null;
+    }
+
     getIndividualUser() {
         return this.individualUser;
     }
@@ -149,4 +185,4 @@ class User {
     }
 }
 
-module.exports = { User }; 
+module.exports = { User, AUTH_SOURCES };