@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/management-api/v2/dto.js

@@ -0,0 +1,143 @@
+/**
+ * Response shapes for Management API v2. Use cases return domain records;
+ * these functions decide what leaves the server. Credential material never
+ * does (see maskCredential).
+ */
+
+const idOf = (value) => {
+    if (value === undefined || value === null) return null;
+    if (typeof value === 'object') {
+        const id = value.id ?? value._id;
+        return id === undefined || id === null ? null : String(id);
+    }
+    return String(value);
+};
+
+/**
+ * `{ scope, owner, organizationId, access }` (ADR-056 §3.4): whose a record is
+ * and what the caller may do with it. Empty when the use case did not say.
+ */
+function tenancyFields(tenancy) {
+    if (!tenancy) return {};
+    return {
+        scope: tenancy.scope,
+        owner: tenancy.owner,
+        organizationId: tenancy.organizationId ?? null,
+        access: tenancy.access,
+    };
+}
+
+/** An entity (connected account). */
+function toEntityDto(entity) {
+    const credential =
+        entity.credential && typeof entity.credential === 'object'
+            ? entity.credential
+            : null;
+    return {
+        id: String(entity.id),
+        type: entity.moduleName ?? null,
+        name: entity.name ?? null,
+        externalId: entity.externalId ?? null,
+        credentialId: idOf(entity.credential ?? entity.credentialId),
+        userId: idOf(entity.userId ?? entity.user),
+        authIsValid:
+            typeof credential?.authIsValid === 'boolean'
+                ? credential.authIsValid
+                : null,
+        ...tenancyFields(entity.tenancy),
+    };
+}
+
+/** An integration, from a hydrated instance or a stored DTO. */
+function toIntegrationDto(integration) {
+    return {
+        id: String(integration.id),
+        entities: integration.entities ?? [],
+        status: integration.status ?? null,
+        config: integration.config ?? {},
+        version: integration.version ?? null,
+        messages: integration.messages ?? {},
+        ...tenancyFields(integration.tenancy),
+    };
+}
+
+// Fields every repository adds around the stored data; everything else on a
+// credential record came from the provider and is treated as secret.
+const CREDENTIAL_METADATA = new Set([
+    'id',
+    '_id',
+    'userId',
+    'user',
+    'externalId',
+    'authIsValid',
+    'createdAt',
+    'updatedAt',
+    'type',
+    'entityIds',
+    'status',
+    // Added by the credential use cases (ADR-056 §3.4); never provider data.
+    'tenancy',
+]);
+
+/**
+ * Masks one stored credential value. Strings keep at most their last four
+ * characters, and only when long enough that four characters reveal nothing
+ * useful; objects and arrays are hidden whole. Numbers, booleans and null
+ * (expiry times, flags) are not secret and pass through.
+ */
+function maskValue(value) {
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return value.length >= 16 ? `****${value.slice(-4)}` : '****';
+    }
+    return '****';
+}
+
+const toIso = (value) => {
+    if (!value) return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+};
+
+/**
+ * A credential with every provider field masked. The keys stay visible so a
+ * client can tell an OAuth credential from an API-key one; the values never
+ * leave the server.
+ */
+function maskCredential(credential) {
+    const data = {};
+    for (const [key, value] of Object.entries(credential)) {
+        if (CREDENTIAL_METADATA.has(key) || value === undefined) continue;
+        data[key] = maskValue(value);
+    }
+    const entityIds = Array.isArray(credential.entityIds)
+        ? credential.entityIds.map(String)
+        : [];
+    return {
+        id: String(credential.id),
+        type: credential.type ?? null,
+        externalId: credential.externalId ?? null,
+        userId: idOf(credential.userId),
+        authIsValid:
+            typeof credential.authIsValid === 'boolean'
+                ? credential.authIsValid
+                : null,
+        entityIds,
+        entityCount: entityIds.length,
+        createdAt: toIso(credential.createdAt),
+        updatedAt: toIso(credential.updatedAt),
+        ...tenancyFields(credential.tenancy),
+        data,
+    };
+}
+
+module.exports = {
+    tenancyFields,
+    toEntityDto,
+    toIntegrationDto,
+    maskCredential,
+    maskValue,
+    idOf,
+};

package/management-api/v2/handlers/authorization.js

@@ -0,0 +1,94 @@
+const { toEntityDto, maskCredential } = require('../dto');
+const { objectBody, requireFields, parseStep, optionalString } = require('../request');
+
+/** The v2 body for a submitted step: masked records when complete. */
+function toAuthorizationResponse(result) {
+    if (result.status !== 'complete') return result;
+    return {
+        status: 'complete',
+        entity: result.entity ? toEntityDto(result.entity) : null,
+        credential: result.credential ? maskCredential(result.credential) : null,
+        ...(result.previousCredentialId && {
+            previousCredentialId: result.previousCredentialId,
+        }),
+    };
+}
+
+/**
+ * Management API v2 authorization handlers (multi-step authorize and
+ * credential re-authorization), keyed by operationId.
+ */
+function createAuthorizationHandlers(useCases) {
+    const {
+        getAuthorizationStep,
+        submitAuthorizationStep,
+        getCredentialReauthorization,
+        reauthorizeCredentialForUser,
+    } = useCases;
+
+    const stepQuery = (req) => ({
+        step: parseStep(req.query.step),
+        sessionId: optionalString(req.query.sessionId, 'sessionId'),
+        state: optionalString(req.query.state, 'state'),
+    });
+
+    const stepBody = (req) => {
+        const body = objectBody(req);
+        return {
+            body,
+            step: parseStep(body.step),
+            sessionId: optionalString(body.sessionId, 'sessionId'),
+        };
+    };
+
+    return {
+        async getAuthorizationRequirements(req, res, user) {
+            const entityType = optionalString(req.query.entityType, 'entityType');
+            requireFields({ entityType }, ['entityType']);
+            res.json(
+                await getAuthorizationStep.execute({
+                    user,
+                    entityType,
+                    ...stepQuery(req),
+                })
+            );
+        },
+
+        async authorize(req, res, user) {
+            const { body, step, sessionId } = stepBody(req);
+            requireFields(body, ['entityType', 'data']);
+            const result = await submitAuthorizationStep.execute({
+                user,
+                entityType: optionalString(body.entityType, 'entityType'),
+                data: body.data,
+                step,
+                sessionId,
+                scope: optionalString(body.scope, 'scope'),
+            });
+            res.json(toAuthorizationResponse(result));
+        },
+
+        async getCredentialReauthorizeRequirements(req, res, user) {
+            res.json(
+                await getCredentialReauthorization.execute(
+                    req.params.credentialId,
+                    user,
+                    stepQuery(req)
+                )
+            );
+        },
+
+        async reauthorizeCredential(req, res, user) {
+            const { body, step, sessionId } = stepBody(req);
+            requireFields(body, ['data']);
+            const result = await reauthorizeCredentialForUser.execute(
+                req.params.credentialId,
+                user,
+                { data: body.data, step, sessionId }
+            );
+            res.json(toAuthorizationResponse(result));
+        },
+    };
+}
+
+module.exports = { createAuthorizationHandlers, toAuthorizationResponse };

package/management-api/v2/handlers/credentials.js

@@ -0,0 +1,33 @@
+const { maskCredential } = require('../dto');
+const { parseListFilters } = require('../request');
+
+/** Management API v2 credential handlers, keyed by operationId. */
+function createCredentialHandlers(useCases) {
+    const { listCredentialsForUser, getCredentialForUser, deleteCredentialForUser } =
+        useCases;
+
+    return {
+        async listCredentials(req, res, user) {
+            const credentials = await listCredentialsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
+            res.json({ credentials: credentials.map(maskCredential) });
+        },
+
+        async getCredential(req, res, user) {
+            res.json(
+                maskCredential(
+                    await getCredentialForUser.execute(req.params.credentialId, user)
+                )
+            );
+        },
+
+        async deleteCredential(req, res, user) {
+            await deleteCredentialForUser.execute(req.params.credentialId, user);
+            res.status(204).end();
+        },
+    };
+}
+
+module.exports = { createCredentialHandlers };

package/management-api/v2/handlers/entities.js

@@ -0,0 +1,77 @@
+const { toEntityDto } = require('../dto');
+const { objectBody, parseStep, parseListFilters } = require('../request');
+
+/** Management API v2 entity and entity-type handlers, keyed by operationId. */
+function createEntityHandlers(useCases) {
+    const {
+        listEntitiesForUser,
+        getEntityForUser,
+        deleteEntityForUser,
+        testEntityAuthForUser,
+        getEntityOptionsForUser,
+        refreshEntityOptionsForUser,
+        listEntityTypes,
+        getEntityType,
+        getAuthorizationRequirements,
+    } = useCases;
+
+    return {
+        async listEntities(req, res, user) {
+            const entities = await listEntitiesForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
+            res.json({ entities: entities.map(toEntityDto) });
+        },
+
+        async listEntityTypes(_req, res, user) {
+            res.json({ types: await listEntityTypes.execute({ user }) });
+        },
+
+        async getEntityType(req, res, user) {
+            res.json(await getEntityType.execute(req.params.entityType, { user }));
+        },
+
+        // Describes a step's requirements without starting an authorization
+        // session; GET /api/v2/authorize starts one.
+        async getEntityTypeRequirements(req, res, user) {
+            res.json(
+                await getAuthorizationRequirements.execute({
+                    entityType: req.params.entityType,
+                    step: parseStep(req.query.step),
+                    userId: user.getId(),
+                })
+            );
+        },
+
+        async getEntity(req, res, user) {
+            res.json(toEntityDto(await getEntityForUser.execute(req.params.entityId, user)));
+        },
+
+        async deleteEntity(req, res, user) {
+            await deleteEntityForUser.execute(req.params.entityId, user);
+            res.status(204).end();
+        },
+
+        async testEntityAuth(req, res, user) {
+            const ok = await testEntityAuthForUser.execute(req.params.entityId, user);
+            res.json({ status: ok ? 'ok' : 'failed' });
+        },
+
+        async getEntityOptions(req, res, user) {
+            res.json(await getEntityOptionsForUser.execute(req.params.entityId, user));
+        },
+
+        async refreshEntityOptions(req, res, user) {
+            res.json(
+                await refreshEntityOptionsForUser.execute(
+                    req.params.entityId,
+                    user,
+                    objectBody(req)
+                )
+            );
+        },
+    };
+}
+
+module.exports = { createEntityHandlers };

package/management-api/v2/handlers/integrations.js

@@ -0,0 +1,128 @@
+const { toIntegrationDto } = require('../dto');
+const { objectBody, optionalString, parseListFilters } = require('../request');
+
+/**
+ * Management API v2 integration handlers, keyed by registry operationId.
+ * Each takes (req, res, user) after authentication and only calls use cases.
+ */
+function createIntegrationHandlers(useCases) {
+    const {
+        getIntegrationsForUser,
+        getPossibleIntegrations,
+        createIntegrationForUser,
+        getIntegrationInstanceForUser,
+        updateIntegrationForUser,
+        removeIntegrationForUser,
+        sendIntegrationEventForUser,
+        runIntegrationActionForUser,
+        testIntegrationAuthForUser,
+    } = useCases;
+
+    const send = (req, user, event, payload) =>
+        sendIntegrationEventForUser.execute(
+            req.params.integrationId,
+            user,
+            event,
+            payload
+        );
+
+    return {
+        async listIntegrations(req, res, user) {
+            const integrations = await getIntegrationsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
+            res.json({ integrations: integrations.map(toIntegrationDto) });
+        },
+
+        async listIntegrationOptions(_req, res) {
+            res.json({ integrations: await getPossibleIntegrations.execute() });
+        },
+
+        async createIntegration(req, res, user) {
+            const { entities, config } = objectBody(req);
+            const integration = await createIntegrationForUser.execute(
+                { entities, config },
+                user
+            );
+            res.status(201).json(toIntegrationDto(integration));
+        },
+
+        async getIntegration(req, res, user) {
+            const instance = await getIntegrationInstanceForUser.execute(
+                req.params.integrationId,
+                user
+            );
+            res.json(toIntegrationDto(instance));
+        },
+
+        async updateIntegration(req, res, user) {
+            const { config } = objectBody(req);
+            const integration = await updateIntegrationForUser.execute(
+                req.params.integrationId,
+                user,
+                config
+            );
+            res.json(toIntegrationDto(integration));
+        },
+
+        async deleteIntegration(req, res, user) {
+            await removeIntegrationForUser.execute(req.params.integrationId, user);
+            res.status(204).end();
+        },
+
+        async getIntegrationConfigOptions(req, res, user) {
+            res.json(await send(req, user, 'GET_CONFIG_OPTIONS'));
+        },
+
+        async refreshIntegrationConfigOptions(req, res, user) {
+            res.json(await send(req, user, 'REFRESH_CONFIG_OPTIONS', objectBody(req)));
+        },
+
+        async listIntegrationActions(req, res, user) {
+            const actionType = optionalString(req.query.actionType, 'actionType');
+            res.json(
+                await send(req, user, 'GET_USER_ACTIONS', actionType ? { actionType } : {})
+            );
+        },
+
+        async getIntegrationActionOptions(req, res, user) {
+            res.json(
+                await send(req, user, 'GET_USER_ACTION_OPTIONS', {
+                    actionId: req.params.actionId,
+                    data: objectBody(req),
+                })
+            );
+        },
+
+        async refreshIntegrationActionOptions(req, res, user) {
+            res.json(
+                await send(req, user, 'REFRESH_USER_ACTION_OPTIONS', {
+                    actionId: req.params.actionId,
+                    data: objectBody(req),
+                })
+            );
+        },
+
+        async runIntegrationAction(req, res, user) {
+            res.json(
+                await runIntegrationActionForUser.execute(
+                    req.params.integrationId,
+                    user,
+                    req.params.actionId,
+                    objectBody(req)
+                )
+            );
+        },
+
+        async testIntegrationAuth(req, res, user) {
+            const { ok, errors } = await testIntegrationAuthForUser.execute(
+                req.params.integrationId,
+                user
+            );
+            res.json(ok ? { status: 'ok' } : { status: 'failed', errors });
+        },
+    };
+}
+
+module.exports = { createIntegrationHandlers };

package/management-api/v2/handlers/proxy.js

@@ -0,0 +1,34 @@
+const { toV2ErrorBody } = require('../../error-response');
+
+/**
+ * POST /api/v2/entities/:entityId/proxy (ADR-052). The HTTP status follows the
+ * upstream status. Proxy failures answer in the api-proxy.schema.json error
+ * shape, which is also the v2 error shape plus `success` and `status`.
+ */
+function createProxyHandlers({ executeEntityProxyRequest }) {
+    return {
+        async proxyEntityRequest(req, res, user) {
+            try {
+                const result = await executeEntityProxyRequest.execute(
+                    req.params.entityId,
+                    user,
+                    req.body
+                );
+                res.status(result.status).json(result.body);
+            } catch (error) {
+                if (!error?.isBoom || !error.data?.proxy) throw error;
+                const status = error.output.statusCode;
+                if (error.data.retryAfter) {
+                    res.set('Retry-After', String(error.data.retryAfter));
+                }
+                res.status(status).json({
+                    success: false,
+                    status,
+                    ...toV2ErrorBody(error),
+                });
+            }
+        },
+    };
+}
+
+module.exports = { createProxyHandlers };

package/management-api/v2/request.js

@@ -0,0 +1,85 @@
+const Boom = require('@hapi/boom');
+const { LIST_OWNERS } = require('../../modules/scope-visibility');
+
+/** The JSON body as an object, or a 400 VALIDATION_ERROR. */
+function objectBody(req) {
+    const body = req.body;
+    if (body === undefined || body === null || body === '') return {};
+    if (typeof body !== 'object' || Array.isArray(body)) {
+        throw Boom.badRequest('Request body must be a JSON object', {
+            code: 'VALIDATION_ERROR',
+        });
+    }
+    return body;
+}
+
+/** Fields that must be present (non-empty) in the body. */
+function requireFields(body, fields) {
+    const missing = fields.filter(
+        (field) =>
+            body[field] === undefined || body[field] === null || body[field] === ''
+    );
+    if (missing.length) {
+        throw Boom.badRequest(
+            `Missing required field${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`,
+            { code: 'VALIDATION_ERROR', details: { missing } }
+        );
+    }
+    return body;
+}
+
+/** A 1-based step number from a query or body value; 1 when absent. */
+function parseStep(value) {
+    if (value === undefined || value === null || value === '') return 1;
+    const step = Number(value);
+    if (!Number.isInteger(step) || step < 1) {
+        throw Boom.badRequest('step must be a positive integer', {
+            code: 'INVALID_STEP',
+        });
+    }
+    return step;
+}
+
+/** An optional string query/body value. */
+function optionalString(value, name) {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value !== 'string') {
+        throw Boom.badRequest(`${name} must be a string`, {
+            code: 'VALIDATION_ERROR',
+            details: { field: name },
+        });
+    }
+    return value;
+}
+
+const LIST_SCOPES = ['individual', 'organization'];
+
+/**
+ * `?scope=individual|organization` and `?owner=me|org` on a list (ADR-056
+ * §3.4). Anything else is a 400.
+ */
+function parseListFilters(query = {}) {
+    const scope = optionalString(query.scope, 'scope');
+    const owner = optionalString(query.owner, 'owner');
+    if (scope !== undefined && !LIST_SCOPES.includes(scope)) {
+        throw Boom.badRequest(`scope must be one of ${LIST_SCOPES.join(', ')}`, {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'scope' },
+        });
+    }
+    if (owner !== undefined && !Object.hasOwn(LIST_OWNERS, owner)) {
+        throw Boom.badRequest('owner must be me or org', {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'owner' },
+        });
+    }
+    return { scope, owner };
+}
+
+module.exports = {
+    objectBody,
+    requireFields,
+    parseStep,
+    optionalString,
+    parseListFilters,
+};