@friggframework/core 2.0.0--canary.680.6bacd26.0 → 2.0.0--canary.663.8de669c.0

package/modules/entity-type-registry.js

@@ -1,311 +0,0 @@
-/**
- * App-level entity type registry (ADR-059).
- *
- * Pure: reads an app definition, does no I/O. It answers "which entity types
- * (API modules) can this app connect?" from two sources:
- *
- *   1. `appDefinition.entities`, an object keyed by entity type name whose
- *      values are `{ definition, scope?, proxy?, display? }`.
- *   2. Inference: every module bound by `appDefinition.integrations[*]
- *      .Definition.modules` (skipped when `entities.$infer === false`).
- *
- * `loadAppDefinition()` builds the registry once, at load, and returns it as
- * `entityTypeRegistry` / `moduleDefinitions`; every consumer that holds a
- * loaded app definition reads those instead of rebuilding.
- */
-
-const { BaseError } = require('../errors/base-error');
-const { getLogger } = require('../logs');
-
-const log = getLogger('frigg.modules.entity_registry');
-
-const INFER_KEY = '$infer';
-const UNNAMED = '(unnamed definition)';
-
-/**
- * Raised for an invalid `entities` registry. `code` is always
- * `ENTITY_REGISTRY_INVALID`, so callers can tell it from other load errors.
- */
-class EntityRegistryError extends BaseError {
-    constructor(message, options) {
-        super(message, options);
-        this.code = 'ENTITY_REGISTRY_INVALID';
-    }
-}
-
-const isPlainObject = (value) =>
-    value !== null && typeof value === 'object' && !Array.isArray(value);
-
-const appSource = () => ({ kind: 'app' });
-const integrationSource = (integrationClass) => ({
-    kind: 'integration',
-    name: integrationClass?.Definition?.name || 'unnamed',
-});
-const describeSource = (source) =>
-    source.kind === 'app' ? 'app' : `integration:${source.name}`;
-
-const safeGetName = (definition) => {
-    if (typeof definition.getName !== 'function') return undefined;
-    try {
-        const name = definition.getName();
-        return typeof name === 'string' && name ? name : undefined;
-    } catch {
-        return undefined;
-    }
-};
-
-const moduleNameOf = (definition) =>
-    typeof definition?.moduleName === 'string' && definition.moduleName
-        ? definition.moduleName
-        : undefined;
-
-/** The name an entity type is known by: moduleName, else getName(). */
-function entityTypeNameOf(definition) {
-    if (!definition) return undefined;
-    return moduleNameOf(definition) ?? safeGetName(definition);
-}
-
-/** Same object, or the same package name and version when both can be read. */
-function isSameDefinition(a, b) {
-    if (a === b) return true;
-    const packageId = (definition) => {
-        const { packageName, version } = definition || {};
-        return typeof packageName === 'string' &&
-            packageName &&
-            typeof version === 'string' &&
-            version
-            ? `${packageName}@${version}`
-            : null;
-    };
-    const left = packageId(a);
-    return left !== null && left === packageId(b);
-}
-
-function conflictError(name, existing, source) {
-    return new EntityRegistryError(
-        `Entity type '${name}' is supplied by two different definitions: ` +
-            `${existing.sources
-                .map(describeSource)
-                .join(', ')} and ${describeSource(source)}. ` +
-            'They must be the same definition object (or the same package name and version).'
-    );
-}
-
-/**
- * A registry key must equal the definition's moduleName and, when it has one,
- * its getName(). Case matters. This leaves one name per entity type.
- */
-function assertKeyMatchesDefinition(key, definition) {
-    const moduleName = moduleNameOf(definition);
-    const getName = safeGetName(definition);
-    const matches =
-        (moduleName !== undefined || getName !== undefined) &&
-        (moduleName === undefined || key === moduleName) &&
-        (getName === undefined || key === getName);
-    if (!matches) {
-        throw new EntityRegistryError(
-            `appDefinition.entities key '${key}' does not match its definition's name ` +
-                `(moduleName '${moduleName ?? '(none)'}', getName() '${
-                    getName ?? '(none)'
-                }'). ` +
-                'The key must equal both, so each entity type has one name.'
-        );
-    }
-}
-
-const settingsOf = (entry) => {
-    const settings = {};
-    for (const field of ['scope', 'proxy', 'display']) {
-        if (entry[field] !== undefined) settings[field] = entry[field];
-    }
-    return settings;
-};
-
-/**
- * `entities` absent keeps today's behaviour: inference on, and a name clash
- * between integrations is not fatal. `entities` present (even `{}`) opts in to
- * the strict rules.
- */
-function readEntities(appDefinition) {
-    const entities = appDefinition?.entities;
-    if (entities === undefined || entities === null) {
-        return { strict: false, infer: true, entries: [] };
-    }
-    if (!isPlainObject(entities)) {
-        throw new EntityRegistryError(
-            'appDefinition.entities must be an object keyed by entity type name'
-        );
-    }
-    const { [INFER_KEY]: inferFlag, ...rest } = entities;
-    if (inferFlag !== undefined && typeof inferFlag !== 'boolean') {
-        throw new EntityRegistryError(
-            `appDefinition.entities.${INFER_KEY} must be a boolean`
-        );
-    }
-    return {
-        strict: true,
-        infer: inferFlag !== false,
-        entries: Object.entries(rest),
-    };
-}
-
-function registerAppEntries(registry, entries) {
-    for (const [key, entry] of entries) {
-        if (
-            !isPlainObject(entry) ||
-            !entry.definition ||
-            typeof entry.definition !== 'object'
-        ) {
-            throw new EntityRegistryError(
-                `appDefinition.entities.${key} must be an object with a 'definition'`
-            );
-        }
-        assertKeyMatchesDefinition(key, entry.definition);
-        registry.set(key, {
-            definition: entry.definition,
-            sources: [appSource()],
-            settings: settingsOf(entry),
-        });
-    }
-}
-
-function* boundDefinitions(integrationClass) {
-    const modules = integrationClass?.Definition?.modules;
-    if (!isPlainObject(modules)) return;
-    for (const bound of Object.values(modules)) {
-        if (bound?.definition) yield bound.definition;
-    }
-}
-
-const addSource = (entry, source) => {
-    const known = entry.sources.some(
-        (s) => s.kind === source.kind && s.name === source.name
-    );
-    if (!known) entry.sources.push(source);
-};
-
-/**
- * Folds one integration-bound definition into the registry. Returns the name
- * it could not register (only possible when inference is off), else undefined.
- */
-function mergeBoundDefinition(registry, definition, source, { strict, infer }) {
-    const name = entityTypeNameOf(definition);
-
-    if (!name) {
-        // No moduleName / getName(): it cannot be keyed by name. Offering it
-        // as before, de-duplicated by identity, keeps apps that never named
-        // one working. It cannot be registered, so `$infer: false` rejects it.
-        if (!infer) return UNNAMED;
-        const known = [...registry.values()].find(
-            (entry) => entry.definition === definition
-        );
-        if (known) addSource(known, source);
-        else {
-            registry.set(`${UNNAMED} #${registry.size}`, {
-                definition,
-                sources: [source],
-                settings: {},
-            });
-        }
-        return undefined;
-    }
-
-    const existing = registry.get(name);
-    if (existing) {
-        if (isSameDefinition(existing.definition, definition)) {
-            addSource(existing, source);
-        } else if (strict) {
-            throw conflictError(name, existing, source);
-        } else {
-            // Pre-ADR-059 apps keep working: the first definition wins, as
-            // ModuleFactory would have picked it.
-            log.warn('Two different definitions share one entity type name', {
-                eventName: `${log.name}.duplicate_definition`,
-                entityType: name,
-                kept: existing.sources.map(describeSource).join(', '),
-                ignored: describeSource(source),
-            });
-        }
-        return undefined;
-    }
-
-    if (!infer) return name;
-    registry.set(name, { definition, sources: [source], settings: {} });
-    return undefined;
-}
-
-function assertAllRegistered(unregistered) {
-    if (unregistered.size === 0) return;
-    const detail = [...unregistered]
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(
-            ([name, sources]) => `${name} (bound by ${[...sources].join(', ')})`
-        );
-    throw new EntityRegistryError(
-        `appDefinition.entities.${INFER_KEY} is false, so every module an integration binds must be registered. Missing: ${detail.join(
-            '; '
-        )}`
-    );
-}
-
-const freezeEntries = (registry) => {
-    for (const entry of registry.values()) {
-        entry.sources.forEach(Object.freeze);
-        Object.freeze(entry.sources);
-        Object.freeze(entry.settings);
-        Object.freeze(entry);
-    }
-};
-
-/**
- * Builds the registry for an app definition.
- *
- * @param {object} [appDefinition] - `{ entities?, integrations? }`
- * @returns {Map<string, {definition: object, sources: Array<{kind: 'app'} | {kind: 'integration', name: string}>, settings: {scope?: string|object, proxy?: object, display?: object}}>}
- * @throws {EntityRegistryError} on a key/name mismatch, two different
- *   definitions under one name (when `entities` is present), or, with
- *   `$infer: false`, a bound module that is not registered.
- */
-function getEntityTypeRegistry(appDefinition = {}) {
-    const mode = readEntities(appDefinition);
-    const registry = new Map();
-    registerAppEntries(registry, mode.entries);
-
-    const unregistered = new Map();
-    for (const integrationClass of appDefinition?.integrations || []) {
-        const source = integrationSource(integrationClass);
-        for (const definition of boundDefinitions(integrationClass)) {
-            const missing = mergeBoundDefinition(
-                registry,
-                definition,
-                source,
-                mode
-            );
-            if (missing !== undefined) {
-                if (!unregistered.has(missing))
-                    unregistered.set(missing, new Set());
-                unregistered.get(missing).add(describeSource(source));
-            }
-        }
-    }
-    assertAllRegistered(unregistered);
-
-    freezeEntries(registry);
-    return registry;
-}
-
-/** The definitions of a registry, in registry order. */
-const getEntityTypeDefinitions = (registry) =>
-    [...registry.values()].map((entry) => entry.definition);
-
-/** Names of the integrations that bind an entity type; empty for registry-only. */
-const usedByOf = (entry) =>
-    entry.sources.filter((s) => s.kind === 'integration').map((s) => s.name);
-
-module.exports = {
-    getEntityTypeRegistry,
-    getEntityTypeDefinitions,
-    usedByOf,
-    entityTypeNameOf,
-    EntityRegistryError,
-};

package/modules/proxy/proxy-errors.js

@@ -1,20 +0,0 @@
-/**
- * A proxied call was refused or failed in a way the Management API maps to a
- * documented status (ADR-052 §10). `code` is the public error code; nothing
- * here carries the upstream URL, headers or credential material.
- */
-class ProxyRequestError extends Error {
-    /**
-     * @param {string} code - e.g. INVALID_PROXY_REQUEST, PROXY_NOT_ALLOWED, TIMEOUT
-     * @param {string} message - safe to show the caller
-     * @param {Object} [details] - safe structured details
-     */
-    constructor(code, message, details) {
-        super(message);
-        this.name = 'ProxyRequestError';
-        this.code = code;
-        this.details = details;
-    }
-}
-
-module.exports = { ProxyRequestError };

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 };