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

package/management-api/v2/test-support/fake-dependencies.js

@@ -0,0 +1,103 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * In-memory doubles for every Management API v2 dependency. Each use case is
+ * a jest.fn() so a test can assert on calls or override one behaviour.
+ */
+function fakeV2Dependencies(overrides = {}) {
+    const user = { getId: () => 'user-1' };
+    const notFound = (code) => async () => {
+        throw Boom.notFound('not found', { code });
+    };
+    const fn = (impl) => ({ execute: jest.fn(impl) });
+
+    return {
+        user,
+        config: { v1: true, proxy: { enable: false } },
+        authenticateUser: {
+            execute: jest.fn(async (req) => {
+                if (!req.headers.authorization) {
+                    throw Boom.unauthorized('No valid authentication provided');
+                }
+                return user;
+            }),
+        },
+        getIntegrationsForUser: fn(async () => [
+            { id: 'i1', entities: ['e1'], status: 'ENABLED', config: { type: 'sync' }, userActions: {} },
+        ]),
+        getPossibleIntegrations: fn(async () => [{ type: 'sync', display: {} }]),
+        createIntegrationForUser: fn(async () => ({
+            id: 'i2', entities: ['e1'], status: 'ENABLED', config: { type: 'sync' },
+        })),
+        getIntegrationInstanceForUser: fn(async (id) => {
+            if (id !== 'i1') return notFound('INTEGRATION_NOT_FOUND')();
+            return { id: 'i1', entities: ['e1'], status: 'ENABLED', config: { type: 'sync' } };
+        }),
+        updateIntegrationForUser: fn(async (id, _user, config) => ({
+            id, entities: ['e1'], status: 'ENABLED', config,
+        })),
+        removeIntegrationForUser: fn(async () => undefined),
+        sendIntegrationEventForUser: fn(async (_id, _user, event, payload) => ({ event, payload })),
+        runIntegrationActionForUser: fn(async (_id, _user, actionId, payload) => ({ ran: actionId, payload })),
+        testIntegrationAuthForUser: fn(async () => ({ ok: true, errors: [] })),
+
+        listEntitiesForUser: fn(async () => [
+            { id: 'e1', userId: 'user-1', moduleName: 'acme', name: 'Acme', externalId: 'x1', credential: { id: 'c1', authIsValid: true, access_token: 'secret' } },
+        ]),
+        getEntityForUser: fn(async (id) => {
+            if (id !== 'e1') return notFound('ENTITY_NOT_FOUND')();
+            return { id: 'e1', userId: 'user-1', moduleName: 'acme', name: 'Acme', externalId: 'x1', credential: { id: 'c1', authIsValid: true, access_token: 'secret' } };
+        }),
+        deleteEntityForUser: fn(async () => undefined),
+        testEntityAuthForUser: fn(async () => true),
+        getEntityOptionsForUser: fn(async () => ({ jsonSchema: {} })),
+        refreshEntityOptionsForUser: fn(async (_id, _user, body) => ({ refreshed: body })),
+        listEntityTypes: fn(async () => [{ type: 'acme', name: 'Acme' }]),
+        getEntityType: fn(async (type) => {
+            if (type !== 'acme') return notFound('ENTITY_TYPE_NOT_FOUND')();
+            return { type: 'acme', name: 'Acme' };
+        }),
+        getAuthorizationRequirements: fn(async ({ step }) => ({
+            type: 'oauth2', data: { url: 'https://provider.example/authorize' }, step, totalSteps: 1, isMultiStep: false,
+        })),
+        listCredentialsForUser: fn(async () => [
+            { id: 'c1', userId: 'user-1', type: 'acme', entityIds: ['e1'], authIsValid: true, access_token: 'ya29.secret-token-value-1234' },
+        ]),
+        getCredentialForUser: fn(async (id) => {
+            if (id !== 'c1') return notFound('CREDENTIAL_NOT_FOUND')();
+            return { id: 'c1', userId: 'user-1', type: 'acme', entityIds: ['e1'], authIsValid: true, api_key: 'sk_live_abcdefghijkl9876' };
+        }),
+        deleteCredentialForUser: fn(async () => ({ id: 'c1', entityIds: ['e1'] })),
+        getAuthorizationStep: fn(async ({ entityType, step }) => {
+            if (entityType === 'nope') return notFound('ENTITY_TYPE_NOT_FOUND')();
+            return { type: 'email', data: {}, step, totalSteps: 2, isMultiStep: true, sessionId: 'sess-1' };
+        }),
+        submitAuthorizationStep: fn(async ({ step }) =>
+            step === 1
+                ? { status: 'pending', step: 2, totalSteps: 2, sessionId: 'sess-1', requirements: { type: 'otp' } }
+                : {
+                      status: 'complete',
+                      entity: { id: 'e1', userId: 'user-1', moduleName: 'acme', credential: { id: 'c1', authIsValid: true } },
+                      credential: { id: 'c1', userId: 'user-1', type: 'acme', entityIds: ['e1'], authIsValid: true, access_token: 'ya29.brand-new-token-0001' },
+                  }
+        ),
+        getCredentialReauthorization: fn(async (id, _user, { step }) => ({ type: 'oauth2', data: {}, step, totalSteps: 1 })),
+        reauthorizeCredentialForUser: fn(async () => ({
+            status: 'complete',
+            entity: { id: 'e1', userId: 'user-1', moduleName: 'acme' },
+            credential: { id: 'c2', userId: 'user-1', type: 'acme', entityIds: ['e1'], authIsValid: true },
+            previousCredentialId: 'c1',
+        })),
+        executeEntityProxyRequest: fn(async (entityId, _user, request) => {
+            if (request?.path === '/limited') {
+                throw Boom.tooManyRequests('The upstream API is rate limiting this account', {
+                    code: 'RATE_LIMITED', proxy: true, expose: true, retryAfter: '30', details: { upstreamStatus: 429 },
+                });
+            }
+            return { status: 201, body: { success: true, status: 201, headers: {}, data: { id: 'new' } } };
+        }),
+        ...overrides,
+    };
+}
+
+module.exports = { fakeV2Dependencies };

package/modules/domain/authorization-session.js

@@ -0,0 +1,144 @@
+const crypto = require('node:crypto');
+
+const DEFAULT_TTL_MINUTES = 15;
+
+function sessionTtlMs() {
+    const minutes = parseInt(process.env.AUTH_SESSION_EXPIRY_MINUTES || '', 10);
+    return (Number.isInteger(minutes) && minutes > 0 ? minutes : DEFAULT_TTL_MINUTES) * 60 * 1000;
+}
+
+/**
+ * State of one multi-step authorization (Management API v2
+ * `/api/v2/authorize` and `/api/v2/credentials/:id/reauthorize`).
+ *
+ * `stepData` holds what earlier steps collected (for example the email an OTP
+ * was sent to) and is encrypted at rest (encryption-schema-registry). A
+ * session is bound to the user who started it, the entity type, and, for a
+ * re-authorization, the credential being renewed.
+ */
+class AuthorizationSession {
+    /**
+     * @param {Object} params
+     * @param {string} params.sessionId - unguessable id (UUID v4)
+     * @param {string} params.userId
+     * @param {string} params.entityType - module name
+     * @param {string|null} [params.credentialId] - set for re-authorization
+     * @param {number} [params.currentStep=1] - the step the caller submits next
+     * @param {number} params.maxSteps
+     * @param {Object} [params.stepData={}]
+     * @param {Date} params.expiresAt
+     * @param {boolean} [params.completed=false]
+     * @param {Date} [params.createdAt]
+     * @param {Date} [params.updatedAt]
+     */
+    constructor({
+        sessionId,
+        userId,
+        entityType,
+        credentialId = null,
+        currentStep = 1,
+        maxSteps,
+        stepData = {},
+        expiresAt,
+        completed = false,
+        createdAt = new Date(),
+        updatedAt = new Date(),
+    }) {
+        this.sessionId = sessionId;
+        this.userId = userId === undefined || userId === null ? userId : String(userId);
+        this.entityType = entityType;
+        this.credentialId =
+            credentialId === undefined || credentialId === null ? null : String(credentialId);
+        this.currentStep = currentStep;
+        this.maxSteps = maxSteps;
+        this.stepData = stepData && typeof stepData === 'object' ? stepData : {};
+        this.expiresAt = expiresAt instanceof Date ? expiresAt : new Date(expiresAt);
+        this.completed = completed;
+        this.createdAt = createdAt;
+        this.updatedAt = updatedAt;
+        this.validate();
+    }
+
+    /**
+     * A new session for step 1, expiring after AUTH_SESSION_EXPIRY_MINUTES
+     * (default 15).
+     */
+    static start({ userId, entityType, maxSteps, credentialId = null, now = new Date() }) {
+        return new AuthorizationSession({
+            sessionId: crypto.randomUUID(),
+            userId,
+            entityType,
+            credentialId,
+            currentStep: 1,
+            maxSteps,
+            stepData: {},
+            expiresAt: new Date(now.getTime() + sessionTtlMs()),
+            completed: false,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+
+    validate() {
+        if (!this.sessionId) throw new Error('sessionId is required');
+        if (!this.userId) throw new Error('userId is required');
+        if (!this.entityType) throw new Error('entityType is required');
+        if (!Number.isInteger(this.maxSteps) || this.maxSteps < 1) {
+            throw new Error('maxSteps must be a positive integer');
+        }
+        if (
+            !Number.isInteger(this.currentStep) ||
+            this.currentStep < 1 ||
+            this.currentStep > this.maxSteps
+        ) {
+            throw new Error(`currentStep must be between 1 and ${this.maxSteps}`);
+        }
+        if (Number.isNaN(this.expiresAt.getTime())) {
+            throw new Error('expiresAt must be a valid date');
+        }
+    }
+
+    isExpired(now = new Date()) {
+        return this.expiresAt.getTime() <= now.getTime();
+    }
+
+    /** True when this session may be used by `userId` for `entityType`/`credentialId`. */
+    belongsTo({ userId, entityType, credentialId = null }) {
+        return (
+            this.userId === String(userId) &&
+            this.entityType === entityType &&
+            this.credentialId === (credentialId === null || credentialId === undefined ? null : String(credentialId))
+        );
+    }
+
+    /**
+     * Records a finished step and moves to `nextStep`, merging what the step
+     * collected into stepData.
+     */
+    advanceTo(nextStep, collected = {}) {
+        if (this.completed) throw new Error('Cannot advance a completed session');
+        if (nextStep !== this.currentStep + 1 || nextStep > this.maxSteps) {
+            throw new Error(
+                `Cannot move from step ${this.currentStep} to step ${nextStep} of ${this.maxSteps}`
+            );
+        }
+        this.currentStep = nextStep;
+        this.stepData = { ...this.stepData, ...(collected || {}) };
+        this.updatedAt = new Date();
+    }
+
+    /** Starts the flow over at step 1, forgetting collected data. */
+    restart() {
+        this.currentStep = 1;
+        this.stepData = {};
+        this.completed = false;
+        this.updatedAt = new Date();
+    }
+
+    markComplete() {
+        this.completed = true;
+        this.updatedAt = new Date();
+    }
+}
+
+module.exports = { AuthorizationSession, DEFAULT_TTL_MINUTES };

package/modules/entity-scope.js

@@ -0,0 +1,15 @@
+/**
+ * Entity scopes and ownership (ADR-056 §3), re-exported from the four files it
+ * is split into:
+ *
+ *   scope-resolution  constants, scope resolution, ownership on create
+ *   scope-config      reading and validating app-definition settings
+ *   scope-visibility  who may see which stored row
+ *   scope-policy      the object a use case asks
+ */
+module.exports = {
+    ...require('./scope-resolution'),
+    ...require('./scope-config'),
+    ...require('./scope-visibility'),
+    ...require('./scope-policy'),
+};

package/modules/entity-type-registry.js

@@ -0,0 +1,311 @@
+/**
+ * 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/index.js

@@ -4,6 +4,15 @@ const { OAuth2Requester } = require('./requester/oauth-2');
 const { Requester } = require('./requester/requester');
 const { ModuleConstants } = require('./ModuleConstants');
 const { ModuleFactory } = require('./module-factory');
+const {
+    getEntityTypeRegistry,
+    EntityRegistryError,
+} = require('./entity-type-registry');
+const {
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
+} = require('./entity-scope');
 
 module.exports = {
     ApiKeyRequester,
@@ -12,4 +21,9 @@ module.exports = {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
 };

package/modules/module-factory.js

@@ -45,6 +45,18 @@ class ModuleFactory {
             );
         }
 
+        // definition.env may be an async function (e.g. the db-credentials
+        // extension's bootstrap loads OAuth app credentials from the
+        // database); resolve it first. A static env keeps the plain
+        // constructor, exactly as before.
+        if (typeof moduleDefinition.env === 'function') {
+            return await Module.create({
+                userId,
+                entity,
+                definition: moduleDefinition,
+            });
+        }
+
         return new Module({
             userId,
             entity,