@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

package/modules/proxy/proxy-policy.js

@@ -0,0 +1,277 @@
+const { ProxyRequestError } = require('./proxy-errors');
+const { isValidBaseName } = require('./proxy-bases');
+
+/**
+ * What the entity proxy accepts and returns (ADR-052 §5-§7). Pure functions:
+ * no I/O, so every rule is unit-tested on its own.
+ */
+
+const PROXY_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const METHODS_WITH_BODY = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** Request headers a caller may always send (lower case). */
+const ALLOWED_REQUEST_HEADERS = [
+    'accept',
+    'content-type',
+    'accept-language',
+    'if-match',
+    'if-none-match',
+];
+
+/** Request headers that are refused outright, even if a module lists them. */
+const REJECTED_REQUEST_HEADERS = [
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'host',
+    'forwarded',
+    'x-real-ip',
+    'x-api-key',
+];
+const REJECTED_REQUEST_HEADER_PREFIXES = ['x-forwarded-'];
+
+/** Response headers never passed back (credentials and hop-by-hop). */
+const REMOVED_RESPONSE_HEADERS = [
+    'authorization',
+    'proxy-authorization',
+    'proxy-authenticate',
+    'set-cookie',
+    'set-cookie2',
+    'www-authenticate',
+    'x-api-key',
+    'connection',
+    'keep-alive',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    // The body is re-encoded as JSON, so these no longer describe it.
+    'content-length',
+    'content-encoding',
+];
+
+const invalid = (message, details) =>
+    new ProxyRequestError('INVALID_PROXY_REQUEST', message, details);
+
+/**
+ * A query key ending in `[]` is sent as one `key=value` pair per array
+ * element; the requester applies the same rule (see
+ * `_rawRequest` in requester.js).
+ */
+const isRepeatedQueryKey = (key) => key.endsWith('[]');
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Validates the request body of POST /api/v2/entities/:id/proxy and returns
+ * it with the method upper-cased and the body serialised.
+ *
+ * @param {unknown} request
+ * @param {{ maxRequestBytes: number }} limits
+ * @returns {{ method: string, path: string, base?: string, query?: Object, headers: Object, body?: string, requestBytes: number, bodyIsJson: boolean }}
+ */
+function validateProxyRequest(request, { maxRequestBytes }) {
+    if (!isPlainObject(request)) throw invalid('The proxy request must be a JSON object');
+    const method = typeof request.method === 'string' ? request.method.toUpperCase() : '';
+    if (!PROXY_METHODS.includes(method)) {
+        throw invalid(`method must be one of ${PROXY_METHODS.join(', ')}`, { field: 'method' });
+    }
+    if (typeof request.path !== 'string') {
+        throw invalid('path is required', { field: 'path' });
+    }
+
+    // `base` is a name, never a URL or host; anything else is refused before
+    // a module is looked up. Omitted means `default` (the caller applies it).
+    let base;
+    if (request.base !== undefined && request.base !== null) {
+        if (typeof request.base !== 'string' || !isValidBaseName(request.base)) {
+            throw invalid(
+                'base must be the name of one of the module\'s base URLs (lower case letters, digits and -), not a URL or host',
+                { field: 'base' }
+            );
+        }
+        base = request.base;
+    }
+
+    let query;
+    if (request.query !== undefined && request.query !== null) {
+        if (!isPlainObject(request.query)) throw invalid('query must be an object', { field: 'query' });
+        query = {};
+        for (const [key, value] of Object.entries(request.query)) {
+            const scalar = ['string', 'number', 'boolean'].includes(typeof value);
+            const list = Array.isArray(value) && value.every((v) => typeof v === 'string');
+            if (!scalar && !list) {
+                throw invalid(`query.${key} must be a string, number, boolean or array of strings`, {
+                    field: `query.${key}`,
+                });
+            }
+            // A key ending in `[]` (`fields[]`) is sent once per value, as
+            // Airtable and Fathom expect; every other array goes comma-separated.
+            if (list) {
+                query[key] = isRepeatedQueryKey(key) ? [...value] : value.join(',');
+            } else {
+                query[key] = value;
+            }
+        }
+    }
+
+    const headers = {};
+    if (request.headers !== undefined && request.headers !== null) {
+        if (!isPlainObject(request.headers)) throw invalid('headers must be an object', { field: 'headers' });
+        for (const [name, value] of Object.entries(request.headers)) {
+            if (typeof value !== 'string') {
+                throw invalid(`header ${name} must be a string`, { field: `headers.${name}` });
+            }
+            headers[name.toLowerCase()] = value;
+        }
+    }
+
+    let body;
+    let bodyIsJson = false;
+    if (request.body !== undefined && request.body !== null) {
+        if (!METHODS_WITH_BODY.has(method)) {
+            throw invalid(`${method} requests cannot have a body`, { field: 'body' });
+        }
+        if (typeof request.body === 'string') {
+            body = request.body;
+        } else {
+            body = JSON.stringify(request.body);
+            bodyIsJson = true;
+        }
+    }
+    const requestBytes = body === undefined ? 0 : Buffer.byteLength(body);
+    if (requestBytes > maxRequestBytes) {
+        throw new ProxyRequestError(
+            'PAYLOAD_TOO_LARGE',
+            `The proxied request body is larger than ${maxRequestBytes} bytes`
+        );
+    }
+    return { method, path: request.path, ...(base !== undefined && { base }), query, headers, body, bodyIsJson, requestBytes };
+}
+
+const isWildcardRule = (rule) => rule?.method === '*' || rule?.path === '/**';
+
+// A rule's `base` is checked against the module's declared bases at load, by
+// assertProxyConfig (proxy-bases.js); here only its shape is.
+const isValidRule = (rule) =>
+    isPlainObject(rule) &&
+    typeof rule.method === 'string' &&
+    typeof rule.path === 'string' &&
+    rule.path.startsWith('/') &&
+    (rule.base === undefined || isValidBaseName(rule.base));
+
+/**
+ * The allow-list in force for a module: the app definition's list for it when
+ * one is given (`managementApi.proxy.modules[name].allow`), otherwise the
+ * module's own `proxy.allow`. A module cannot grant itself a wildcard; only
+ * the app definition can. No list means nothing may be proxied.
+ *
+ * @returns {{ rules: Array<{method: string, path: string}>, source: 'app'|'module'|'none', ignored: number }}
+ */
+function resolveAllowRules(definition, moduleOverrides = {}) {
+    const override = moduleOverrides?.[definition.moduleName]?.allow;
+    if (Array.isArray(override)) {
+        return { rules: override.filter(isValidRule), source: 'app', ignored: 0 };
+    }
+    const declared = Array.isArray(definition.proxy?.allow) ? definition.proxy.allow : [];
+    const rules = declared.filter((rule) => isValidRule(rule) && !isWildcardRule(rule));
+    return {
+        rules,
+        source: rules.length ? 'module' : 'none',
+        ignored: declared.length - rules.length,
+    };
+}
+
+/**
+ * Keeps only the request headers the caller may set. A header from the
+ * rejected list (credentials, Host, forwarding headers, or one the module's
+ * own auth sets) fails the request instead of being dropped quietly.
+ *
+ * @param {Object} headers - lower-cased names
+ * @param {Object} options
+ * @param {string[]} [options.moduleHeaders] - from the module's `proxy.headers`
+ * @param {string[]} [options.authHeaderNames] - headers the module's auth sets
+ */
+function filterRequestHeaders(headers, { moduleHeaders = [], authHeaderNames = [] } = {}) {
+    const rejected = new Set([
+        ...REJECTED_REQUEST_HEADERS,
+        ...authHeaderNames.filter(Boolean).map((name) => String(name).toLowerCase()),
+    ]);
+    const allowed = new Set([
+        ...ALLOWED_REQUEST_HEADERS,
+        ...moduleHeaders.map((name) => String(name).toLowerCase()),
+    ]);
+    const kept = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (
+            rejected.has(name) ||
+            REJECTED_REQUEST_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))
+        ) {
+            throw invalid(`The ${name} header cannot be sent through the proxy`, {
+                field: `headers.${name}`,
+            });
+        }
+        if (allowed.has(name)) kept[name] = value;
+    }
+    return kept;
+}
+
+/**
+ * Removes credential and hop-by-hop headers from an upstream response, and
+ * the Location of a redirect the proxy refused to follow.
+ */
+function filterResponseHeaders(headers, { redirectBlocked = false, authHeaderNames = [] } = {}) {
+    const removed = new Set([
+        ...REMOVED_RESPONSE_HEADERS,
+        ...authHeaderNames.filter(Boolean).map((name) => String(name).toLowerCase()),
+    ]);
+    if (redirectBlocked) removed.add('location');
+    const kept = {};
+    for (const [name, value] of Object.entries(headers || {})) {
+        if (!removed.has(name.toLowerCase())) kept[name.toLowerCase()] = value;
+    }
+    return kept;
+}
+
+const JSON_TYPE = /^application\/([a-z0-9.+-]*\+)?json\b/i;
+const TEXT_TYPE = /^(text\/|application\/(xml|x-www-form-urlencoded|javascript|graphql)\b|[a-z]+\/[a-z0-9.+-]*\+xml\b)/i;
+
+/**
+ * Turns the upstream body into the `data` of the proxy response: parsed JSON,
+ * text, or (only if the module allows binary) base64.
+ *
+ * @returns {{ data: unknown, encoding?: 'base64' }}
+ */
+function decodeResponseBody(body, contentType, { binary = false } = {}) {
+    if (!body || body.length === 0) return { data: null };
+    if (JSON_TYPE.test(contentType)) {
+        const text = body.toString('utf8');
+        try {
+            return { data: JSON.parse(text) };
+        } catch {
+            return { data: text };
+        }
+    }
+    if (!contentType || TEXT_TYPE.test(contentType)) {
+        return { data: body.toString('utf8') };
+    }
+    if (binary) return { data: body.toString('base64'), encoding: 'base64' };
+    throw new ProxyRequestError(
+        'UNSUPPORTED_MEDIA_TYPE',
+        'The upstream response is binary and this module does not allow binary proxying',
+        { contentType: contentType.split(';')[0] }
+    );
+}
+
+module.exports = {
+    PROXY_METHODS,
+    ALLOWED_REQUEST_HEADERS,
+    REJECTED_REQUEST_HEADERS,
+    REMOVED_RESPONSE_HEADERS,
+    validateProxyRequest,
+    resolveAllowRules,
+    filterRequestHeaders,
+    filterResponseHeaders,
+    decodeResponseBody,
+};

package/modules/repositories/authorization-session-repository-documentdb.js

@@ -0,0 +1,112 @@
+const { prisma } = require('../../database/prisma');
+const {
+    findOne,
+    insertOne,
+    updateOne,
+    deleteMany,
+} = require('../../database/documentdb-utils');
+const {
+    DocumentDBEncryptionService,
+} = require('../../database/documentdb-encryption-service');
+const { AuthorizationSession } = require('../domain/authorization-session');
+const {
+    AuthorizationSessionRepositoryInterface,
+} = require('./authorization-session-repository-interface');
+
+const COLLECTION = 'AuthorizationSession';
+
+/**
+ * AuthorizationSession persistence for DocumentDB through raw commands.
+ * `stepData` is encrypted with DocumentDBEncryptionService, as the Prisma
+ * extension does not run for raw commands.
+ */
+class AuthorizationSessionRepositoryDocumentDB extends AuthorizationSessionRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async create(session) {
+        const now = new Date();
+        const document = await this.encryptionService.encryptFields(COLLECTION, {
+            sessionId: session.sessionId,
+            userId: session.userId,
+            entityType: session.entityType,
+            credentialId: session.credentialId,
+            currentStep: session.currentStep,
+            maxSteps: session.maxSteps,
+            stepData: session.stepData,
+            expiresAt: session.expiresAt,
+            completed: session.completed,
+            createdAt: now,
+            updatedAt: now,
+        });
+        await insertOne(this.prisma, COLLECTION, document);
+        return this._toDomain(
+            await this.encryptionService.decryptFields(COLLECTION, document)
+        );
+    }
+
+    async findBySessionId(sessionId) {
+        if (typeof sessionId !== 'string' || !sessionId) return null;
+        const document = await findOne(this.prisma, COLLECTION, {
+            sessionId,
+            expiresAt: { $gt: new Date() },
+        });
+        if (!document) return null;
+        return this._toDomain(
+            await this.encryptionService.decryptFields(COLLECTION, document)
+        );
+    }
+
+    async update(session) {
+        const encrypted = await this.encryptionService.encryptFields(COLLECTION, {
+            stepData: session.stepData,
+        });
+        await updateOne(
+            this.prisma,
+            COLLECTION,
+            { sessionId: session.sessionId },
+            {
+                $set: {
+                    currentStep: session.currentStep,
+                    stepData: encrypted.stepData,
+                    completed: session.completed,
+                    updatedAt: new Date(),
+                },
+            }
+        );
+        return session;
+    }
+
+    async deleteBySessionId(sessionId) {
+        const result = await deleteMany(this.prisma, COLLECTION, { sessionId });
+        return result?.n ?? 0;
+    }
+
+    async deleteExpired(now = new Date()) {
+        const result = await deleteMany(this.prisma, COLLECTION, {
+            expiresAt: { $lte: now },
+        });
+        return result?.n ?? 0;
+    }
+
+    _toDomain(document) {
+        return new AuthorizationSession({
+            sessionId: document.sessionId,
+            userId: document.userId,
+            entityType: document.entityType,
+            credentialId: document.credentialId ?? null,
+            currentStep: document.currentStep,
+            maxSteps: document.maxSteps,
+            stepData: document.stepData || {},
+            expiresAt: new Date(document.expiresAt),
+            completed: Boolean(document.completed),
+            createdAt: document.createdAt,
+            updatedAt: document.updatedAt,
+        });
+    }
+}
+
+module.exports = { AuthorizationSessionRepositoryDocumentDB };

package/modules/repositories/authorization-session-repository-factory.js

@@ -0,0 +1,31 @@
+const config = require('../../database/config');
+const {
+    AuthorizationSessionRepositoryPrisma,
+} = require('./authorization-session-repository-prisma');
+const {
+    AuthorizationSessionRepositoryDocumentDB,
+} = require('./authorization-session-repository-documentdb');
+
+/**
+ * AuthorizationSession repository for the configured database. PostgreSQL
+ * and MongoDB share the Prisma adapter; DocumentDB uses raw commands.
+ */
+function createAuthorizationSessionRepository() {
+    switch (config.DB_TYPE) {
+        case 'mongodb':
+        case 'postgresql':
+            return new AuthorizationSessionRepositoryPrisma();
+        case 'documentdb':
+            return new AuthorizationSessionRepositoryDocumentDB();
+        default:
+            throw new Error(
+                `Unsupported database type: ${config.DB_TYPE}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createAuthorizationSessionRepository,
+    AuthorizationSessionRepositoryPrisma,
+    AuthorizationSessionRepositoryDocumentDB,
+};

package/modules/repositories/authorization-session-repository-interface.js

@@ -0,0 +1,47 @@
+/**
+ * Port for persisting AuthorizationSession records (Management API v2
+ * multi-step authorization). Adapters return AuthorizationSession domain
+ * objects and never expired sessions from lookups.
+ */
+class AuthorizationSessionRepositoryInterface {
+    /**
+     * @param {import('../domain/authorization-session').AuthorizationSession} session
+     * @returns {Promise<import('../domain/authorization-session').AuthorizationSession>}
+     */
+    async create(session) {
+        throw new Error('Method create must be implemented by subclass');
+    }
+
+    /**
+     * @param {string} sessionId
+     * @returns {Promise<import('../domain/authorization-session').AuthorizationSession|null>}
+     *   null when missing or expired.
+     */
+    async findBySessionId(sessionId) {
+        throw new Error('Method findBySessionId must be implemented by subclass');
+    }
+
+    /**
+     * Saves currentStep, stepData and completed.
+     * @param {import('../domain/authorization-session').AuthorizationSession} session
+     */
+    async update(session) {
+        throw new Error('Method update must be implemented by subclass');
+    }
+
+    /** @param {string} sessionId */
+    async deleteBySessionId(sessionId) {
+        throw new Error('Method deleteBySessionId must be implemented by subclass');
+    }
+
+    /**
+     * Removes sessions that expired before `now`.
+     * @param {Date} [now]
+     * @returns {Promise<number>} how many were removed
+     */
+    async deleteExpired(now) {
+        throw new Error('Method deleteExpired must be implemented by subclass');
+    }
+}
+
+module.exports = { AuthorizationSessionRepositoryInterface };

package/modules/repositories/authorization-session-repository-prisma.js

@@ -0,0 +1,87 @@
+const { prisma } = require('../../database/prisma');
+const { AuthorizationSession } = require('../domain/authorization-session');
+const {
+    AuthorizationSessionRepositoryInterface,
+} = require('./authorization-session-repository-interface');
+
+/**
+ * AuthorizationSession persistence through the Prisma client, for PostgreSQL
+ * and MongoDB (both schemas declare the same model; the session id, not the
+ * row id, is the key, so no id conversion is needed). `stepData` is
+ * encrypted by the Prisma encryption extension (encryption-schema-registry).
+ */
+class AuthorizationSessionRepositoryPrisma extends AuthorizationSessionRepositoryInterface {
+    constructor(prismaClient = prisma) {
+        super();
+        this.prisma = prismaClient;
+    }
+
+    async create(session) {
+        const record = await this.prisma.authorizationSession.create({
+            data: {
+                sessionId: session.sessionId,
+                userId: session.userId,
+                entityType: session.entityType,
+                credentialId: session.credentialId,
+                currentStep: session.currentStep,
+                maxSteps: session.maxSteps,
+                stepData: session.stepData,
+                expiresAt: session.expiresAt,
+                completed: session.completed,
+            },
+        });
+        return toDomain(record);
+    }
+
+    async findBySessionId(sessionId) {
+        if (typeof sessionId !== 'string' || !sessionId) return null;
+        const record = await this.prisma.authorizationSession.findFirst({
+            where: { sessionId, expiresAt: { gt: new Date() } },
+        });
+        return record ? toDomain(record) : null;
+    }
+
+    async update(session) {
+        const record = await this.prisma.authorizationSession.update({
+            where: { sessionId: session.sessionId },
+            data: {
+                currentStep: session.currentStep,
+                stepData: session.stepData,
+                completed: session.completed,
+            },
+        });
+        return toDomain(record);
+    }
+
+    async deleteBySessionId(sessionId) {
+        const result = await this.prisma.authorizationSession.deleteMany({
+            where: { sessionId },
+        });
+        return result.count;
+    }
+
+    async deleteExpired(now = new Date()) {
+        const result = await this.prisma.authorizationSession.deleteMany({
+            where: { expiresAt: { lte: now } },
+        });
+        return result.count;
+    }
+}
+
+function toDomain(record) {
+    return new AuthorizationSession({
+        sessionId: record.sessionId,
+        userId: record.userId,
+        entityType: record.entityType,
+        credentialId: record.credentialId ?? null,
+        currentStep: record.currentStep,
+        maxSteps: record.maxSteps,
+        stepData: record.stepData || {},
+        expiresAt: record.expiresAt,
+        completed: record.completed,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    });
+}
+
+module.exports = { AuthorizationSessionRepositoryPrisma, toDomain };

package/modules/repositories/entity-not-found.js

@@ -0,0 +1,18 @@
+/**
+ * The error `findEntityById` throws for an id with no row, and the one
+ * predicate that recognises it (as integration-not-found.js does for
+ * integrations). The adapters build the error here and use cases match it
+ * here, so a missing entity can be told from any other failure without
+ * widening a regex.
+ *
+ * Why it matters: a use case that answers 404 for another tenant's entity must
+ * answer the same 404 for an id that does not exist. Otherwise the status code
+ * says which ids exist (ADR-052 §3, ADR-056 §3.6).
+ */
+const MESSAGE = /^Entity .+ not found$/;
+
+const entityNotFoundError = (id) => new Error(`Entity ${id} not found`);
+
+const isEntityNotFound = (error) => MESSAGE.test(error?.message || '');
+
+module.exports = { entityNotFoundError, isEntityNotFound };