@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

package/modules/scope-config.js

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

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

package/modules/scope-resolution.js

@@ -0,0 +1,288 @@
+/**
+ * Scope resolution and ownership on create (ADR-056 §3.1, §3.2, §3.6).
+ *
+ * No I/O: everything here is a function of what it is handed (settings, a
+ * request's identity context, stored rows). This file also holds the shared
+ * constants and `OwnershipConfigError`, so `scope-config.js` (which validates
+ * app definitions) and `scope-visibility.js` can import them without a cycle.
+ *
+ * There is no `scope` column. The owner's user type already says it: no owner
+ * is `global`, the active organization's user is `organization`, the caller's
+ * individual user is `individual` (docs/guides/entity-scopes.md).
+ */
+
+const Boom = require('@hapi/boom');
+const { BaseError } = require('../errors/base-error');
+const { isPresent, sameId } = require('../user/membership');
+
+const SCOPES = Object.freeze({
+    INDIVIDUAL: 'individual',
+    ORGANIZATION: 'organization',
+    GLOBAL: 'global',
+});
+const SCOPE_VALUES = Object.freeze(Object.values(SCOPES));
+const INDIVIDUAL_ACROSS_VALUES = Object.freeze(['organization', 'all']);
+const OWNER_RULES = Object.freeze(['derive', 'individual', 'organization']);
+const ACCESS = Object.freeze({ MANAGE: 'manage', USE: 'use', VIEW: 'view' });
+
+/** The organization roles that may manage organization-level things unless `user.orgAdminRoles` says. */
+const DEFAULT_ORG_ADMIN_ROLES = Object.freeze(['ADMIN']);
+
+/** Raised at app-definition load for an invalid ownership setting. */
+class OwnershipConfigError extends BaseError {
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'OWNERSHIP_CONFIG_INVALID';
+    }
+}
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const configError = (where, message) =>
+    new OwnershipConfigError(`${where}: ${message}`);
+
+/**
+ * One level's setting: a scope (`'organization'`) or a default plus what a
+ * request may choose (`{ default, allow }`). Returns `{ default, allow }`, or
+ * null when the level sets nothing. Idempotent on its own output.
+ */
+function parseScopeSetting(setting, where) {
+    if (setting === undefined || setting === null) return null;
+    if (typeof setting === 'string') {
+        if (!SCOPE_VALUES.includes(setting)) {
+            throw configError(
+                where,
+                `scope '${setting}' is not one of ${SCOPE_VALUES.join(', ')}`
+            );
+        }
+        return { default: setting, allow: [setting] };
+    }
+    if (!isPlainObject(setting)) {
+        throw configError(where, 'scope must be a scope name or { default, allow }');
+    }
+    const unknown = Object.keys(setting).filter(
+        (key) => key !== 'default' && key !== 'allow'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown scope setting(s): ${unknown.join(', ')}`);
+    }
+    const { allow, default: defaultScope } = setting;
+    if (allow !== undefined) {
+        if (
+            !Array.isArray(allow) ||
+            allow.length === 0 ||
+            allow.some((value) => !SCOPE_VALUES.includes(value)) ||
+            new Set(allow).size !== allow.length
+        ) {
+            throw configError(
+                where,
+                `scope.allow must list one or more of ${SCOPE_VALUES.join(', ')} once each`
+            );
+        }
+    }
+    if (defaultScope !== undefined && !SCOPE_VALUES.includes(defaultScope)) {
+        throw configError(
+            where,
+            `scope.default '${defaultScope}' is not one of ${SCOPE_VALUES.join(', ')}`
+        );
+    }
+    if (defaultScope === undefined && (allow === undefined || allow.length !== 1)) {
+        throw configError(where, 'scope needs a default (or an allow list of exactly one)');
+    }
+    const resolvedDefault = defaultScope ?? allow[0];
+    const resolvedAllow = allow ?? [resolvedDefault];
+    if (!resolvedAllow.includes(resolvedDefault)) {
+        throw configError(
+            where,
+            `scope.default '${resolvedDefault}' must be in scope.allow`
+        );
+    }
+    return { default: resolvedDefault, allow: [...resolvedAllow] };
+}
+
+/** The level-6 default: `organization` for an organization-primary app. */
+const defaultScopeFor = (primary) =>
+    primary === 'organization' ? SCOPES.ORGANIZATION : SCOPES.INDIVIDUAL;
+
+const LEVELS = ['binding', 'integration', 'entityType', 'app'];
+
+/**
+ * The first level that sets a scope (ADR-056 §3.1), each overriding those
+ * below it; nothing intersects. Returns `{ default, allow, source }`.
+ */
+function decideLevel({ binding, integration, entityType, app, primary } = {}) {
+    const settings = { binding, integration, entityType, app };
+    for (const source of LEVELS) {
+        const parsed = parseScopeSetting(settings[source], `${source} scope`);
+        if (parsed) return { ...parsed, source };
+    }
+    const fallback = defaultScopeFor(primary);
+    return { default: fallback, allow: [fallback], source: 'default' };
+}
+
+/**
+ * What a request may choose, from the deciding level's `allow` list only. A
+ * tenant request is never given `global`; a scope outside the list is refused.
+ * Both are the same refusal (403 SCOPE_NOT_ALLOWED): the caller asked for
+ * something this app does not offer.
+ */
+function applyRequest(decided, request) {
+    const result = {
+        scope: decided.default,
+        source: decided.source,
+        decidedBy: decided.source,
+        allow: decided.allow,
+    };
+    if (request === undefined || request === null) return result;
+    if (!SCOPE_VALUES.includes(request)) {
+        throw Boom.badRequest(
+            `scope must be one of ${SCOPE_VALUES.filter((s) => s !== SCOPES.GLOBAL).join(', ')}`,
+            { code: 'SCOPE_INVALID', details: { field: 'scope' } }
+        );
+    }
+    if (request === SCOPES.GLOBAL) {
+        throw Boom.forbidden(
+            'global entities are created by the app owner through admin routes, not by a tenant request',
+            { code: 'SCOPE_NOT_ALLOWED' }
+        );
+    }
+    if (!decided.allow.includes(request)) {
+        throw Boom.forbidden(
+            `scope '${request}' is not allowed here; allowed: ${decided.allow.join(', ')}`,
+            {
+                code: 'SCOPE_NOT_ALLOWED',
+                details: { field: 'scope', allowed: decided.allow },
+            }
+        );
+    }
+    return { ...result, scope: request, source: 'request' };
+}
+
+/**
+ * The scope a new connection gets: decideLevel then applyRequest.
+ *
+ * @param {Object} levels
+ * @param {string} [levels.request] - `scope` on the request
+ * @param {*} [levels.binding] - `use(module, { scope })` / `Definition.entities[key].scope`
+ * @param {*} [levels.integration] - `Definition.ownership.scope`
+ * @param {*} [levels.entityType] - registry `settings.scope` (ADR-059)
+ * @param {*} [levels.app] - `appDefinition.ownership.scope`
+ * @param {string} [levels.primary] - `user.primary`
+ * @returns {{scope: string, source: string, decidedBy: string, allow: string[]}}
+ */
+function resolveScope({ request, ...levels } = {}) {
+    return applyRequest(decideLevel(levels), request);
+}
+
+const MISSING_INDIVIDUAL =
+    'this request has no individual user; send x-frigg-appuserid (or sign in with a token that names the person)';
+const MISSING_ORGANIZATION =
+    'this request has no active organization; send x-frigg-apporgid (or sign in with a token that names the organization)';
+
+const missing = (message, field) =>
+    Boom.badRequest(message, { code: 'IDENTITY_REQUIRED', details: { field } });
+
+const adminRequired = (what) =>
+    Boom.forbidden(`only an organization admin can ${what}`, {
+        code: 'ORG_ADMIN_REQUIRED',
+    });
+
+/**
+ * The owner and organization for a new entity of `scope` (§3.2):
+ *
+ *   individual   -> the person; the active organization (null under 'all')
+ *   organization -> the active organization's user, in that organization
+ *   global       -> refused here: the tenant API never creates global entities
+ *
+ * `ctx` is an access context (scope-visibility.accessContext).
+ */
+function resolveOwnerForScope(scope, ctx) {
+    if (scope === SCOPES.INDIVIDUAL) {
+        if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
+        return {
+            scope,
+            ownerId: ctx.callerId,
+            organizationId: ctx.individualAcross === 'all' ? null : ctx.activeOrgId,
+        };
+    }
+    if (scope === SCOPES.ORGANIZATION) {
+        if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        if (!ctx.canManageOrg) throw adminRequired('connect an organization-level account');
+        return { scope, ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
+    }
+    throw Boom.forbidden(
+        'global entities are created by the app owner through admin routes, not through the tenant API',
+        { code: 'SCOPE_NOT_ALLOWED' }
+    );
+}
+
+/**
+ * The owner kind of an integration (§3 "Integration ownership"): the
+ * organization when every entity it uses is organization-scoped, otherwise the
+ * person, unless `Definition.ownership.owner` says. ResolveIntegrationOwnership
+ * then refuses an integration whose entities are not all of that one scope.
+ */
+function integrationOwnerKind(entityScopes, rule = 'derive') {
+    if (rule === 'individual' || rule === 'organization') return rule;
+    return entityScopes.length > 0 &&
+        entityScopes.every((scope) => scope === SCOPES.ORGANIZATION)
+        ? SCOPES.ORGANIZATION
+        : SCOPES.INDIVIDUAL;
+}
+
+/**
+ * The owner and organization of a new integration of owner kind `kind`
+ * ('individual' | 'organization').
+ */
+function resolveIntegrationOwner(kind, ctx) {
+    if (kind === SCOPES.ORGANIZATION) {
+        if (!ctx.activeOrgId) throw missing(MISSING_ORGANIZATION, 'x-frigg-apporgid');
+        if (!ctx.canManageOrg) throw adminRequired('create an organization-level integration');
+        return { ownerId: ctx.activeOrgId, organizationId: ctx.activeOrgId };
+    }
+    if (!ctx.callerId) throw missing(MISSING_INDIVIDUAL, 'x-frigg-appuserid');
+    return { ownerId: ctx.callerId, organizationId: ctx.activeOrgId };
+}
+
+/**
+ * The entity an authorization should reuse. The same provider account in two
+ * organizations is two entities (§3.6), so an exact organization match wins.
+ * A legacy row (organizationId null, written before scoping) is reused when
+ * the visibility rule would show it here: an organization-owned one always
+ * (the owner is unambiguous), an individual one only in the person's legacy
+ * organization.
+ */
+function pickExistingEntity(candidates, { scope, organizationId, legacyOrgId }) {
+    const rows = candidates || [];
+    const unscoped = (row) => !isPresent(row.organizationId);
+    const exact = rows.find((row) =>
+        isPresent(organizationId)
+            ? sameId(row.organizationId, organizationId)
+            : unscoped(row)
+    );
+    if (exact) return exact;
+    const legacyApplies =
+        scope === SCOPES.ORGANIZATION || sameId(legacyOrgId, organizationId);
+    return legacyApplies ? rows.find(unscoped) ?? null : null;
+}
+
+module.exports = {
+    SCOPES,
+    SCOPE_VALUES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    ACCESS,
+    DEFAULT_ORG_ADMIN_ROLES,
+    OwnershipConfigError,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    decideLevel,
+    applyRequest,
+    resolveScope,
+    resolveOwnerForScope,
+    integrationOwnerKind,
+    resolveIntegrationOwner,
+    pickExistingEntity,
+};