@friggframework/core 2.0.0--canary.686.3e27a92.0 → 2.0.0--canary.663.8de669c.0

package/modules/use-cases/execute-entity-proxy-request.js

@@ -1,286 +0,0 @@
-const Boom = require('@hapi/boom');
-const { getLogger } = require('../../logs');
-const { getTelemetry } = require('../../telemetry/telemetry-runtime');
-const { ProxyRequestError } = require('../proxy/proxy-errors');
-const { SCOPES } = require('../scope-resolution');
-const { grantsUse } = require('../scope-visibility');
-const { normalizeProxyPath, matchAllowRule } = require('../proxy/proxy-path');
-const {
-    validateProxyRequest,
-    resolveAllowRules,
-    filterRequestHeaders,
-    filterResponseHeaders,
-    decodeResponseBody,
-} = require('../proxy/proxy-policy');
-
-const log = getLogger('frigg.api.proxy');
-
-/** HTTP status and audit outcome for each proxy error code (ADR-052 §10). */
-const ERROR_MAP = {
-    INVALID_PROXY_REQUEST: { status: 400, outcome: 'denied' },
-    PROXY_NOT_ALLOWED: { status: 403, outcome: 'denied' },
-    PAYLOAD_TOO_LARGE: { status: 413, outcome: 'too_large' },
-    UNSUPPORTED_MEDIA_TYPE: { status: 415, outcome: 'denied' },
-    PROXY_NOT_CONFIGURED: { status: 501, outcome: 'denied' },
-    INVALID_CREDENTIALS: { status: 401, outcome: 'upstream_error' },
-    RATE_LIMITED: { status: 429, outcome: 'upstream_error' },
-    UPSTREAM_ERROR: { status: 502, outcome: 'upstream_error' },
-    NETWORK_ERROR: { status: 502, outcome: 'upstream_error' },
-    RESPONSE_TOO_LARGE: { status: 502, outcome: 'too_large' },
-    TIMEOUT: { status: 504, outcome: 'timeout' },
-};
-
-function toBoom(error, extra = {}) {
-    const mapping = ERROR_MAP[error.code] || { status: 502 };
-    const boom = new Boom.Boom(error.message, {
-        statusCode: mapping.status,
-        data: {
-            code: error.code,
-            details: error.details,
-            // Every proxy message is written for the caller (no URLs, no
-            // credential material), including the 5xx ones.
-            expose: true,
-            proxy: true,
-            ...extra,
-        },
-    });
-    return boom;
-}
-
-const authHeaderNamesOf = (api) =>
-    [api?.api_key_name, api?.API_KEY_NAME].filter(
-        (name) => typeof name === 'string' && name
-    );
-
-/**
- * POST /api/v2/entities/:entityId/proxy (ADR-052): calls the entity's API
- * through its module with the stored credential, inside the limits the app
- * and the module set.
- *
- * Order of checks: request shape and size, path rules, entity visibility in
- * the active organization (404), `use` access (403), the entity's scope
- * against `managementApi.proxy.scopes` (403), the module's allow-list (403,
- * deny by default), credential readiness (401), then the call through
- * Requester._proxyRequest. Every call,
- * allowed or denied, writes one audit record and one usage count. Bodies,
- * headers, query values and the raw path are never logged.
- */
-class ExecuteEntityProxyRequest {
-    /**
-     * @param {Object} params
-     * @param {import('./get-entity-module-for-user').GetEntityModuleForUser} params.getEntityModuleForUser
-     * @param {ReturnType<import('../../management-api/management-api-config').resolveManagementApiConfig>['proxy']} params.proxyConfig
-     * @param {Object} [params.telemetry]
-     * @param {() => number} [params.now]
-     */
-    constructor({ getEntityModuleForUser, proxyConfig, telemetry, now }) {
-        this.getEntityModuleForUser = getEntityModuleForUser;
-        this.proxyConfig = proxyConfig;
-        this.telemetry = telemetry;
-        this.now = now || Date.now;
-    }
-
-    /**
-     * @param {string} entityId
-     * @param {Object} user - authenticated User
-     * @param {Object} request - { method, path, query?, headers?, body? }
-     * @returns {Promise<{ status: number, body: { success: boolean, status: number, headers: Object, data: unknown, dataEncoding?: string } }>}
-     */
-    async execute(entityId, user, request) {
-        const started = this.now();
-        const audit = {
-            userId: user?.getId?.(),
-            organizationId: user?.getOrganizationUser?.()?.id,
-            entityId: String(entityId),
-            method: typeof request?.method === 'string' ? request.method.toUpperCase() : undefined,
-            requestBytes: 0,
-        };
-
-        try {
-            const validated = validateProxyRequest(request, this.proxyConfig);
-            audit.method = validated.method;
-            audit.requestBytes = validated.requestBytes;
-            const path = normalizeProxyPath(validated.path);
-
-            // Visible in the active organization, or 404 (ADR-056 §3.6): the
-            // same clauses the v2 lists use, so a missing entity, another
-            // person's and one paired with another organization look alike.
-            const { entity, definition, module } =
-                await this.getEntityModuleForUser.execute(entityId, user);
-            audit.module = definition.moduleName;
-            this.assertProxyable(entityId, entity, definition, user);
-
-            const credentialRef = entity.credential;
-            const credentialId =
-                credentialRef && typeof credentialRef === 'object'
-                    ? credentialRef.id ?? credentialRef._id
-                    : credentialRef;
-            if (credentialId !== undefined && credentialId !== null) {
-                audit.credentialId = String(credentialId);
-            }
-
-            const { rules } = resolveAllowRules(definition, this.proxyConfig.modules);
-            const rule = matchAllowRule(rules, validated.method, path);
-            if (!rule) {
-                throw new ProxyRequestError(
-                    'PROXY_NOT_ALLOWED',
-                    `Module ${definition.moduleName} does not allow ${validated.method} on this path`,
-                    { module: definition.moduleName, method: validated.method }
-                );
-            }
-            audit.pattern = rule.path;
-
-            const credential = entity.credential;
-            if (!credential || (typeof credential === 'object' && credential.authIsValid === false)) {
-                throw new ProxyRequestError(
-                    'INVALID_CREDENTIALS',
-                    'The entity has no usable credential; re-authorize it'
-                );
-            }
-
-            const authHeaderNames = authHeaderNamesOf(module.api);
-            const headers = filterRequestHeaders(validated.headers, {
-                moduleHeaders: Array.isArray(definition.proxy?.headers) ? definition.proxy.headers : [],
-                authHeaderNames,
-            });
-            if (validated.body !== undefined && !headers['content-type']) {
-                headers['content-type'] = validated.bodyIsJson ? 'application/json' : 'text/plain';
-            }
-
-            const upstream = await module.api._proxyRequest({
-                method: validated.method,
-                path,
-                query: validated.query,
-                headers,
-                body: validated.body,
-                baseUrl: this.resolveBaseUrl(definition, module.api),
-                timeoutMs: this.proxyConfig.timeoutMs,
-                maxResponseBytes: this.proxyConfig.maxResponseBytes,
-                isAllowedRedirect: (nextPath, nextMethod) =>
-                    Boolean(matchAllowRule(rules, nextMethod, nextPath)),
-            });
-            audit.upstreamStatus = upstream.status;
-            audit.responseBytes = upstream.body?.length ?? 0;
-
-            if (upstream.status === 429) {
-                throw Object.assign(
-                    new ProxyRequestError('RATE_LIMITED', 'The upstream API is rate limiting this account', {
-                        upstreamStatus: 429,
-                    }),
-                    { retryAfter: upstream.headers['retry-after'] }
-                );
-            }
-            if (upstream.status >= 500) {
-                throw new ProxyRequestError('UPSTREAM_ERROR', 'The upstream API returned an error', {
-                    upstreamStatus: upstream.status,
-                });
-            }
-
-            const decoded = decodeResponseBody(upstream.body, upstream.contentType, {
-                binary: definition.proxy?.binary === true,
-            });
-            const result = {
-                status: upstream.status,
-                body: {
-                    success: upstream.status < 400,
-                    status: upstream.status,
-                    headers: filterResponseHeaders(upstream.headers, {
-                        redirectBlocked: upstream.redirectBlocked,
-                        authHeaderNames,
-                    }),
-                    data: decoded.data,
-                    ...(decoded.encoding && { dataEncoding: decoded.encoding }),
-                },
-            };
-            this.record(audit, upstream.status < 400 ? 'ok' : 'upstream_error', started);
-            return result;
-        } catch (error) {
-            if (error instanceof ProxyRequestError) {
-                const { outcome = 'upstream_error' } = ERROR_MAP[error.code] || {};
-                this.record(audit, outcome, started, error.code);
-                throw toBoom(error, error.retryAfter ? { retryAfter: error.retryAfter } : {});
-            }
-            const notFound = error?.isBoom && error.output.statusCode === 404;
-            this.record(
-                audit,
-                notFound ? 'denied' : 'error',
-                started,
-                error?.data?.code || (error?.isBoom ? undefined : 'INTERNAL_ERROR')
-            );
-            throw error;
-        }
-    }
-
-    /**
-     * ADR-056 §3.5: the caller needs `use` access to the entity in the active
-     * organization, and the entity's scope must be one the app lets the proxy
-     * accept. `access` and `scope` come from the description the v2 lists
-     * return (GetEntityModuleForUser.describe), never from a second rule.
-     *
-     * Both refusals are 403 PROXY_NOT_ALLOWED: the caller can already see the
-     * entity, so saying it exists leaks nothing. `details.reason` tells them
-     * apart ('access' or 'scope').
-     */
-    assertProxyable(entityId, entity, definition, user) {
-        const tenancy = this.getEntityModuleForUser.describe(entity, user);
-        if (!tenancy) {
-            // Not visible after all: the same 404 as a missing entity.
-            throw Boom.notFound(`Entity ${entityId} not found`, {
-                code: 'ENTITY_NOT_FOUND',
-            });
-        }
-        if (!grantsUse(tenancy.access)) {
-            throw new ProxyRequestError(
-                'PROXY_NOT_ALLOWED',
-                'Proxying through an entity needs use access to it; you can only view this one',
-                { module: definition.moduleName, reason: 'access' }
-            );
-        }
-        // Narrowest by default (§3.5): with no setting only individual
-        // entities are proxied, because proxying through a shared credential
-        // lets any member act on the organization's account.
-        const acceptedScopes = this.proxyConfig.scopes ?? [SCOPES.INDIVIDUAL];
-        if (!acceptedScopes.includes(tenancy.scope)) {
-            throw new ProxyRequestError(
-                'PROXY_NOT_ALLOWED',
-                `The entity proxy does not accept ${tenancy.scope} entities in this app`,
-                { module: definition.moduleName, reason: 'scope', scope: tenancy.scope }
-            );
-        }
-    }
-
-    /** A module may pin its proxy base URL (string, or a function of the api). */
-    resolveBaseUrl(definition, api) {
-        const declared = definition.proxy?.baseUrl;
-        if (typeof declared === 'function') return declared(api);
-        if (typeof declared === 'string') return declared;
-        return undefined;
-    }
-
-    /** One audit record (ADR-048) and one usage count (ADR-011) per call. */
-    record(audit, outcome, started, reason) {
-        const fields = {
-            eventName: 'frigg.api.proxy.request',
-            ...audit,
-            outcome,
-            durationMs: this.now() - started,
-            ...(reason && { reason }),
-        };
-        if (outcome === 'ok' || outcome === 'upstream_error') {
-            log.info('Entity proxy request', fields);
-        } else {
-            log.warn('Entity proxy request refused', fields);
-        }
-        try {
-            (this.telemetry || getTelemetry()).count('frigg.api.proxy.requests', 1, {
-                module: audit.module || 'unknown',
-                method: audit.method || 'unknown',
-                outcome,
-            });
-        } catch {
-            // Telemetry must never break a request.
-        }
-    }
-}
-
-module.exports = { ExecuteEntityProxyRequest, ERROR_MAP };

package/modules/use-cases/get-authorization-requirements.js

@@ -1,100 +0,0 @@
-const Boom = require('@hapi/boom');
-const { findDefinition, getAuthStepCount } = require('./entity-types');
-
-const defaultCreateModule = (params) => {
-    const { Module } = require('../module');
-    return Module.create(params);
-};
-
-/**
- * Normalises what a module returns for a step into the v2 requirements
- * shape: `{ type, data }`. Modules either return `{ type, data }` already
- * (multi-step, JSON-schema forms) or a flat object such as the OAuth2
- * requester's `{ type: 'oauth2', url }`.
- */
-function normalizeRequirements(raw) {
-    if (!raw || typeof raw !== 'object') return { type: 'custom', data: {} };
-    if (raw.data && typeof raw.data === 'object') {
-        return { ...raw, type: raw.type || 'custom' };
-    }
-    const { type, ...data } = raw;
-    return { type: type || 'custom', data };
-}
-
-/**
- * Single-step requirements, from wherever the module declares them: a
- * requiredAuthMethods.getAuthorizationRequirements(api) (the form-based
- * API-key convention `frigg auth` uses), or the Api's own
- * getAuthorizationRequirements() (OAuth2Requester builds the authorize URL).
- */
-async function singleStepRequirements(definition, module) {
-    const declared = definition.requiredAuthMethods?.getAuthorizationRequirements;
-    if (typeof declared === 'function') return declared(module.api);
-    if (typeof module.api?.getAuthorizationRequirements === 'function') {
-        return module.api.getAuthorizationRequirements();
-    }
-    throw Boom.notImplemented(
-        `Module ${definition.moduleName} declares no authorization requirements (add requiredAuthMethods.getAuthorizationRequirements)`,
-        { code: 'REQUIREMENTS_NOT_DECLARED', expose: true }
-    );
-}
-
-/**
- * What the caller must submit for one authorization step of an entity type
- * (Management API v2). Single-step modules use their Api's
- * getAuthorizationRequirements(); multi-step modules declare
- * getAuthStepCount() and getAuthRequirementsForStep(step) on their
- * definition (docs/MULTI_STEP_AUTH_MIGRATION_GUIDE.md).
- */
-class GetAuthorizationRequirements {
-    /**
-     * @param {Object} params
-     * @param {Array<Object>} params.moduleDefinitions
-     * @param {Function} [params.createModule]
-     */
-    constructor({ moduleDefinitions, createModule }) {
-        this.moduleDefinitions = moduleDefinitions || [];
-        this.createModule = createModule || defaultCreateModule;
-    }
-
-    /**
-     * @param {Object} params
-     * @param {string} params.entityType
-     * @param {number} [params.step=1]
-     * @param {string} [params.userId]
-     * @param {string} [params.state] - OAuth state forwarded to the Api.
-     * @returns {Promise<{type: string, data: Object, step: number, totalSteps: number, isMultiStep: boolean}>}
-     */
-    async execute({ entityType, step = 1, userId = null, state } = {}) {
-        const definition = findDefinition(this.moduleDefinitions, entityType);
-        const totalSteps = getAuthStepCount(definition);
-
-        if (!Number.isInteger(step) || step < 1 || step > totalSteps) {
-            throw Boom.badRequest(
-                `step must be between 1 and ${totalSteps} for ${entityType}`,
-                { code: 'INVALID_STEP' }
-            );
-        }
-
-        let raw;
-        if (typeof definition.getAuthRequirementsForStep === 'function') {
-            raw = await definition.getAuthRequirementsForStep(step);
-        } else {
-            const module = await this.createModule({
-                userId,
-                definition,
-                ...(state ? { state } : {}),
-            });
-            raw = await singleStepRequirements(definition, module);
-        }
-
-        return {
-            ...normalizeRequirements(raw),
-            step,
-            totalSteps,
-            isMultiStep: totalSteps > 1,
-        };
-    }
-}
-
-module.exports = { GetAuthorizationRequirements, normalizeRequirements };

package/modules/use-cases/get-entity-module-for-user.js

@@ -1,113 +0,0 @@
-const Boom = require('@hapi/boom');
-const { describeRecord } = require('../scope-visibility');
-const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
-const { isEntityNotFound } = require('../repositories/entity-not-found');
-
-/**
- * True when `user` may act on records owned by `ownerId`. Uses the User
- * domain object's rule (individual or organisation user model) when present.
- * This is the owner-only rule: it ignores the organization a record belongs
- * to, so it no longer decides access to an entity or an integration
- * (modules/scope-visibility.js does). Credentials still use it.
- * @param {Object} user - authenticated User (or a plain { getId } double)
- * @param {string|number} ownerId
- */
-function userOwns(user, ownerId) {
-    if (ownerId === undefined || ownerId === null || !user) return false;
-    if (typeof user.ownsUserId === 'function') return user.ownsUserId(ownerId);
-    return String(user.getId()) === String(ownerId);
-}
-
-const defaultCreateModule = (params) => {
-    const { Module } = require('../module');
-    return Module.create(params);
-};
-
-/**
- * Loads an entity the caller owns and builds its Module (API client
- * hydrated from the persisted entity and credential). Management API v2.
- *
- * A missing entity and one owned by someone else are the same 404, so ids
- * cannot be probed (ADR-052 §3).
- */
-class GetEntityModuleForUser {
-    /**
-     * @param {Object} params
-     * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
-     * @param {Array<Object>} params.moduleDefinitions
-     * @param {Function} [params.createModule] - builds a Module; injectable for tests.
-     * @param {Object} [params.scopePolicy] - from createScopePolicy; with none the
-     *   app configures nothing (ADR-056 §3.1).
-     */
-    constructor({ moduleRepository, moduleDefinitions, createModule, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
-        this.moduleRepository = moduleRepository;
-        this.moduleDefinitions = moduleDefinitions || [];
-        this.createModule = createModule || defaultCreateModule;
-    }
-
-    /**
-     * @param {string} entityId
-     * @param {Object} user - authenticated User
-     * @returns {Promise<{ entity: Object, definition: Object, module: Object }>}
-     */
-    async execute(entityId, user) {
-        const entity = await this.loadOwnedEntity(entityId, user);
-        const definition = this.moduleDefinitions.find(
-            (def) => def.moduleName === entity.moduleName
-        );
-        if (!definition) {
-            throw Boom.notFound(
-                `Entity type ${entity.moduleName} is not configured in this app`,
-                { code: 'ENTITY_TYPE_NOT_FOUND' }
-            );
-        }
-        const module = await this.createModule({
-            userId: entity.userId,
-            entity,
-            definition,
-        });
-        return { entity, definition, module };
-    }
-
-    /**
-     * The entity record, or a 404 when it is missing or the caller may not use
-     * it: not theirs, or paired with another organization (ADR-056 §3.6). A
-     * `global` entity is never the tenant's to load.
-     */
-    async loadOwnedEntity(entityId, user) {
-        let entity = null;
-        try {
-            entity = await this.moduleRepository.findEntityById(entityId);
-        } catch (error) {
-            // Every adapter throws for a missing row, and a malformed id (e.g.
-            // not an integer on Postgres) is "not found" too. Both must be the
-            // 404 another tenant's entity gets, or the status says which ids
-            // exist. Anything else is a real failure.
-            if (
-                isEntityNotFound(error) ||
-                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '')
-            ) {
-                entity = null;
-            } else {
-                throw error;
-            }
-        }
-        if (!entity || !this.describe(entity, user)) {
-            throw Boom.notFound(`Entity ${entityId} not found`, {
-                code: 'ENTITY_NOT_FOUND',
-            });
-        }
-        return entity;
-    }
-
-    /**
-     * `{ scope, owner, organizationId, access }` of an entity to this caller,
-     * or null when they may not see it (§3.4).
-     */
-    describe(entity, user) {
-        return describeRecord(entity, this.scopePolicy.accessContext(user), 'entity');
-    }
-}
-
-module.exports = { GetEntityModuleForUser, userOwns };

package/modules/use-cases/manage-access.js

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