@friggframework/core 2.0.0--canary.690.d043f23.0 → 2.0.0--canary.691.2fd013b.0

package/modules/domain/authorization-session.js

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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -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-bases.js

@@ -1,169 +0,0 @@
-const { ProxyConfigError } = require('./proxy-errors');
-
-/**
- * Named base URLs for the entity proxy (ADR-052, amendment 2026-10-18).
- *
- * A module declares where its API lives. One host is `proxy.baseUrl`, which
- * means `{ default: baseUrl }`. A module whose API spans several hosts (Google:
- * Drive, Docs, Sheets, Analytics Data, Ads) declares `proxy.baseUrls`, a map of
- * name to URL. A caller picks a base by NAME in the proxy request's `base`
- * field; it never supplies a URL or a host, so the host still comes only from
- * the module.
- */
-
-const DEFAULT_BASE = 'default';
-const BASE_NAME = /^[a-z][a-z0-9-]*$/;
-
-const isPlainObject = (value) =>
-    value !== null && typeof value === 'object' && !Array.isArray(value);
-
-const describeRule = (rule) =>
-    `${rule && typeof rule.method === 'string' ? rule.method : '?'} ${
-        rule && typeof rule.path === 'string' ? rule.path : '?'
-    }`;
-
-function isValidBaseName(name) {
-    return typeof name === 'string' && name.length <= 64 && BASE_NAME.test(name);
-}
-
-function assertBaseUrl(moduleName, name, value) {
-    const where = `Module ${moduleName} proxy.baseUrls.${name}`;
-    if (typeof value !== 'string') {
-        throw new ProxyConfigError(`${where} must be an absolute https URL string (functions are not accepted)`);
-    }
-    let url;
-    try {
-        url = new URL(value);
-    } catch {
-        throw new ProxyConfigError(`${where} is not a valid absolute URL`);
-    }
-    if (url.protocol !== 'https:') {
-        throw new ProxyConfigError(`${where} must use https`);
-    }
-    if (url.username || url.password || url.search || url.hash) {
-        throw new ProxyConfigError(
-            `${where} must not carry credentials, a query or a fragment`
-        );
-    }
-}
-
-/**
- * The bases a module declares, validated.
- *
- * @param {object} definition - a module definition
- * @returns {{ names: string[], values: Map<string, string|Function|undefined>, declared: boolean }}
- *   `declared` is false when the module names no base of its own; it then has
- *   the single base `default`, resolved from the requester at call time.
- * @throws {ProxyConfigError}
- */
-function resolveModuleBases(definition) {
-    const moduleName = definition?.moduleName ?? '(unnamed)';
-    const proxy = definition?.proxy;
-    const hasBaseUrl = proxy?.baseUrl !== undefined;
-    const hasBaseUrls = proxy?.baseUrls !== undefined;
-
-    if (hasBaseUrl && hasBaseUrls) {
-        throw new ProxyConfigError(
-            `Module ${moduleName} declares both proxy.baseUrl and proxy.baseUrls; use one ` +
-                '(baseUrl means { default: baseUrl })'
-        );
-    }
-    if (hasBaseUrls) {
-        if (!isPlainObject(proxy.baseUrls) || Object.keys(proxy.baseUrls).length === 0) {
-            throw new ProxyConfigError(
-                `Module ${moduleName} proxy.baseUrls must be a non-empty object of name to URL`
-            );
-        }
-        const values = new Map();
-        for (const [name, value] of Object.entries(proxy.baseUrls)) {
-            if (!isValidBaseName(name)) {
-                throw new ProxyConfigError(
-                    `Module ${moduleName} proxy.baseUrls has the invalid name ${JSON.stringify(
-                        name
-                    )}; names match ${BASE_NAME}`
-                );
-            }
-            assertBaseUrl(moduleName, name, value);
-            values.set(name, value);
-        }
-        return { names: [...values.keys()], values, declared: true };
-    }
-    return {
-        names: [DEFAULT_BASE],
-        values: new Map([[DEFAULT_BASE, proxy?.baseUrl]]),
-        declared: hasBaseUrl,
-    };
-}
-
-/** The base a rule applies to; a rule without `base` applies to `default`. */
-const ruleBase = (rule) => (rule && rule.base !== undefined ? rule.base : DEFAULT_BASE);
-
-/**
- * Load-time check of every allow rule that names a base: the app's
- * `managementApi.proxy.modules.<module>.allow` and each module's own
- * `proxy.allow`. A rule for a base the module does not declare could never
- * match, which reads as "allowed" and is not, so it stops the app.
- *
- * @param {Array<object>} moduleDefinitions
- * @param {{ modules?: Object }} [proxyConfig] - resolved managementApi.proxy
- * @throws {ProxyConfigError}
- */
-function assertProxyConfig(moduleDefinitions, proxyConfig = {}) {
-    const namesByModule = new Map();
-    for (const definition of moduleDefinitions || []) {
-        if (!definition?.moduleName) continue;
-        const { names } = resolveModuleBases(definition);
-        namesByModule.set(definition.moduleName, names);
-        const own = definition.proxy?.allow;
-        if (Array.isArray(own)) {
-            assertRulesUseDeclaredBases(
-                definition.moduleName,
-                names,
-                own,
-                `Module ${definition.moduleName} proxy.allow`
-            );
-        }
-    }
-    for (const [moduleName, override] of Object.entries(proxyConfig.modules || {})) {
-        const names = namesByModule.get(moduleName);
-        // An override for a module that is not registered is not new: it never applied.
-        if (!names || !Array.isArray(override?.allow)) continue;
-        assertRulesUseDeclaredBases(
-            moduleName,
-            names,
-            override.allow,
-            `managementApi.proxy.modules.${moduleName}.allow`
-        );
-    }
-}
-
-function assertRulesUseDeclaredBases(moduleName, names, rules, where) {
-    for (const rule of rules) {
-        if (!isPlainObject(rule) || rule.base === undefined) continue;
-        if (!isValidBaseName(rule.base) || !names.includes(rule.base)) {
-            throw new ProxyConfigError(
-                `${where}: the rule ${describeRule(rule)} names the base ${JSON.stringify(
-                    rule.base
-                )}, which module ${moduleName} does not declare (declared: ${names.join(', ')})`
-            );
-        }
-    }
-    // A rule with no base means `default`; the module must have one.
-    if (!names.includes(DEFAULT_BASE)) {
-        const bare = rules.find((rule) => isPlainObject(rule) && rule.base === undefined);
-        if (bare) {
-            throw new ProxyConfigError(
-                `${where}: the rule ${describeRule(bare)} names no base, so it applies to ` +
-                    `"default", which module ${moduleName} does not declare (declared: ${names.join(', ')})`
-            );
-        }
-    }
-}
-
-module.exports = {
-    DEFAULT_BASE,
-    isValidBaseName,
-    resolveModuleBases,
-    ruleBase,
-    assertProxyConfig,
-};

package/modules/proxy/proxy-errors.js

@@ -1,31 +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;
-    }
-}
-
-/**
- * A module definition or the app's proxy settings are wrong. Thrown at load,
- * so the app stops starting instead of failing on the first proxied call.
- */
-class ProxyConfigError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ProxyConfigError';
-    }
-}
-
-module.exports = { ProxyRequestError, ProxyConfigError };