@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

package/modules/scope-resolution.js

@@ -0,0 +1,288 @@
+/**
+ * Scope resolution and ownership on create (ADR-056 §3.1, §3.2, §3.6).
+ *
+ * No I/O: everything here is a function of what it is handed (settings, a
+ * request's identity context, stored rows). This file also holds the shared
+ * constants and `OwnershipConfigError`, so `scope-config.js` (which validates
+ * app definitions) and `scope-visibility.js` can import them without a cycle.
+ *
+ * There is no `scope` column. The owner's user type already says it: no owner
+ * is `global`, the active organization's user is `organization`, the caller's
+ * individual user is `individual` (docs/guides/entity-scopes.md).
+ */
+
+const Boom = require('@hapi/boom');
+const { BaseError } = require('../errors/base-error');
+const { isPresent, sameId } = require('../user/membership');
+
+const SCOPES = Object.freeze({
+    INDIVIDUAL: 'individual',
+    ORGANIZATION: 'organization',
+    GLOBAL: 'global',
+});
+const SCOPE_VALUES = Object.freeze(Object.values(SCOPES));
+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) {
+        super(message, options);
+        this.code = 'OWNERSHIP_CONFIG_INVALID';
+    }
+}
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const configError = (where, message) =>
+    new OwnershipConfigError(`${where}: ${message}`);
+
+/**
+ * One level's setting: a scope (`'organization'`) or a default plus what a
+ * request may choose (`{ default, allow }`). Returns `{ default, allow }`, or
+ * null when the level sets nothing. Idempotent on its own output.
+ */
+function parseScopeSetting(setting, where) {
+    if (setting === undefined || setting === null) return null;
+    if (typeof setting === 'string') {
+        if (!SCOPE_VALUES.includes(setting)) {
+            throw configError(
+                where,
+                `scope '${setting}' is not one of ${SCOPE_VALUES.join(', ')}`
+            );
+        }
+        return { default: setting, allow: [setting] };
+    }
+    if (!isPlainObject(setting)) {
+        throw configError(where, 'scope must be a scope name or { default, allow }');
+    }
+    const unknown = Object.keys(setting).filter(
+        (key) => key !== 'default' && key !== 'allow'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown scope setting(s): ${unknown.join(', ')}`);
+    }
+    const { allow, default: defaultScope } = setting;
+    if (allow !== undefined) {
+        if (
+            !Array.isArray(allow) ||
+            allow.length === 0 ||
+            allow.some((value) => !SCOPE_VALUES.includes(value)) ||
+            new Set(allow).size !== allow.length
+        ) {
+            throw configError(
+                where,
+                `scope.allow must list one or more of ${SCOPE_VALUES.join(', ')} once each`
+            );
+        }
+    }
+    if (defaultScope !== undefined && !SCOPE_VALUES.includes(defaultScope)) {
+        throw configError(
+            where,
+            `scope.default '${defaultScope}' is not one of ${SCOPE_VALUES.join(', ')}`
+        );
+    }
+    if (defaultScope === undefined && (allow === undefined || allow.length !== 1)) {
+        throw configError(where, 'scope needs a default (or an allow list of exactly one)');
+    }
+    const resolvedDefault = defaultScope ?? allow[0];
+    const resolvedAllow = allow ?? [resolvedDefault];
+    if (!resolvedAllow.includes(resolvedDefault)) {
+        throw configError(
+            where,
+            `scope.default '${resolvedDefault}' must be in scope.allow`
+        );
+    }
+    return { default: resolvedDefault, allow: [...resolvedAllow] };
+}
+
+/** The level-6 default: `organization` for an organization-primary app. */
+const defaultScopeFor = (primary) =>
+    primary === 'organization' ? SCOPES.ORGANIZATION : SCOPES.INDIVIDUAL;
+
+const LEVELS = ['binding', 'integration', 'entityType', 'app'];
+
+/**
+ * The first level that sets a scope (ADR-056 §3.1), each overriding those
+ * below it; nothing intersects. Returns `{ default, allow, source }`.
+ */
+function decideLevel({ binding, integration, entityType, app, primary } = {}) {
+    const settings = { binding, integration, entityType, app };
+    for (const source of LEVELS) {
+        const parsed = parseScopeSetting(settings[source], `${source} scope`);
+        if (parsed) return { ...parsed, source };
+    }
+    const fallback = defaultScopeFor(primary);
+    return { default: fallback, allow: [fallback], source: 'default' };
+}
+
+/**
+ * What a request may choose, from the deciding level's `allow` list only. A
+ * tenant request is never given `global`; a scope outside the list is refused.
+ * Both are the same refusal (403 SCOPE_NOT_ALLOWED): the caller asked for
+ * something this app does not offer.
+ */
+function applyRequest(decided, request) {
+    const result = {
+        scope: decided.default,
+        source: decided.source,
+        decidedBy: decided.source,
+        allow: decided.allow,
+    };
+    if (request === undefined || request === null) return result;
+    if (!SCOPE_VALUES.includes(request)) {
+        throw Boom.badRequest(
+            `scope must be one of ${SCOPE_VALUES.filter((s) => s !== SCOPES.GLOBAL).join(', ')}`,
+            { code: 'SCOPE_INVALID', details: { field: 'scope' } }
+        );
+    }
+    if (request === SCOPES.GLOBAL) {
+        throw Boom.forbidden(
+            'global entities are created by the app owner through admin routes, not by a tenant request',
+            { code: 'SCOPE_NOT_ALLOWED' }
+        );
+    }
+    if (!decided.allow.includes(request)) {
+        throw Boom.forbidden(
+            `scope '${request}' is not allowed here; allowed: ${decided.allow.join(', ')}`,
+            {
+                code: 'SCOPE_NOT_ALLOWED',
+                details: { field: 'scope', allowed: decided.allow },
+            }
+        );
+    }
+    return { ...result, scope: request, source: 'request' };
+}
+
+/**
+ * The scope a new connection gets: decideLevel then applyRequest.
+ *
+ * @param {Object} levels
+ * @param {string} [levels.request] - `scope` on the request
+ * @param {*} [levels.binding] - `use(module, { scope })` / `Definition.entities[key].scope`
+ * @param {*} [levels.integration] - `Definition.ownership.scope`
+ * @param {*} [levels.entityType] - registry `settings.scope` (ADR-059)
+ * @param {*} [levels.app] - `appDefinition.ownership.scope`
+ * @param {string} [levels.primary] - `user.primary`
+ * @returns {{scope: string, source: string, decidedBy: string, allow: string[]}}
+ */
+function resolveScope({ request, ...levels } = {}) {
+    return applyRequest(decideLevel(levels), request);
+}
+
+const MISSING_INDIVIDUAL =
+    'this request has no individual user; send x-frigg-appuserid (or sign in with a token that names the person)';
+const MISSING_ORGANIZATION =
+    'this request has no active organization; send x-frigg-apporgid (or sign in with a token that names the 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):
+ *
+ *   individual   -> the person; the active organization (null under 'all')
+ *   organization -> the active organization's user, in that organization
+ *   global       -> refused here: the tenant API never creates global entities
+ *
+ * `ctx` is an access context (scope-visibility.accessContext).
+ */
+function resolveOwnerForScope(scope, ctx) {
+    if (scope === SCOPES.INDIVIDUAL) {
+        if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
+        return {
+            scope,
+            ownerId: ctx.callerId,
+            organizationId: ctx.individualAcross === 'all' ? null : ctx.activeOrgId,
+        };
+    }
+    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(
+        'global entities are created by the app owner through admin routes, not through the tenant API',
+        { code: 'SCOPE_NOT_ALLOWED' }
+    );
+}
+
+/**
+ * The owner kind of an integration (§3 "Integration ownership"): the
+ * organization when every entity it uses is organization-scoped, otherwise the
+ * person, unless `Definition.ownership.owner` says. ResolveIntegrationOwnership
+ * then refuses an integration whose entities are not all of that one scope.
+ */
+function integrationOwnerKind(entityScopes, rule = 'derive') {
+    if (rule === 'individual' || rule === 'organization') return rule;
+    return entityScopes.length > 0 &&
+        entityScopes.every((scope) => scope === SCOPES.ORGANIZATION)
+        ? SCOPES.ORGANIZATION
+        : SCOPES.INDIVIDUAL;
+}
+
+/**
+ * The owner and organization of a new integration of owner kind `kind`
+ * ('individual' | 'organization').
+ */
+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');
+    return { ownerId: ctx.callerId, organizationId: ctx.activeOrgId };
+}
+
+/**
+ * The entity an authorization should reuse. The same provider account in two
+ * organizations is two entities (§3.6), so an exact organization match wins.
+ * A legacy row (organizationId null, written before scoping) is reused when
+ * the visibility rule would show it here: an organization-owned one always
+ * (the owner is unambiguous), an individual one only in the person's legacy
+ * organization.
+ */
+function pickExistingEntity(candidates, { scope, organizationId, legacyOrgId }) {
+    const rows = candidates || [];
+    const unscoped = (row) => !isPresent(row.organizationId);
+    const exact = rows.find((row) =>
+        isPresent(organizationId)
+            ? sameId(row.organizationId, organizationId)
+            : unscoped(row)
+    );
+    if (exact) return exact;
+    const legacyApplies =
+        scope === SCOPES.ORGANIZATION || sameId(legacyOrgId, organizationId);
+    return legacyApplies ? rows.find(unscoped) ?? null : null;
+}
+
+module.exports = {
+    SCOPES,
+    SCOPE_VALUES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    ACCESS,
+    DEFAULT_ORG_ADMIN_ROLES,
+    OwnershipConfigError,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    decideLevel,
+    applyRequest,
+    resolveScope,
+    resolveOwnerForScope,
+    integrationOwnerKind,
+    resolveIntegrationOwner,
+    pickExistingEntity,
+};

package/modules/scope-visibility.js

@@ -0,0 +1,247 @@
+/**
+ * Which stored rows a caller may see and use (ADR-056 §3.4, §3.6).
+ *
+ * No I/O. One clause list (`ctx.clauses`) is what a repository is asked for and
+ * what `describeRecord` checks every returned row against, so a list and an
+ * access check cannot drift apart. The clauses are built once per request, when
+ * the access context is.
+ */
+
+const { isPresent, idString, sameId } = require('../user/membership');
+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.
+ * `userId` is the owner's user id, and for an organization-owned row that is
+ * the ORGANIZATION user's id, not a person's. `organizationId: null` means "has
+ * no organization" (unset or null); otherwise the id of the organization.
+ *
+ * @typedef {Object} OwnershipClause
+ * @property {string} userId
+ * @property {(string|null)} organizationId
+ */
+
+/**
+ * Whether the caller's own rows with no organization belong to the context this
+ * request acts in: always when it acts in no organization (today's behaviour),
+ * always for an entity under `individualAcross: 'all'`, and otherwise only in
+ * the person's legacy organization.
+ */
+function unscopedRowsBelongHere(base, kind) {
+    return (
+        !base.activeOrgId ||
+        (kind === 'entity' && base.individualAcross === 'all') ||
+        sameId(base.legacyOrgId, base.activeOrgId)
+    );
+}
+
+/**
+ * What a caller may see, as owner/organization pairs:
+ *
+ *   - the active organization's own rows (owner = the organization), whether
+ *     they carry its id or, written before scoping, none;
+ *   - the caller's rows in the active organization;
+ *   - the caller's rows with no organization, when `unscopedRowsBelongHere`.
+ *
+ * `kind` is 'entity' or 'integration'; only entities may be
+ * organization-independent under 'all' (an integration always belongs to the
+ * organization it was created in).
+ *
+ * @returns {OwnershipClause[]}
+ */
+function buildClauses(base, kind) {
+    const clauses = [];
+    if (base.activeOrgId) {
+        clauses.push({ userId: base.activeOrgId, organizationId: base.activeOrgId });
+        clauses.push({ userId: base.activeOrgId, organizationId: null });
+    }
+    if (base.callerId) {
+        if (base.activeOrgId) {
+            clauses.push({ userId: base.callerId, organizationId: base.activeOrgId });
+        }
+        if (unscopedRowsBelongHere(base, kind)) {
+            clauses.push({ userId: base.callerId, organizationId: null });
+        }
+    }
+    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,
+ * 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, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [options]
+ */
+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 = {
+        callerId: hasUserModel ? idString(individual?.id) : idString(user?.getId?.()),
+        activeOrgId:
+            typeof user?.getActiveOrganizationId === 'function'
+                ? idString(user.getActiveOrganizationId())
+                : null,
+        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'),
+        },
+    };
+}
+
+/** The clauses for `kind` ('entity' | 'integration'): what to ask the repository. */
+const visibilityClauses = (ctx, kind) => ctx.clauses[kind];
+
+const matchesClause = (record, clause) =>
+    sameId(record.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? !isPresent(record.organizationId)
+        : sameId(record.organizationId, clause.organizationId));
+
+/** The scope a stored row has for this caller, from its owner. */
+function scopeOf(record, ctx) {
+    if (!isPresent(record?.userId)) return SCOPES.GLOBAL;
+    if (sameId(record.userId, ctx.activeOrgId)) return SCOPES.ORGANIZATION;
+    if (sameId(record.userId, ctx.callerId)) return SCOPES.INDIVIDUAL;
+    return null;
+}
+
+/** 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;
+};
+
+/**
+ * Whether an access level lets the caller use a record: bind it, proxy through
+ * it (§3.4). `manage` includes `use`; `view` (metadata only) does not, and
+ * neither does anything unrecognised.
+ */
+const grantsUse = (access) => access === ACCESS.USE || access === ACCESS.MANAGE;
+
+/**
+ * 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.
+ * `{ scope, owner: {type, id}, organizationId, access }` (§3.4). A `global`
+ * row is never described: it is not the tenant's to see.
+ */
+function describeRecord(record, ctx, kind) {
+    if (!record) return null;
+    const scope = scopeOf(record, ctx);
+    if (scope === null || scope === SCOPES.GLOBAL) return null;
+    if (!ctx.clauses[kind].some((clause) => matchesClause(record, clause))) {
+        return null;
+    }
+    return {
+        scope,
+        owner: { type: scope, id: idString(record.userId) },
+        organizationId:
+            scope === SCOPES.ORGANIZATION
+                ? idString(record.userId)
+                : idString(record.organizationId),
+        access: accessFor(scope, ctx),
+    };
+}
+
+/** `?owner=` values and the scope each one means. */
+const LIST_OWNERS = Object.freeze({
+    me: SCOPES.INDIVIDUAL,
+    org: SCOPES.ORGANIZATION,
+});
+
+/** Whether a described row passes `?scope=` and `?owner=`. */
+function matchesListFilters(description, { scope, owner } = {}) {
+    if (scope !== undefined && description.scope !== scope) return false;
+    if (owner !== undefined && description.owner.type !== LIST_OWNERS[owner]) {
+        return false;
+    }
+    return true;
+}
+
+module.exports = {
+    canManageOrganization,
+    accessToOwner,
+    accessContext,
+    unscopedRowsBelongHere,
+    visibilityClauses,
+    matchesClause,
+    scopeOf,
+    describeRecord,
+    grantsUse,
+    LIST_OWNERS,
+    matchesListFilters,
+};

package/modules/tests/doubles/in-memory-authorization-session-repository.js

@@ -0,0 +1,45 @@
+const { AuthorizationSession } = require('../../domain/authorization-session');
+
+/** In-memory AuthorizationSession repository for tests. */
+class InMemoryAuthorizationSessionRepository {
+    constructor() {
+        this.rows = new Map();
+    }
+
+    _copy(session) {
+        return new AuthorizationSession({ ...session, stepData: { ...session.stepData } });
+    }
+
+    async create(session) {
+        this.rows.set(session.sessionId, this._copy(session));
+        return this._copy(session);
+    }
+
+    async findBySessionId(sessionId) {
+        const row = this.rows.get(sessionId);
+        if (!row || row.isExpired()) return null;
+        return this._copy(row);
+    }
+
+    async update(session) {
+        this.rows.set(session.sessionId, this._copy(session));
+        return this._copy(session);
+    }
+
+    async deleteBySessionId(sessionId) {
+        return this.rows.delete(sessionId) ? 1 : 0;
+    }
+
+    async deleteExpired(now = new Date()) {
+        let removed = 0;
+        for (const [id, row] of this.rows) {
+            if (row.isExpired(now)) {
+                this.rows.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+}
+
+module.exports = { InMemoryAuthorizationSessionRepository };

package/modules/tests/doubles/ownership-matching.js

@@ -0,0 +1,18 @@
+/**
+ * Test double helper: answers an owner/organization clause the way a database
+ * does, so in-memory repositories run the clauses a use case hands them.
+ * `clause.organizationId === null` matches a row with no organization (unset
+ * or null).
+ */
+const same = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b);
+
+const matchesClause = (row, clause) =>
+    same(row.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? row.organizationId === null || row.organizationId === undefined
+        : same(row.organizationId, clause.organizationId));
+
+const matchesAnyClause = (row, clauses) => clauses.some((clause) => matchesClause(row, clause));
+
+module.exports = { same, matchesClause, matchesAnyClause };

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

@@ -0,0 +1,61 @@
+/**
+ * Authorizes an entity for a caller: decides who will own it and in which
+ * organization (ADR-056 §3.2, §3.6), then runs the module's authorization.
+ * Shared by the v1 `POST /api/authorize` and the v2 authorize flow, so the
+ * owner is decided in one place and never by `user.primary`.
+ */
+class AuthorizeEntityForUser {
+    /**
+     * @param {Object} params
+     * @param {Object} params.scopePolicy - from createScopePolicy
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     */
+    constructor({ scopePolicy, processAuthorizationCallback }) {
+        this.scopePolicy = scopePolicy;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+    }
+
+    /**
+     * 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, fixedScope?: string}} params
+     *   `fixedScope`: a re-authorization keeps the scope its connection has
+     */
+    resolveOwnership({ user, entityType, scope, fixedScope }) {
+        if (fixedScope) return this.scopePolicy.ownershipForScope({ scope: fixedScope, user });
+        return this.scopePolicy.resolveOwnership({
+            entityType,
+            requestScope: scope,
+            user,
+        });
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {Object} params.data - what the module's authorization needs
+     * @param {string} [params.scope] - the scope the request asks for
+     * @param {Object} [params.ownership] - from `resolveOwnership`, when the
+     *   caller needed it earlier (a multi-step flow does)
+     * @returns {Promise<{result: Object, ownership: Object}>} the callback's
+     *   `{ credential_id, entity_id, type }` and the ownership it ran with
+     */
+    async execute({ user, entityType, data, scope, ownership }) {
+        const resolved = ownership ?? this.resolveOwnership({ user, entityType, scope });
+        const result = await this.processAuthorizationCallback.execute(
+            resolved.ownerId,
+            entityType,
+            data,
+            {
+                scope: resolved.scope,
+                organizationId: resolved.organizationId,
+                legacyOrgId: resolved.legacyOrgId,
+            }
+        );
+        return { result, ownership: resolved };
+    }
+}
+
+module.exports = { AuthorizeEntityForUser };