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

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

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

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

package/modules/requester/proxy-request.js

@@ -1,244 +0,0 @@
-const { FetchError } = require('../../errors/fetch-error');
-const { ProxyRequestError } = require('../proxy/proxy-errors');
-const {
-    normalizeProxyPath,
-    joinProxyUrl,
-} = require('../proxy/proxy-path');
-
-const MAX_REDIRECTS = 3;
-
-/**
- * The generic, path-checked request behind the Management API entity proxy
- * (ADR-052 §8). It runs through the requester's own `_request`, so auth
- * headers, token refresh (single-flight), the per-attempt timeout, telemetry
- * and log redaction all apply. What it adds:
- *
- * - the URL is always `module base URL + normalised path`; the caller cannot
- *   name a host, scheme or port;
- * - no backoff retries (the caller decides; a 429 comes back with its
- *   Retry-After), and upstream errors are returned, not thrown;
- * - redirects are handled manually: same origin and under the base path only,
- *   at most three hops, each re-checked with `isAllowedRedirect`;
- * - one deadline for the whole call and a cap on the response body.
- *
- * @param {import('./requester').Requester} requester
- * @param {Object} params
- * @param {string} params.method - upper case
- * @param {string} params.path - caller path, validated here
- * @param {Object} [params.query]
- * @param {Object} [params.headers] - already filtered by the caller's policy
- * @param {string|Buffer} [params.body] - already serialised
- * @param {string} [params.baseUrl] - module-declared proxy base URL; falls
- *   back to the requester's `proxyBaseUrl`, `baseUrl` or `baseURL`
- * @param {number} params.timeoutMs - budget for the whole call
- * @param {number} params.maxResponseBytes
- * @param {(path: string, method: string) => boolean} [params.isAllowedRedirect]
- * @returns {Promise<{ status: number, headers: Object, body: Buffer, contentType: string, redirectBlocked: boolean }>}
- * @throws {ProxyRequestError} INVALID_PROXY_REQUEST, PROXY_NOT_CONFIGURED,
- *   INVALID_CREDENTIALS, TIMEOUT, NETWORK_ERROR, RESPONSE_TOO_LARGE
- */
-async function proxyRequest(requester, params) {
-    const {
-        method,
-        path,
-        query,
-        headers = {},
-        body,
-        baseUrl,
-        timeoutMs,
-        maxResponseBytes,
-        isAllowedRedirect,
-    } = params;
-
-    const normalizedPath = normalizeProxyPath(path);
-    const base =
-        baseUrl ??
-        requester.proxyBaseUrl ??
-        requester.baseUrl ??
-        requester.baseURL;
-    if (!base) {
-        throw new ProxyRequestError(
-            'PROXY_NOT_CONFIGURED',
-            'The module declares no base URL to proxy to'
-        );
-    }
-    const target = joinProxyUrl(base, normalizedPath);
-    const deadline = Date.now() + timeoutMs;
-
-    const run = async () => {
-        let url = target.url;
-        let currentMethod = method;
-        let currentBody = body;
-        let currentQuery = query;
-        for (let hop = 0; ; hop++) {
-            const remaining = deadline - Date.now();
-            if (remaining <= 0) throw timeoutError();
-
-            const response = await requester._request(url, {
-                method: currentMethod,
-                headers: { ...headers },
-                query: currentQuery,
-                body: currentBody,
-                returnFullRes: true,
-                returnErrorResponses: true,
-                noRetry: true,
-                redirect: 'manual',
-                size: maxResponseBytes,
-                timeoutMs: remaining,
-            });
-
-            const location = response.headers.get('location');
-            if (response.status >= 300 && response.status < 400 && location) {
-                const next = sameApiRedirect(location, url, target);
-                const nextMethod = redirectMethod(response.status, currentMethod);
-                if (
-                    next &&
-                    hop < MAX_REDIRECTS &&
-                    (!isAllowedRedirect || isAllowedRedirect(next.path, nextMethod))
-                ) {
-                    if (nextMethod !== currentMethod) currentBody = undefined;
-                    currentMethod = nextMethod;
-                    url = next.url;
-                    currentQuery = undefined;
-                    continue;
-                }
-                return readResponse(response, maxResponseBytes, {
-                    redirectBlocked: !next,
-                });
-            }
-            return readResponse(response, maxResponseBytes, {
-                redirectBlocked: false,
-            });
-        }
-    };
-
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(timeoutError()), timeoutMs);
-    });
-    const work = run();
-    // If the deadline wins, the request still settles later; nothing awaits it.
-    work.catch(() => {});
-    try {
-        return await Promise.race([work, timeout]);
-    } catch (error) {
-        throw toProxyError(error);
-    } finally {
-        clearTimeout(timer);
-    }
-}
-
-function timeoutError() {
-    return new ProxyRequestError('TIMEOUT', 'The upstream API did not answer in time');
-}
-
-/**
- * A redirect target the proxy may follow: same origin as the module base URL
- * and under its base path. Returns null for anything else.
- */
-function sameApiRedirect(location, currentUrl, target) {
-    let next;
-    try {
-        next = new URL(location, currentUrl);
-    } catch {
-        return null;
-    }
-    if (next.origin !== target.origin || next.protocol !== 'https:') return null;
-    let decodedPath;
-    try {
-        decodedPath = decodeURIComponent(next.pathname);
-    } catch {
-        return null;
-    }
-    if (
-        !(decodedPath === target.basePath || decodedPath.startsWith(`${target.basePath}/`))
-    ) {
-        return null;
-    }
-    const relativePath = decodedPath.slice(target.basePath.length) || '/';
-    let checkedPath;
-    try {
-        checkedPath = normalizeProxyPath(relativePath);
-    } catch {
-        return null;
-    }
-    // _rawRequest percent-encodes the URL once, so hand it the decoded form.
-    return {
-        url: `${target.origin}${target.basePath}${checkedPath}${next.search ? decodeURI(next.search) : ''}`,
-        path: checkedPath,
-    };
-}
-
-/** Method for the next hop, as fetch does it. */
-function redirectMethod(status, method) {
-    if (status === 303 && method !== 'HEAD') return 'GET';
-    if ((status === 301 || status === 302) && method === 'POST') return 'GET';
-    return method;
-}
-
-async function readResponse(response, maxResponseBytes, { redirectBlocked }) {
-    const declaredLength = Number(response.headers.get('content-length'));
-    if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
-        destroyBody(response);
-        throw tooLarge();
-    }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    if (buffer.length > maxResponseBytes) throw tooLarge();
-    const headers = {};
-    response.headers.forEach((value, name) => {
-        headers[name.toLowerCase()] = value;
-    });
-    return {
-        status: response.status,
-        headers,
-        body: buffer,
-        contentType: headers['content-type'] || '',
-        redirectBlocked,
-    };
-}
-
-function destroyBody(response) {
-    try {
-        response.body?.destroy?.();
-    } catch {
-        // nothing to clean up
-    }
-}
-
-function tooLarge() {
-    return new ProxyRequestError(
-        'RESPONSE_TOO_LARGE',
-        'The upstream response is larger than the proxy allows'
-    );
-}
-
-/** Maps requester and fetch failures to the proxy's error codes. */
-function toProxyError(error) {
-    if (error instanceof ProxyRequestError) return error;
-    const causeType = error?.cause?.type ?? error?.type;
-    if (causeType === 'max-size') return tooLarge();
-    if (error?.isTimeout) return timeoutError();
-    if (error instanceof FetchError || error?.name === 'FetchError') {
-        if (error.statusCode === 401) {
-            return new ProxyRequestError(
-                'INVALID_CREDENTIALS',
-                'The upstream API rejected the stored credentials; re-authorize the entity',
-                { upstreamStatus: 401 }
-            );
-        }
-        if (!error.statusCode) {
-            return new ProxyRequestError(
-                'NETWORK_ERROR',
-                'Could not reach the upstream API'
-            );
-        }
-        return new ProxyRequestError(
-            'UPSTREAM_ERROR',
-            'The upstream API returned an error',
-            { upstreamStatus: error.statusCode }
-        );
-    }
-    return error;
-}
-
-module.exports = { proxyRequest, MAX_REDIRECTS };

package/modules/scope-config.js

@@ -1,192 +0,0 @@
-/**
- * Reading and validating ownership settings in an app definition (ADR-056
- * §3.1, §3.3). Called once by loadAppDefinition, so a bad setting stops the app
- * at load, not on the first request. No I/O.
- */
-
-const {
-    SCOPES,
-    INDIVIDUAL_ACROSS_VALUES,
-    OWNER_RULES,
-    DEFAULT_ORG_ADMIN_ROLES,
-    configError,
-    isPlainObject,
-    parseScopeSetting,
-    resolveScope,
-} = require('./scope-resolution');
-const { entityTypeNameOf } = require('./entity-type-registry');
-
-/** The binding scope an integration declares for `modules[key]`, if any. */
-function bindingScopeSetting(Definition, key) {
-    const binding = Definition?.modules?.[key];
-    if (binding?.scope !== undefined) return binding.scope;
-    const entityEntry = Definition?.entities?.[key];
-    if (entityEntry?.scope !== undefined) return entityEntry.scope;
-    // Deprecated alias from the global-entities branch: `global: true`.
-    if (entityEntry?.global === true) return SCOPES.GLOBAL;
-    return undefined;
-}
-
-function readAppOwnership(appDefinition) {
-    const raw = appDefinition?.ownership;
-    if (raw === undefined || raw === null) {
-        return { scope: null, individualAcross: 'organization' };
-    }
-    if (!isPlainObject(raw)) {
-        throw configError('appDefinition.ownership', 'must be an object');
-    }
-    const unknown = Object.keys(raw).filter(
-        (key) => key !== 'scope' && key !== 'individualAcross'
-    );
-    if (unknown.length) {
-        throw configError(
-            'appDefinition.ownership',
-            `unknown setting(s): ${unknown.join(', ')}`
-        );
-    }
-    const individualAcross = raw.individualAcross ?? 'organization';
-    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
-        throw configError(
-            'appDefinition.ownership.individualAcross',
-            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
-        );
-    }
-    return {
-        scope: parseScopeSetting(raw.scope, 'appDefinition.ownership.scope'),
-        individualAcross,
-    };
-}
-
-function readIntegrationOwnership(integrationClass) {
-    const name = integrationClass?.Definition?.name || 'unnamed';
-    const raw = integrationClass?.Definition?.ownership;
-    if (raw === undefined || raw === null) return { scope: null, owner: 'derive' };
-    const where = `integration '${name}' ownership`;
-    if (!isPlainObject(raw)) throw configError(where, 'must be an object');
-    const unknown = Object.keys(raw).filter(
-        (key) => key !== 'scope' && key !== 'owner'
-    );
-    if (unknown.length) {
-        throw configError(where, `unknown setting(s): ${unknown.join(', ')}`);
-    }
-    const owner = raw.owner ?? 'derive';
-    if (!OWNER_RULES.includes(owner)) {
-        throw configError(where, `owner must be one of ${OWNER_RULES.join(', ')}`);
-    }
-    return { scope: parseScopeSetting(raw.scope, `${where}.scope`), owner };
-}
-
-/**
- * `user.orgAdminRoles`: the token roles that may manage organization-level
- * things. Default `['ADMIN']`. A shared-secret caller needs no role.
- */
-function readOrgAdminRoles(appDefinition) {
-    const raw = appDefinition?.user?.orgAdminRoles;
-    if (raw === undefined || raw === null) return [...DEFAULT_ORG_ADMIN_ROLES];
-    if (
-        !Array.isArray(raw) ||
-        raw.length === 0 ||
-        raw.some((role) => typeof role !== 'string' || role.trim() === '')
-    ) {
-        throw configError(
-            'appDefinition.user.orgAdminRoles',
-            'must be a non-empty array of role names'
-        );
-    }
-    return [...raw];
-}
-
-/**
- * `user.orgAdminGateBearerTokens`: judge Frigg bearer-token callers by role
- * like adopter-token callers. Default false: they keep their pre-roles
- * behaviour and may manage the organization they act in.
- */
-function readGateBearerTokens(appDefinition) {
-    const raw = appDefinition?.user?.orgAdminGateBearerTokens;
-    if (raw === undefined || raw === null) return false;
-    if (typeof raw !== 'boolean') {
-        throw configError('appDefinition.user.orgAdminGateBearerTokens', 'must be a boolean');
-    }
-    return raw;
-}
-
-/**
- * Every binding of every integration with its resolved scope and where it came
- * from, parsing each integration's settings once. Throws OwnershipConfigError
- * for any invalid one. Exported for tooling that wants to show the chain.
- */
-function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
-    const app = readAppOwnership(appDefinition);
-    const rows = [];
-    for (const integrationClass of appDefinition?.integrations || []) {
-        const Definition = integrationClass?.Definition;
-        const name = Definition?.name || 'unnamed';
-        const ownership = readIntegrationOwnership(integrationClass);
-        for (const [key, binding] of Object.entries(Definition?.modules || {})) {
-            const moduleName = entityTypeNameOf(binding?.definition);
-            const resolved = resolveScope({
-                binding: parseScopeSetting(
-                    bindingScopeSetting(Definition, key),
-                    `integration '${name}' binding '${key}' scope`
-                ),
-                integration: ownership.scope,
-                entityType: moduleName
-                    ? entityTypeRegistry?.get(moduleName)?.settings?.scope
-                    : undefined,
-                app: app.scope,
-                primary,
-            });
-            rows.push({
-                integration: name,
-                binding: key,
-                moduleName: moduleName ?? null,
-                scope: resolved.scope,
-                source: resolved.source,
-                owner: ownership.owner,
-            });
-        }
-    }
-    return rows;
-}
-
-/**
- * Validates every ownership setting in one pass and returns the app-level
- * config the runtime needs.
- *
- * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[], gateBearerTokens: boolean}}
- * @throws {OwnershipConfigError}
- */
-function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
-    const app = readAppOwnership(appDefinition);
-    for (const [name, entry] of entityTypeRegistry || []) {
-        parseScopeSetting(entry?.settings?.scope, `entity type '${name}' scope`);
-    }
-    const rows = listBindingScopes(
-        appDefinition,
-        entityTypeRegistry,
-        appDefinition?.user?.primary
-    );
-    // §3.3: a shared integration must not run on one person's credential.
-    for (const row of rows) {
-        if (row.owner === 'organization' && row.scope === SCOPES.INDIVIDUAL) {
-            throw configError(
-                `integration '${row.integration}' binding '${row.binding}'`,
-                "an organization-owned integration cannot bind an 'individual' entity"
-            );
-        }
-    }
-    return Object.freeze({
-        scope: app.scope,
-        individualAcross: app.individualAcross,
-        orgAdminRoles: Object.freeze(readOrgAdminRoles(appDefinition)),
-        gateBearerTokens: readGateBearerTokens(appDefinition),
-    });
-}
-
-module.exports = {
-    bindingScopeSetting,
-    readAppOwnership,
-    readIntegrationOwnership,
-    listBindingScopes,
-    resolveOwnershipConfig,
-};

package/modules/scope-policy.js

@@ -1,112 +0,0 @@
-/**
- * The object a use case asks about scopes (ADR-056 §3): the app's ownership
- * config and entity type registry bound once, as closures. With no arguments it
- * is the behaviour of an app that configures nothing.
- */
-
-const {
-    INDIVIDUAL_ACROSS_VALUES,
-    DEFAULT_ORG_ADMIN_ROLES,
-    configError,
-    parseScopeSetting,
-    resolveScope,
-    resolveOwnerForScope,
-} = require('./scope-resolution');
-const {
-    accessContext,
-    accessToOwner,
-    describeRecord,
-} = require('./scope-visibility');
-
-/**
- * @param {Object} [params]
- * @param {{scope: *, individualAcross: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [params.ownership] - the raw
- *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
- *   `{ default, allow }` parses to itself)
- * @param {Map} [params.entityTypeRegistry]
- */
-function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
-    const appScope = parseScopeSetting(
-        ownership?.scope,
-        'appDefinition.ownership.scope'
-    );
-    const individualAcross = ownership?.individualAcross ?? 'organization';
-    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
-        throw configError(
-            'appDefinition.ownership.individualAcross',
-            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
-        );
-    }
-
-    const orgAdminRoles = ownership?.orgAdminRoles ?? DEFAULT_ORG_ADMIN_ROLES;
-    const gateBearerTokens = ownership?.gateBearerTokens === true;
-
-    const contextFor = (user) =>
-        accessContext(user, { individualAcross, orgAdminRoles, gateBearerTokens });
-
-    /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
-    const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
-        resolveScope({
-            request: requestScope,
-            binding,
-            integration,
-            entityType: entityTypeRegistry?.get?.(entityType)?.settings?.scope,
-            app: appScope,
-            primary: user?.config?.primary,
-        });
-
-    /**
-     * Scope, then owner and organization, for a new entity. `legacyOrgId` (the
-     * person's legacy organization pointer) rides along so a later lookup can
-     * reuse an entity written before scoping.
-     */
-    const resolveOwnership = ({ entityType, requestScope, user }) => {
-        const ctx = contextFor(user);
-        const resolved = resolveEntityScope({ entityType, requestScope, user });
-        return {
-            ...resolveOwnerForScope(resolved.scope, ctx),
-            legacyOrgId: ctx.legacyOrgId,
-            source: resolved.source,
-        };
-    };
-
-    /**
-     * The owner and organization for a scope that is already decided: a
-     * re-authorization keeps the scope its connection has, whatever the config
-     * says now. The admin gate applies as it does on create.
-     */
-    const ownershipForScope = ({ scope, user }) => {
-        const ctx = contextFor(user);
-        return {
-            ...resolveOwnerForScope(scope, ctx),
-            legacyOrgId: ctx.legacyOrgId,
-            source: 'fixed',
-        };
-    };
-
-    /** Whether `user` may load this stored entity for use (same clauses as the list). */
-    const canUseEntity = (user, entity) =>
-        describeRecord(entity, contextFor(user), 'entity') !== null;
-
-    /**
-     * What `user` may do with a record owned by `ownerId` that has no
-     * organization of its own (a credential): manage, or null when not theirs.
-     */
-    const accessToOwnedBy = (user, ownerId) => accessToOwner(ownerId, contextFor(user));
-
-    return Object.freeze({
-        individualAcross,
-        orgAdminRoles,
-        accessToOwnedBy,
-        accessContext: contextFor,
-        resolveScope: resolveEntityScope,
-        resolveOwnership,
-        ownershipForScope,
-        canUseEntity,
-    });
-}
-
-/** The policy of an app that configures nothing; what a use case gets by default. */
-const DEFAULT_SCOPE_POLICY = createScopePolicy();
-
-module.exports = { createScopePolicy, DEFAULT_SCOPE_POLICY };