@friggframework/core 2.0.0--canary.686.df38e8e.0 → 2.0.0--canary.710.9045bbc.0

package/modules/proxy/proxy-path.js

@@ -1,179 +0,0 @@
-const { ProxyRequestError } = require('./proxy-errors');
-
-/**
- * Path rules for the entity proxy (ADR-052 §4). The caller supplies a path
- * relative to the module's base URL and nothing else: the host, scheme and
- * port always come from the module.
- */
-
-const invalid = (reason) =>
-    new ProxyRequestError('INVALID_PROXY_REQUEST', `Invalid proxy path: ${reason}`, {
-        field: 'path',
-    });
-
-// Control characters (C0, DEL, C1), any whitespace, and invisible format
-// characters such as zero-width spaces and byte-order marks.
-const FORBIDDEN_CHARS = /[\x00-\x20\x7f-\x9f]|\s|\p{Cf}/u;
-
-/**
- * Validates and normalises a caller-supplied path.
- *
- * - must start with a single `/`; `//` (anywhere), `\`, `?`, `#`, control
- *   and whitespace characters are rejected;
- * - encoded separators (`%2f`, `%5c`) are rejected, then the path is
- *   percent-decoded exactly once; a `%` left after decoding (double
- *   encoding) is rejected, as is any decoded control or whitespace
- *   character other than a space (`%20`);
- * - `.` and `..` segments are rejected rather than resolved.
- *
- * @param {unknown} path
- * @returns {string} the decoded path, e.g. `/crm/v3/objects/contacts`
- * @throws {ProxyRequestError} INVALID_PROXY_REQUEST
- */
-function normalizeProxyPath(path) {
-    if (typeof path !== 'string' || path.length === 0) {
-        throw invalid('path must be a non-empty string');
-    }
-    if (path.length > 2048) throw invalid('path is too long');
-    if (!path.startsWith('/')) throw invalid('path must start with /');
-    if (path.startsWith('//') || path.includes('//')) {
-        throw invalid('empty path segments (//) are not allowed');
-    }
-    if (path.includes('\\')) throw invalid('backslashes are not allowed');
-    if (path.includes('?') || path.includes('#')) {
-        throw invalid('send the query string in `query`, not in the path');
-    }
-    if (FORBIDDEN_CHARS.test(path)) {
-        throw invalid('control and whitespace characters are not allowed');
-    }
-    if (/%(2f|5c)/i.test(path)) {
-        throw invalid('encoded path separators are not allowed');
-    }
-
-    let decoded;
-    try {
-        decoded = decodeURIComponent(path);
-    } catch {
-        throw invalid('malformed percent-encoding');
-    }
-    if (
-        decoded.includes('%') ||
-        decoded.includes('\\') ||
-        decoded.includes('?') ||
-        decoded.includes('#') ||
-        decoded.includes('//') ||
-        // An encoded space (%20) is a legitimate path character; every other
-        // control or whitespace character stays forbidden.
-        FORBIDDEN_CHARS.test(decoded.replaceAll(' ', ''))
-    ) {
-        throw invalid('encoded characters decode to something not allowed');
-    }
-
-    const segments = decoded.split('/').slice(1);
-    if (segments.some((segment) => segment === '.' || segment === '..')) {
-        throw invalid('dot segments (. and ..) are not allowed');
-    }
-    return decoded;
-}
-
-/**
- * Joins a module base URL and a normalised path, then proves the result
- * cannot leave the module's API: https only, same origin as the base URL,
- * and under the base URL's path.
- *
- * @param {string} baseUrl - from the module, never from the request
- * @param {string} normalizedPath - from normalizeProxyPath()
- * @returns {{ url: string, basePath: string, origin: string }} `url` is not
- *   percent-encoded; the Requester encodes it once.
- * @throws {ProxyRequestError} PROXY_NOT_CONFIGURED or INVALID_PROXY_REQUEST
- */
-function joinProxyUrl(baseUrl, normalizedPath) {
-    let base;
-    try {
-        base = new URL(baseUrl);
-    } catch {
-        throw new ProxyRequestError(
-            'PROXY_NOT_CONFIGURED',
-            'The module has no valid base URL to proxy to'
-        );
-    }
-    if (base.protocol !== 'https:') {
-        throw new ProxyRequestError(
-            'PROXY_NOT_CONFIGURED',
-            'The module base URL must use https to be proxied'
-        );
-    }
-    if (base.username || base.password || base.search || base.hash) {
-        throw new ProxyRequestError(
-            'PROXY_NOT_CONFIGURED',
-            'The module base URL must not carry credentials, a query or a fragment'
-        );
-    }
-
-    const basePath = base.pathname.replace(/\/+$/, '');
-    const url = `${base.origin}${basePath}${normalizedPath}`;
-
-    let joined;
-    try {
-        joined = new URL(url);
-    } catch {
-        throw invalid('the joined URL is not valid');
-    }
-    const joinedPath = decodeURIComponent(joined.pathname);
-    if (
-        joined.protocol !== 'https:' ||
-        joined.origin !== base.origin ||
-        joined.username ||
-        joined.password ||
-        !(joinedPath === basePath || joinedPath.startsWith(`${basePath}/`))
-    ) {
-        throw invalid('the path leaves the module API');
-    }
-    return { url, basePath, origin: base.origin };
-}
-
-/**
- * Finds the allow-list rule that permits `method` on `path`.
- *
- * Patterns use `:param` for exactly one segment and a trailing `/**` for a
- * subtree (the prefix itself included). `method: '*'` matches any method.
- *
- * @param {Array<{method: string, path: string}>} rules
- * @param {string} method - upper case
- * @param {string} path - normalised path
- * @returns {{method: string, path: string}|null}
- */
-function matchAllowRule(rules, method, path) {
-    const requestSegments = path.split('/').slice(1);
-    for (const rule of rules || []) {
-        if (!rule || typeof rule.path !== 'string' || typeof rule.method !== 'string') {
-            continue;
-        }
-        const ruleMethod = rule.method.toUpperCase();
-        if (ruleMethod !== '*' && ruleMethod !== method) continue;
-        if (patternMatches(rule.path, requestSegments)) return rule;
-    }
-    return null;
-}
-
-function patternMatches(pattern, requestSegments) {
-    if (!pattern.startsWith('/')) return false;
-    let patternSegments = pattern.split('/').slice(1);
-    let subtree = false;
-    if (patternSegments[patternSegments.length - 1] === '**') {
-        subtree = true;
-        patternSegments = patternSegments.slice(0, -1);
-    }
-    if (subtree) {
-        if (requestSegments.length < patternSegments.length) return false;
-    } else if (requestSegments.length !== patternSegments.length) {
-        return false;
-    }
-    return patternSegments.every((segment, index) => {
-        const actual = requestSegments[index];
-        if (segment.startsWith(':')) return actual !== undefined && actual !== '';
-        return segment === actual;
-    });
-}
-
-module.exports = { normalizeProxyPath, joinProxyUrl, matchAllowRule };

package/modules/proxy/proxy-policy.js

@@ -1,248 +0,0 @@
-const { ProxyRequestError } = require('./proxy-errors');
-
-/**
- * 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);
-
-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, 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' });
-    }
-
-    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}`,
-                });
-            }
-            // The requester sends one value per key; arrays go comma-separated.
-            query[key] = list ? value.join(',') : 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, query, headers, body, bodyIsJson, requestBytes };
-}
-
-const isWildcardRule = (rule) => rule?.method === '*' || rule?.path === '/**';
-
-const isValidRule = (rule) =>
-    isPlainObject(rule) &&
-    typeof rule.method === 'string' &&
-    typeof rule.path === 'string' &&
-    rule.path.startsWith('/');
-
-/**
- * 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

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

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

@@ -1,47 +0,0 @@
-/**
- * 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 };