@friggframework/core 2.0.0--canary.682.cbca9e2.0 → 2.0.0--canary.684.e113124.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:
 

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/integrations/integration-router.js

@@ -279,9 +279,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 +335,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 +348,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({});
         })

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/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,6 +247,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         listCredentialsForUser: new credentialOps.ListCredentialsForUser({
             credentialRepository,
             moduleRepository,
+            scopePolicy,
         }),
         getCredentialForUser,
         deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({

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-config.js

@@ -8,6 +8,7 @@ const {
     SCOPES,
     INDIVIDUAL_ACROSS_VALUES,
     OWNER_RULES,
+    DEFAULT_ORG_ADMIN_ROLES,
     configError,
     isPlainObject,
     parseScopeSetting,
@@ -75,6 +76,26 @@ 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];
+}
+
 /**
  * Every binding of every integration with its resolved scope and where it came
  * from, parsing each integration's settings once. Throws OwnershipConfigError
@@ -118,7 +139,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[]}}
  * @throws {OwnershipConfigError}
  */
 function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
@@ -143,6 +164,7 @@ function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
     return Object.freeze({
         scope: app.scope,
         individualAcross: app.individualAcross,
+        orgAdminRoles: Object.freeze(readOrgAdminRoles(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[]}} [params.ownership] - the raw
  *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
  *   `{ default, allow }` parses to itself)
  * @param {Map} [params.entityTypeRegistry]
@@ -33,7 +38,10 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         );
     }
 
-    const contextFor = (user) => accessContext(user, { individualAcross });
+    const orgAdminRoles = ownership?.orgAdminRoles ?? DEFAULT_ORG_ADMIN_ROLES;
+
+    const contextFor = (user) =>
+        accessContext(user, { individualAcross, orgAdminRoles });
 
     /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
     const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
@@ -61,15 +69,38 @@ 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;
 
+    /**
+     * 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,
     });
 }

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,35 @@ function buildClauses(base, kind) {
     return clauses;
 }
 
+/**
+ * Whether the caller may manage organization-level things (create, change,
+ * delete). A shared-secret caller is the app's own backend and may. A person
+ * with a token has the role the token carries, and `MEMBER` when it carries
+ * none: a missing role never means admin. An unknown source (a `User` built
+ * outside AuthenticateUser) is treated like a token.
+ *
+ * @param {{authSource: (string|null), orgRole: (string|null)}} who
+ * @param {string[]} adminRoles - `user.orgAdminRoles`, compared case-insensitively
+ */
+function canManageOrganization({ authSource, orgRole }, adminRoles = DEFAULT_ORG_ADMIN_ROLES) {
+    if (authSource === AUTH_SOURCES.SHARED_SECRET) return true;
+    const role = String(isPresent(orgRole) ? orgRole : 'MEMBER').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[]}} [options]
  */
-function accessContext(user, { individualAcross = 'organization' } = {}) {
+function accessContext(
+    user,
+    { individualAcross = 'organization', orgAdminRoles = DEFAULT_ORG_ADMIN_ROLES } = {}
+) {
     const hasUserModel = typeof user?.getIndividualUser === 'function';
     const individual = hasUserModel ? user.getIndividualUser() : null;
     const base = {
@@ -86,8 +107,14 @@ 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,
+    };
     return {
         ...base,
+        canManageOrg: canManageOrganization(who, orgAdminRoles),
         clauses: {
             entity: buildClauses(base, 'entity'),
             integration: buildClauses(base, 'integration'),
@@ -112,8 +139,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 +179,7 @@ function describeRecord(record, ctx, kind) {
             scope === SCOPES.ORGANIZATION
                 ? idString(record.userId)
                 : idString(record.organizationId),
-        access: accessFor(scope),
+        access: accessFor(scope, ctx),
     };
 }
 
@@ -154,6 +199,8 @@ function matchesListFilters(description, { scope, owner } = {}) {
 }
 
 module.exports = {
+    canManageOrganization,
+    accessToOwner,
     accessContext,
     unscopedRowsBelongHere,
     visibilityClauses,

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/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/manage-access.js

@@ -0,0 +1,21 @@
+const Boom = require('@hapi/boom');
+const { ACCESS } = require('../scope-resolution');
+
+/**
+ * The one check behind every "may this caller change or delete it" gate
+ * (ADR-056 §3 permissions): the caller may use it but not manage it, so 403
+ * `ORG_ADMIN_REQUIRED`. `access` comes from describeRecord (entities,
+ * integrations) or scopePolicy.accessToOwnedBy (credentials).
+ *
+ * @param {string|null} access - ACCESS value
+ * @param {string} subject - e.g. `entity 5`, for the message
+ */
+function assertCanManage(access, subject) {
+    if (access !== ACCESS.MANAGE) {
+        throw Boom.forbidden(`You may use ${subject} but not change or delete it`, {
+            code: 'ORG_ADMIN_REQUIRED',
+        });
+    }
+}
+
+module.exports = { assertCanManage };

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

@@ -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.682.cbca9e2.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.682.cbca9e2.0",
-        "@friggframework/prettier-config": "2.0.0--canary.682.cbca9e2.0",
-        "@friggframework/test": "2.0.0--canary.682.cbca9e2.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": "cbca9e22cf6af8765f83f03b2e6d3700d1e149b5"
+    "gitHead": "e1131240a890bf30cfee08ba3786458c9e2d1135"
 }

package/types/user/index.d.ts

@@ -62,6 +62,13 @@ declare module "@friggframework/core/user" {
      * at startup. `strictMembership` wins when both are set.
      */
     strictUserValidation?: boolean;
+    /**
+     * Roles (the adopter token's role claim) that may manage organization-level
+     * things (ADR-056 §3). Default `['ADMIN']`; a token with no role claim is
+     * `MEMBER`, never admin; a shared-secret (`x-frigg` header) caller needs no
+     * role. Compared case-insensitively. Validated at load.
+     */
+    orgAdminRoles?: string[];
     authModes?: UserAuthModes;
     jwtConfig?: AdopterJwtConfig;
   }

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/user.js

@@ -1,5 +1,18 @@
 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 person with a token has the role the
+ * token carries, or `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
@@ -21,6 +34,8 @@ class User {
         // 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.
         this.orgRole = null;
+        // How this request authenticated (one of AUTH_SOURCES); null until AuthenticateUser says.
+        this.authSource = null;
 
         this.config = {
             primary,
@@ -84,6 +99,14 @@ class User {
         return this.config.individualUserRequired;
     }
 
+    getAuthSource() {
+        return this.authSource;
+    }
+
+    setAuthSource(authSource) {
+        this.authSource = authSource ?? null;
+    }
+
     getOrgRole() {
         return this.orgRole;
     }
@@ -149,4 +172,4 @@ class User {
     }
 }
 
-module.exports = { User }; 
+module.exports = { User, AUTH_SOURCES };