@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.686.821f8a3.0

package/modules/use-cases/entity-types.js

@@ -0,0 +1,139 @@
+const Boom = require('@hapi/boom');
+const { ModuleConstants } = require('../ModuleConstants');
+const { usedByOf } = require('../entity-type-registry');
+
+const AUTH_TYPE_BY_REQUESTER = {
+    [ModuleConstants.authType.oauth2]: 'oauth2',
+    [ModuleConstants.authType.oauth1]: 'oauth1',
+    [ModuleConstants.authType.apiKey]: 'api-key',
+    [ModuleConstants.authType.basic]: 'basic',
+};
+
+const callIfFunction = (target, name) =>
+    typeof target?.[name] === 'function' ? target[name]() : undefined;
+
+/** Number of authorization steps a module declares (1 unless multi-step). */
+function getAuthStepCount(definition) {
+    const count = callIfFunction(definition, 'getAuthStepCount');
+    return Number.isInteger(count) && count > 0 ? count : 1;
+}
+
+/**
+ * Public description of an API module (an "entity type"). Reads only the
+ * definition: display metadata, auth type and step count. Never credentials
+ * or env values.
+ */
+function describeEntityType(definition, typeName = definition.moduleName) {
+    const stepCount = getAuthStepCount(definition);
+    const display = definition.display || {};
+    const description = {
+        type: typeName,
+        name:
+            callIfFunction(definition, 'getDisplayName') ??
+            display.label ??
+            display.name ??
+            typeName,
+        authType:
+            callIfFunction(definition, 'getAuthType') ??
+            AUTH_TYPE_BY_REQUESTER[definition.API?.requesterType] ??
+            'custom',
+        isMultiStep: stepCount > 1,
+        stepCount,
+    };
+    const text = callIfFunction(definition, 'getDescription') ?? display.description;
+    if (text) description.description = text;
+    const capabilities = callIfFunction(definition, 'getCapabilities');
+    if (capabilities !== undefined) description.capabilities = capabilities;
+    return description;
+}
+
+function findDefinition(moduleDefinitions, entityType) {
+    const definition = moduleDefinitions.find(
+        (def) => def.moduleName === entityType
+    );
+    if (!definition) {
+        throw Boom.notFound(`Entity type '${entityType}' not found`, {
+            code: 'ENTITY_TYPE_NOT_FOUND',
+        });
+    }
+    return definition;
+}
+
+/**
+ * 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) {
+    if (!(entityTypeRegistry instanceof Map)) {
+        throw new TypeError('entityTypeRegistry is required (see getEntityTypeRegistry)');
+    }
+    return entityTypeRegistry;
+}
+
+/**
+ * Lists the entity types this app can authorize: registry entries plus every
+ * module an integration binds (ADR-059). `usedBy` names the integrations that
+ * bind each type; it is empty for a registry-only type.
+ */
+class ListEntityTypes {
+    constructor({ entityTypeRegistry, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
+    }
+
+    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
+    async execute({ user } = {}) {
+        return [...this.registry]
+            .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, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
+    }
+
+    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, this.scopePolicy, user);
+    }
+}
+
+module.exports = {
+    ListEntityTypes,
+    GetEntityType,
+    describeEntityType,
+    getAuthStepCount,
+    findDefinition,
+};

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

@@ -0,0 +1,286 @@
+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

@@ -0,0 +1,100 @@
+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-entities-for-user.js

@@ -1,8 +1,11 @@
 const { Module } = require('../module');
 const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+const { describeRecord, visibilityClauses } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntitiesForUser {
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
 
         this.definitionMap = new Map();
@@ -11,21 +14,31 @@ class GetEntitiesForUser {
         }
     }
 
-    async execute(userId) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            userId
+    /**
+     * The entities a `User` may see in the active organization (ADR-056 §3.6).
+     * @param {Object} user - authenticated User
+     */
+    async execute(user) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const found = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
+        );
+        const entities = (found || []).filter((entity) =>
+            describeRecord(entity, ctx, 'entity')
         );
 
-        return entities.map((entity) => {
-            const definition = this.definitionMap.get(entity.moduleName);
+        return Promise.all(
+            entities.map(async (entity) => {
+                const definition = this.definitionMap.get(entity.moduleName);
 
-            const moduleInstance = new Module({
-                userId,
-                definition: definition,
-                entity: entity,
-            });
-            return mapModuleClassToModuleDTO(moduleInstance);
-        });
+                const moduleInstance = await Module.create({
+                    userId: entity.userId,
+                    definition: definition,
+                    entity: entity,
+                });
+                return mapModuleClassToModuleDTO(moduleInstance);
+            })
+        );
     }
 }