@friggframework/core 2.0.0--canary.704.79d9a63.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/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 };

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

@@ -0,0 +1,162 @@
+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
+ * GetEntityModuleForUser, so ownership is checked the same way everywhere
+ * (missing or foreign entity = 404).
+ */
+
+/**
+ * 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, scopePolicy }) {
+        this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    }
+
+    /**
+     * @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')
+        );
+        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 may use, with its `tenancy`. */
+class GetEntityForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user) {
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        return {
+            ...entity,
+            tenancy: this.getEntityModuleForUser.describe(entity, user),
+        };
+    }
+}
+
+/** Runs the module's testAuthRequest against the stored credential. */
+class TestEntityAuthForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    /** @returns {Promise<boolean>} */
+    async execute(entityId, user) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return Boolean(await module.testAuth());
+    }
+}
+
+/** The module's entity options (e.g. objects a user can pick). */
+class GetEntityOptionsForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return module.getEntityOptions();
+    }
+}
+
+/** Refreshes the module's entity options with caller input, then returns them. */
+class RefreshEntityOptionsForUser {
+    constructor({ getEntityModuleForUser }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+    }
+
+    async execute(entityId, user, options = {}) {
+        const { module } = await this.getEntityModuleForUser.execute(
+            entityId,
+            user
+        );
+        return module.refreshEntityOptions(options);
+    }
+}
+
+/**
+ * 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 }) {
+        this.getEntityModuleForUser = getEntityModuleForUser;
+        this.moduleRepository = moduleRepository;
+        this.integrationRepository = integrationRepository;
+    }
+
+    async execute(entityId, user) {
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        assertCanManage(
+            this.getEntityModuleForUser.describe(entity, user)?.access,
+            `entity ${entity.id}`
+        );
+        const integrations =
+            (await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            )) || [];
+        if (integrations.length > 0) {
+            throw Boom.conflict(
+                `Entity ${entity.id} is used by ${integrations.length} integration(s); delete them first`,
+                {
+                    code: 'ENTITY_IN_USE',
+                    details: {
+                        integrationIds: integrations.map((i) => String(i.id)),
+                    },
+                }
+            );
+        }
+        await this.moduleRepository.deleteEntity(entity.id);
+    }
+}
+
+module.exports = {
+    ListEntitiesForUser,
+    GetEntityForUser,
+    TestEntityAuthForUser,
+    GetEntityOptionsForUser,
+    RefreshEntityOptionsForUser,
+    DeleteEntityForUser,
+};