@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

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/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 };

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) => Module.create(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 = await 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

@@ -1,4 +1,11 @@
 const Boom = require('@hapi/boom');
+const {
+    describeRecord,
+    visibilityClauses,
+    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
@@ -6,29 +13,55 @@ const Boom = require('@hapi/boom');
  * (missing or foreign entity = 404).
  */
 
-/** The caller's connected entities. */
+/**
+ * The entities the caller may see in the active organization (ADR-056 §3.4,
+ * §3.6): the organization's own, and the caller's individual ones by the
+ * visibility rule. Each carries `tenancy` ({scope, owner, organizationId,
+ * access}); the stored entity is otherwise untouched.
+ */
 class ListEntitiesForUser {
-    constructor({ moduleRepository }) {
+    constructor({ moduleRepository, scopePolicy }) {
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
-    /** @param {Object} user - authenticated User */
-    async execute(user) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            user.getId()
+    /**
+     * @param {Object} user - authenticated User
+     * @param {{scope?: string, owner?: string}} [filters] - `?scope=` and `?owner=`
+     */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const entities = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
         );
-        return Array.isArray(entities) ? entities : [];
+        const listed = [];
+        for (const entity of Array.isArray(entities) ? entities : []) {
+            // The query is the filter; this is the same rule applied again,
+            // so a repository that returns too much cannot widen the list.
+            const tenancy = describeRecord(entity, ctx, 'entity');
+            if (tenancy && matchesListFilters(tenancy, filters)) {
+                listed.push({ ...entity, tenancy });
+            }
+        }
+        return listed;
     }
 }
 
-/** One entity the caller owns. */
+/** One entity the caller may use, with its `tenancy`. */
 class GetEntityForUser {
     constructor({ getEntityModuleForUser }) {
         this.getEntityModuleForUser = getEntityModuleForUser;
     }
 
     async execute(entityId, user) {
-        return this.getEntityModuleForUser.loadOwnedEntity(entityId, user);
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        return {
+            ...entity,
+            tenancy: this.getEntityModuleForUser.describe(entity, user),
+        };
     }
 }
 
@@ -79,10 +112,10 @@ class RefreshEntityOptionsForUser {
 }
 
 /**
- * Deletes an entity the caller owns. 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 }) {
@@ -96,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/entity-types.js

@@ -59,10 +59,31 @@ function findDefinition(moduleDefinitions, entityType) {
     return definition;
 }
 
-const describeEntry = (name, entry) => ({
+/**
+ * With a scope policy the entry also says which scope a new connection gets
+ * and which a request may choose (ADR-056 §3.1), so a UI can offer the choice.
+ * `global` is never offered: a tenant request cannot create one.
+ */
+const scopeOf = (scopePolicy, name, user) => {
+    if (!scopePolicy) return {};
+    const { scope, source, allow } = scopePolicy.resolveScope({
+        entityType: name,
+        user,
+    });
+    return {
+        scope: {
+            default: scope,
+            allow: allow.filter((value) => value !== 'global'),
+            source,
+        },
+    };
+};
+
+const describeEntry = (name, entry, scopePolicy, user) => ({
     // The registry key is the name the API uses, whatever the definition spells.
     ...describeEntityType(entry.definition, name),
     usedBy: usedByOf(entry),
+    ...scopeOf(scopePolicy, name, user),
 });
 
 function requireRegistry(entityTypeRegistry) {
@@ -78,31 +99,34 @@ function requireRegistry(entityTypeRegistry) {
  * bind each type; it is empty for a registry-only type.
  */
 class ListEntityTypes {
-    constructor({ entityTypeRegistry }) {
+    constructor({ entityTypeRegistry, scopePolicy }) {
         this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute() {
+    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
+    async execute({ user } = {}) {
         return [...this.registry]
-            .map(([name, entry]) => describeEntry(name, entry))
+            .map(([name, entry]) => describeEntry(name, entry, this.scopePolicy, user))
             .sort((a, b) => a.name.localeCompare(b.name));
     }
 }
 
 /** Describes one entity type, looked up by its registry key; 404 when absent. */
 class GetEntityType {
-    constructor({ entityTypeRegistry }) {
+    constructor({ entityTypeRegistry, scopePolicy }) {
         this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute(entityType) {
+    async execute(entityType, { user } = {}) {
         const entry = this.registry.get(entityType);
         if (!entry) {
             throw Boom.notFound(`Entity type '${entityType}' not found`, {
                 code: 'ENTITY_TYPE_NOT_FOUND',
             });
         }
-        return describeEntry(entityType, entry);
+        return describeEntry(entityType, entry, this.scopePolicy, user);
     }
 }