@friggframework/core 2.0.0--canary.685.a13fdab.0 → 2.0.0--canary.679.a2bcc2f.0

package/integrations/use-cases/resolve-integration-ownership.js

@@ -1,177 +0,0 @@
-const Boom = require('@hapi/boom');
-const { SCOPES, resolveScope } = require('../../modules/scope-resolution');
-const {
-    integrationOwnerKind,
-    resolveIntegrationOwner,
-} = require('../../modules/scope-resolution');
-const {
-    describeRecord,
-    unscopedRowsBelongHere,
-} = require('../../modules/scope-visibility');
-const {
-    bindingScopeSetting,
-    readIntegrationOwnership,
-} = require('../../modules/scope-config');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
-const { entityTypeNameOf } = require('../../modules/entity-type-registry');
-
-const notFound = (entityId) =>
-    Boom.notFound(`Entity ${entityId} not found`, { code: 'ENTITY_NOT_FOUND' });
-
-/**
- * Who owns an integration about to be created, and in which organization
- * (ADR-056 §3, §3.3, §3.6). Shared by the v1 and v2 create paths. Nothing is
- * persisted before this has answered, so a refusal leaves no row behind.
- *
- * Every entity must be one the caller may use in the active organization. A
- * missing one, another organization's and a `global` one are the same 404, so
- * ids cannot be probed. When the integration declares a scope (a binding's
- * `scope` or `Definition.entities[key].scope`, or `Definition.ownership.scope`)
- * the entity's scope must be in it. Levels below the integration (entity type,
- * app, default) decide where a connection is CREATED and do not restrict what
- * an integration may bind, so an app that adds a registry scope later does not
- * break integrations that already use older connections.
- *
- * The owner follows the entities (all organization: the organization;
- * otherwise the person) unless `Definition.ownership.owner` says. Every entity
- * must then be of the owner's own scope: an integration is loaded by its owner,
- * who must own what it uses, so an integration that mixes an organization
- * entity with a person's own, or that names an owner that does not match, is
- * refused with a 400 here, before anything is written.
- */
-class ResolveIntegrationOwnership {
-    /**
-     * @param {Object} params
-     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
-     * @param {Array<Function>} params.integrationClasses
-     * @param {Object} [params.scopePolicy] - from createScopePolicy
-     */
-    constructor({ moduleRepository, integrationClasses, scopePolicy }) {
-        this.moduleRepository = moduleRepository;
-        this.integrationClasses = integrationClasses || [];
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
-    }
-
-    /**
-     * @param {Object} params
-     * @param {Array<string|number>} params.entityIds
-     * @param {Object} params.config - `{ type }`
-     * @param {Object} params.user - authenticated User
-     * @returns {Promise<{ownerId: string, organizationId: (string|null), ownerKind: string, adoptUnscoped: boolean}>}
-     */
-    async execute({ entityIds, config, user }) {
-        const ctx = this.scopePolicy.accessContext(user);
-        const integrationClass = this.integrationClasses.find(
-            (IntegrationClass) => IntegrationClass.Definition?.name === config?.type
-        );
-        const ownership = readIntegrationOwnership(integrationClass);
-
-        const entities = await this.loadEntities(entityIds);
-        const scoped = entities.map((entity) => ({
-            entity,
-            scope: this.acceptedScope({ entity, ctx, integrationClass, ownership }),
-        }));
-
-        const ownerKind = integrationOwnerKind(
-            scoped.map(({ scope }) => scope),
-            ownership.owner
-        );
-        this.assertOneScope(scoped, ownerKind, config?.type);
-        return {
-            ...resolveIntegrationOwner(ownerKind, ctx),
-            ownerKind,
-            // Whether an existing integration with no organization (written
-            // before scoping) is this caller's to reuse. An organization-owned
-            // one is unambiguous: its owner is the organization, whoever asks
-            // and whatever their own legacy pointer says. A person's is theirs
-            // only where scope-visibility says (their legacy organization).
-            adoptUnscoped:
-                ownerKind === SCOPES.ORGANIZATION ||
-                unscopedRowsBelongHere(ctx, 'integration'),
-        };
-    }
-
-    /** Every entity must be of the integration owner's own scope (see the class comment). */
-    assertOneScope(scoped, ownerKind, type) {
-        for (const { entity, scope } of scoped) {
-            if (scope === ownerKind) continue;
-            // The load-time check (resolveOwnershipConfig) only sees declared
-            // scopes; this one sees the entities actually named.
-            if (ownerKind === SCOPES.ORGANIZATION) {
-                throw Boom.badRequest(
-                    "An organization-owned integration cannot use an 'individual' entity: a shared integration must not run on one person's credential",
-                    {
-                        code: 'ORG_INTEGRATION_INDIVIDUAL_ENTITY',
-                        details: { entityId: String(entity.id) },
-                    }
-                );
-            }
-            throw Boom.badRequest(
-                `Integration '${type}' would be owned by the person but uses the organization entity ${entity.id}. An integration must use entities of one scope: all of the person's, or all of the organization's.`,
-                {
-                    code: 'MIXED_ENTITY_SCOPES',
-                    details: { entityId: String(entity.id), scope },
-                }
-            );
-        }
-    }
-
-    async loadEntities(entityIds) {
-        const ids = (entityIds || []).map(String);
-        if (ids.length === 0) return [];
-        let found;
-        try {
-            found = await this.moduleRepository.findEntitiesByIds(ids);
-        } catch (error) {
-            // A malformed id (e.g. not an integer on PostgreSQL) is "not found".
-            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
-                throw notFound(ids[0]);
-            }
-            throw error;
-        }
-        const byId = new Map((found || []).filter(Boolean).map((e) => [String(e.id), e]));
-        return ids.map((id) => {
-            if (!byId.has(id)) throw notFound(id);
-            return byId.get(id);
-        });
-    }
-
-    /** The entity's scope for this caller, or a refusal. */
-    acceptedScope({ entity, ctx, integrationClass, ownership }) {
-        const described = describeRecord(entity, ctx, 'entity');
-        if (!described) throw notFound(entity.id);
-        const { scope } = described;
-
-        const declared = this.declaredScope({ entity, integrationClass, ownership });
-        if (declared && !declared.allow.includes(scope)) {
-            throw Boom.badRequest(
-                `Entity ${entity.id} is ${scope}-scoped, but this integration binds ${entity.moduleName} at ${declared.allow.join(' or ')} scope`,
-                {
-                    code: 'ENTITY_SCOPE_MISMATCH',
-                    details: { entityId: String(entity.id), scope, allowed: declared.allow },
-                }
-            );
-        }
-        return scope;
-    }
-
-    /**
-     * What the integration itself declares for this entity's binding (levels 2
-     * and 3 only), or null when it declares nothing.
-     */
-    declaredScope({ entity, integrationClass, ownership }) {
-        const Definition = integrationClass?.Definition;
-        const key = Object.keys(Definition?.modules || {}).find(
-            (candidate) =>
-                entityTypeNameOf(Definition.modules[candidate]?.definition) ===
-                entity.moduleName
-        );
-        const resolved = resolveScope({
-            binding: key === undefined ? undefined : bindingScopeSetting(Definition, key),
-            integration: ownership.scope,
-        });
-        return resolved.decidedBy === 'default' ? null : resolved;
-    }
-}
-
-module.exports = { ResolveIntegrationOwnership };

package/modules/entity-scope.js

@@ -1,15 +0,0 @@
-/**
- * Entity scopes and ownership (ADR-056 §3), re-exported from the four files it
- * is split into:
- *
- *   scope-resolution  constants, scope resolution, ownership on create
- *   scope-config      reading and validating app-definition settings
- *   scope-visibility  who may see which stored row
- *   scope-policy      the object a use case asks
- */
-module.exports = {
-    ...require('./scope-resolution'),
-    ...require('./scope-config'),
-    ...require('./scope-visibility'),
-    ...require('./scope-policy'),
-};

package/modules/repositories/entity-not-found.js

@@ -1,18 +0,0 @@
-/**
- * The error `findEntityById` throws for an id with no row, and the one
- * predicate that recognises it (as integration-not-found.js does for
- * integrations). The adapters build the error here and use cases match it
- * here, so a missing entity can be told from any other failure without
- * widening a regex.
- *
- * Why it matters: a use case that answers 404 for another tenant's entity must
- * answer the same 404 for an id that does not exist. Otherwise the status code
- * says which ids exist (ADR-052 §3, ADR-056 §3.6).
- */
-const MESSAGE = /^Entity .+ not found$/;
-
-const entityNotFoundError = (id) => new Error(`Entity ${id} not found`);
-
-const isEntityNotFound = (error) => MESSAGE.test(error?.message || '');
-
-module.exports = { entityNotFoundError, isEntityNotFound };

package/modules/scope-config.js

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

package/modules/scope-policy.js

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