@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/user/use-cases/get-user-from-x-frigg-headers.js

@@ -1,10 +1,38 @@
 const Boom = require('@hapi/boom');
-const { User } = require('../user');
+const {
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+    wantsIndividual,
+} = require('../app-user-helpers');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.user.x_frigg_headers');
+
+const NOT_A_MEMBER_MESSAGE =
+    'Not a member: the user identified by x-frigg-appUserId is not a member of the ' +
+    'organization identified by x-frigg-appOrgId, and strict membership does not ' +
+    'allow these headers to add them.';
 
 /**
  * Use case for retrieving or creating a user from x-frigg header identifiers.
  * Supports backend-to-backend API communication using application user IDs.
  *
+ * `x-frigg-appOrgId` names the request's active organization (ADR-056 §3.6).
+ * A person the organization does not know yet is added to it as a member; the
+ * person is never moved out of another organization, and
+ * `IndividualUser.organizationId` is set only on a first link.
+ *
+ * With `user.strictMembership: true` the headers cannot make anyone a member of
+ * an organization that already existed: a person who is not already a member
+ * (a brand-new `appUserId` included) is refused with 400. The one thing strict
+ * mode still allows is naming an organization this request creates, so a first
+ * login can bootstrap its own organization. Apps that run strict add people to
+ * existing organizations themselves, through the membership repository.
+ *
+ * `strictUserValidation` is a deprecated alias for `strictMembership`; its
+ * meaning changed (it used to reject a mismatched individual/organization pair).
+ *
  * @class GetUserFromXFriggHeaders
  */
 class GetUserFromXFriggHeaders {
@@ -12,11 +40,22 @@ class GetUserFromXFriggHeaders {
      * Creates a new GetUserFromXFriggHeaders instance.
      * @param {Object} params - Configuration parameters.
      * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {import('./ensure-organization-membership').EnsureOrganizationMembership} params.ensureOrganizationMembership
      * @param {Object} params.userConfig - The user config in the app definition.
      */
-    constructor({ userRepository, userConfig }) {
+    constructor({ userRepository, ensureOrganizationMembership, userConfig }) {
         this.userRepository = userRepository;
+        this.ensureOrganizationMembership = ensureOrganizationMembership;
         this.userConfig = userConfig;
+
+        const { strictMembership, strictUserValidation } = userConfig ?? {};
+        if (strictUserValidation !== undefined && strictMembership === undefined) {
+            log.warn(
+                'user.strictUserValidation is deprecated and now means strictMembership; rename it',
+                { eventName: `${log.name}.strict_user_validation_deprecated` }
+            );
+        }
+        this.strict = Boolean(strictMembership ?? strictUserValidation);
     }
 
     /**
@@ -25,7 +64,7 @@ class GetUserFromXFriggHeaders {
      * @param {string} [appUserId] - The app user ID from x-frigg-appUserId header.
      * @param {string} [appOrgId] - The app organization ID from x-frigg-appOrgId header.
      * @returns {Promise<import('../user').User>} The authenticated user object.
-     * @throws {Boom} 400 Bad Request if neither ID is provided or if both IDs are provided but belong to different users.
+     * @throws {Boom} 400 Bad Request if neither ID is provided or, in strict mode, if the person is not already a member of the existing organization named.
      */
     async execute(appUserId, appOrgId) {
         // At least one header must be provided
@@ -36,96 +75,60 @@ class GetUserFromXFriggHeaders {
         }
 
         // Find users by both IDs if both are provided
-        let individualUserData = null;
-        let organizationUserData = null;
-
-        if (appUserId && this.userConfig.individualUserRequired !== false) {
-            individualUserData =
-                await this.userRepository.findIndividualUserByAppUserId(
-                    appUserId
-                );
-        }
+        let { individual: individualUserData, organization: organizationUserData } =
+            await findAppUsers(this.userRepository, this.userConfig, {
+                appUserId,
+                appOrgId,
+            });
 
-        if (appOrgId && this.userConfig.organizationUserRequired) {
-            organizationUserData =
-                await this.userRepository.findOrganizationUserByAppOrgId(
-                    appOrgId
-                );
-        }
+        // Strict mode refuses to make anyone a member of an organization that
+        // existed before this request. Only an organization created below is
+        // exempt, since it has no members to disagree with.
+        const refuseNewMembers = this.strict && Boolean(organizationUserData);
 
-        // VALIDATION/AUTO-LINKING: If both IDs provided and both users exist, handle mismatch
+        // A person who does not exist yet cannot already be a member, so refuse
+        // now, before anything is persisted: refusing after creating them would
+        // leave an orphan individual behind on every refused request.
         if (
+            refuseNewMembers &&
             appUserId &&
-            appOrgId &&
-            individualUserData &&
-            organizationUserData
+            wantsIndividual(this.userConfig) &&
+            !individualUserData
         ) {
-            // Check if individual user is linked to the org user
-            const individualOrgId =
-                individualUserData.organizationUser?.toString();
-            const expectedOrgId = organizationUserData.id?.toString();
-
-            if (individualOrgId !== expectedOrgId) {
-                // Default behavior: Auto-link disconnected users
-                // Opt-in strict mode: Throw error on mismatch
-                if (this.userConfig.strictUserValidation) {
-                    throw Boom.badRequest(
-                        'User ID mismatch: x-frigg-appUserId and x-frigg-appOrgId refer to different users. ' +
-                            'Provide only one identifier or ensure they belong to the same user.'
-                    );
-                }
-
-                // Auto-link the users
-                individualUserData = await this.userRepository.linkIndividualToOrganization(
-                    individualUserData.id,
-                    organizationUserData.id
-                );
-            }
+            throw Boom.badRequest(NOT_A_MEMBER_MESSAGE);
         }
 
         // Auto-create users independently if they don't exist and are required
-        if (
-            !individualUserData &&
-            appUserId &&
-            this.userConfig.individualUserRequired !== false
-        ) {
-            individualUserData =
-                await this.userRepository.createIndividualUser({
-                    appUserId,
-                    username: `app-user-${appUserId}`,
-                    email: `${appUserId}@app.local`,
-                });
-        }
-
-        if (
-            !organizationUserData &&
-            appOrgId &&
-            this.userConfig.organizationUserRequired
-        ) {
-            organizationUserData =
-                await this.userRepository.createOrganizationUser({
-                    appOrgId,
-                });
-
-            // Link individual user to newly created org user if individual exists
-            if (individualUserData && organizationUserData) {
-                individualUserData = await this.userRepository.linkIndividualToOrganization(
-                    individualUserData.id,
-                    organizationUserData.id
-                );
+        const created = await createMissingAppUsers(
+            this.userRepository,
+            this.userConfig,
+            {
+                appUserId,
+                appOrgId,
+                individual: individualUserData,
+                organization: organizationUserData,
             }
+        );
+        individualUserData = created.individual;
+        organizationUserData = created.organization;
+
+        // The organization named by the header is the active one: join it
+        // rather than re-linking the person's single organizationId.
+        const ensured = await this.ensureOrganizationMembership.execute({
+            individual: individualUserData,
+            organization: organizationUserData,
+            requireExisting: refuseNewMembers,
+        });
+        if (refuseNewMembers && individualUserData && !ensured.membership) {
+            throw Boom.badRequest(NOT_A_MEMBER_MESSAGE);
         }
+        individualUserData = ensured.individual;
 
-        const user = new User(
+        return buildUser(
+            this.userConfig,
             individualUserData,
-            organizationUserData,
-            this.userConfig.usePassword,
-            this.userConfig.primary,
-            this.userConfig.individualUserRequired,
-            this.userConfig.organizationUserRequired
+            organizationUserData
         );
-
-        return user;
     }
 }
 

package/user/user.js

@@ -1,5 +1,20 @@
 const bcrypt = require('bcryptjs');
 
+/**
+ * How the request that produced a `User` proved who it is. Set by
+ * AuthenticateUser, never inferred from a missing value. Organization roles
+ * (ADR-056 §3, §3.6) depend on it: a shared-secret caller is the app's own
+ * backend and is trusted to manage; a Frigg bearer token keeps its pre-roles
+ * behaviour unless the app opts in (`user.orgAdminGateBearerTokens`); an
+ * adopter token has the role it carries, else the stored membership role,
+ * else `MEMBER`.
+ */
+const AUTH_SOURCES = Object.freeze({
+    SHARED_SECRET: 'shared-secret',
+    ADOPTER_JWT: 'adopter-jwt',
+    BEARER_TOKEN: 'bearer-token',
+});
+
 /**
  * Represents a user in the system. The User class is a domain entity,
  * @class User
@@ -18,6 +33,14 @@ class User {
         this.individualUser = individualUser;
         this.organizationUser = organizationUser;
         this.usePassword = usePassword;
+        // Organization role from an adopter token claim (ADR-056 §2), per
+        // request. When present it wins over the stored membership role.
+        this.orgRole = null;
+        // The role stored on the person's membership of the active organization
+        // (OrganizationMembership.orgRole); used when the token carries none.
+        this.membershipRole = null;
+        // How this request authenticated (one of AUTH_SOURCES); null until AuthenticateUser says.
+        this.authSource = null;
 
         this.config = {
             primary,
@@ -26,6 +49,17 @@ class User {
         };
     }
 
+    /**
+     * The organization this request acts in (ADR-056 §3.6): the one the token or
+     * `x-frigg-appOrgId` named, not the person's legacy `organizationId`
+     * pointer. Null when the request has no organization.
+     * @returns {string|null}
+     */
+    getActiveOrganizationId() {
+        const id = this.organizationUser?.id;
+        return id === undefined || id === null || id === '' ? null : String(id);
+    }
+
     getPrimaryUser() {
         if (this.config.primary === 'organization') {
             return this.organizationUser;
@@ -33,6 +67,11 @@ class User {
         return this.individualUser;
     }
 
+    /**
+     * The id of the primary user. With `primary: 'organization'` this is the
+     * active organization (the one the request named), never the organization
+     * the person was first linked to.
+     */
     getId() {
         return this.getPrimaryUser()?.id;
     }
@@ -65,6 +104,30 @@ class User {
         return this.config.individualUserRequired;
     }
 
+    getAuthSource() {
+        return this.authSource;
+    }
+
+    setAuthSource(authSource) {
+        this.authSource = authSource ?? null;
+    }
+
+    getOrgRole() {
+        return this.orgRole;
+    }
+
+    setOrgRole(orgRole) {
+        this.orgRole = orgRole ?? null;
+    }
+
+    getMembershipRole() {
+        return this.membershipRole;
+    }
+
+    setMembershipRole(membershipRole) {
+        this.membershipRole = membershipRole ?? null;
+    }
+
     getIndividualUser() {
         return this.individualUser;
     }
@@ -122,4 +185,4 @@ class User {
     }
 }
 
-module.exports = { User }; 
+module.exports = { User, AUTH_SOURCES }; 

package/errors/mapping-already-exists-error.js

@@ -1,14 +0,0 @@
-const { BaseError } = require('./base-error');
-
-class MappingAlreadyExistsError extends BaseError {
-    constructor(integrationId, sourceId, ...errorOptions) {
-        super(
-            `Mapping already exists for integration ${integrationId} and sourceId ${sourceId}`,
-            ...errorOptions
-        );
-        this.integrationId = integrationId;
-        this.sourceId = sourceId;
-    }
-}
-
-module.exports = { MappingAlreadyExistsError };

package/handlers/workers/integration-triggers.js

@@ -1,25 +0,0 @@
-/**
- * The `{integration}Triggers` functions (ADR-055 §2-3): one per integration that declares triggers. Devtools gives
- * each one schedule per distinct tick (`{ tick: '5m', time }`) and one per `at` trigger (`{ at, time }`); this only
- * hands the event to the tick use case.
- */
-const { createHandler } = require('@friggframework/core');
-const { loadAppDefinition } = require('../app-definition-loader');
-const { hasTriggers } = require('../../integrations/triggers');
-const { runTriggerTick } = require('../../integrations/use-cases/run-trigger-tick');
-
-const handlers = {};
-const { integrations: integrationClasses } = loadAppDefinition();
-
-for (const IntegrationClass of integrationClasses) {
-    if (!hasTriggers(IntegrationClass)) continue;
-    handlers[IntegrationClass.Definition.name] = {
-        tick: createHandler({
-            eventName: `Trigger tick for ${IntegrationClass.Definition.name}`,
-            isUserFacingResponse: false,
-            method: async (event, context) => runTriggerTick(IntegrationClass, event || {}, context),
-        }),
-    };
-}
-
-module.exports = { handlers };

package/infrastructure/scheduler/recurrence.js

@@ -1,204 +0,0 @@
-/**
- * Recurrence: how often something repeats, in a form no host owns.
- *
- *   { every: '15m' }                               every 15 minutes ('30s' is refused: ticks are whole minutes)
- *   { cron: '0 9 * * 1-5', timezone: 'America/New_York' }   standard five-field cron (minute hour dom month dow)
- *
- * Recurring triggers (ADR-055, integrations/triggers.js) use it for the timing an installation may choose and for
- * the floor a developer sets on that choice. Nothing here creates a host schedule: the tick asks `lastFiringIn`
- * whether a cron fired since the previous tick, so a per-installation calendar needs no schedule of its own.
- *
- * Pure; no I/O.
- */
-
-const EVERY = /^(\d+)\s*(m|h|d)$/;
-const UNIT_MINUTES = { m: 1, h: 60, d: 1440 };
-
-/** '15m' -> 15, '2h' -> 120, '1d' -> 1440. Anything else -> null. */
-function parseEvery(every) {
-    const m = EVERY.exec(String(every ?? '').trim());
-    if (!m) return null;
-    const n = Number(m[1]) * UNIT_MINUTES[m[2]];
-    return n > 0 ? n : null;
-}
-
-const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
-const DAYS = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
-const FIELDS = [
-    { name: 'minute', min: 0, max: 59 },
-    { name: 'hour', min: 0, max: 23 },
-    { name: 'day of month', min: 1, max: 31 },
-    { name: 'month', min: 1, max: 12, names: MONTHS, base: 1 },
-    { name: 'day of week', min: 0, max: 7, names: DAYS, base: 0 },   // 0 and 7 are both Sunday
-];
-
-function atom(token, field) {
-    const t = token.toUpperCase();
-    if (field.names) {
-        const i = field.names.indexOf(t);
-        if (i >= 0) return i + field.base;
-    }
-    if (!/^\d+$/.test(t)) return null;
-    const n = Number(t);
-    return n >= field.min && n <= field.max ? n : null;
-}
-
-/** One cron field -> the sorted set of values it matches, or an error string. */
-function parseField(text, field) {
-    const out = new Set();
-    for (const part of text.split(',')) {
-        const [range, stepText] = part.split('/');
-        if (part.split('/').length > 2) return `${field.name}: "${part}" has more than one step`;
-        const step = stepText === undefined ? 1 : Number(stepText);
-        if (!Number.isInteger(step) || step < 1) return `${field.name}: step "${stepText}" is not a positive whole number`;
-        let lo, hi;
-        if (range === '*') { lo = field.min; hi = field.name === 'day of week' ? 6 : field.max; }
-        else if (range.includes('-')) {
-            const [a, b] = range.split('-');
-            lo = atom(a, field); hi = atom(b, field);
-            if (lo === null || hi === null) return `${field.name}: "${range}" is out of range`;
-            if (lo > hi) return `${field.name}: "${range}" runs backwards`;
-        } else {
-            lo = atom(range, field);
-            if (lo === null) return `${field.name}: "${range}" is out of range`;
-            hi = stepText === undefined ? lo : (field.name === 'day of week' ? 6 : field.max);
-        }
-        for (let v = lo; v <= hi; v += step) out.add(field.name === 'day of week' && v === 7 ? 0 : v);
-    }
-    return [...out].sort((a, b) => a - b);
-}
-
-/**
- * Parse a five-field cron. Returns { fields: [Set x5], restricted: { dom, dow } } or { error }.
- * `restricted` records whether day-of-month / day-of-week were given (not `*`), which decides how they combine.
- */
-function parseCron(cron) {
-    const parts = String(cron ?? '').trim().split(/\s+/);
-    if (parts.length !== 5 || parts[0] === '') return { error: 'A cron expression has five fields: minute hour day-of-month month day-of-week' };
-    const fields = [];
-    for (let i = 0; i < 5; i += 1) {
-        const v = parseField(parts[i], FIELDS[i]);
-        if (typeof v === 'string') return { error: v };
-        fields.push(new Set(v));
-    }
-    return { fields, parts, restricted: { dom: parts[2] !== '*', dow: parts[4] !== '*' } };
-}
-
-/** Does a parsed cron fire at this (UTC-free, wall-clock) minute? Standard cron: dom and dow OR when both are set. */
-function matches(parsed, d) {
-    const [mi, h, dom, mon, dow] = parsed.fields;
-    if (!mi.has(d.getUTCMinutes()) || !h.has(d.getUTCHours()) || !mon.has(d.getUTCMonth() + 1)) return false;
-    const domHit = dom.has(d.getUTCDate()), dowHit = dow.has(d.getUTCDay());
-    if (parsed.restricted.dom && parsed.restricted.dow) return domHit || dowHit;
-    return domHit && dowHit;
-}
-
-/**
- * The shortest gap, in minutes, between two firings. For `every` it is the interval; for cron it is measured over
- * fifteen months of wall-clock minutes (long enough to see every month and weekday combination), so a floor such as
- * "no more often than every 15 minutes" is checked against what the expression really does, not its spelling.
- * Returns Infinity for an expression that fires at most once in that window, null when invalid.
- */
-function minGapMinutes(recurrence) {
-    if (recurrence?.every !== undefined) return parseEvery(recurrence.every);
-    const parsed = parseCron(recurrence?.cron);
-    return parsed.error ? null : scan(parsed).best;
-}
-
-/** Walk fifteen months of firings: how many there are and the shortest gap between two. */
-function scan(parsed) {
-    const [mi, h] = parsed.fields;
-    const minutes = [...mi], hours = [...h];
-    let prev = null, best = Infinity, count = 0;
-    const start = Date.UTC(2027, 0, 1);
-    for (let day = 0; day < 457 && best > 1; day += 1) {     // fifteen months: every month and weekday pairing
-        const midnight = start + day * 86400000;
-        if (!matches(parsed, new Date(midnight + hours[0] * 3600000 + minutes[0] * 60000))) continue;
-        for (const hr of hours) {
-            for (const mn of minutes) {
-                const t = day * 1440 + hr * 60 + mn;
-                if (prev !== null && t - prev < best) best = t - prev;
-                prev = t;
-                count += 1;
-            }
-        }
-    }
-    return { best, count };
-}
-
-/** Is `tz` an IANA time zone this runtime knows? */
-function isTimeZone(tz) {
-    try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); return true; } catch { return false; }
-}
-
-/**
- * Validate a recurrence. `min` is an optional floor ('15m'): the expression must never fire more often.
- * @returns {string[]} problems, empty when valid
- */
-function validateRecurrence(recurrence, { min } = {}) {
-    const problems = [];
-    if (!recurrence || typeof recurrence !== 'object') return ['Give a schedule as { every } or { cron, timezone? }'];
-    const hasEvery = recurrence.every !== undefined, hasCron = recurrence.cron !== undefined;
-    if (hasEvery === hasCron) return ['Give exactly one of every or cron'];
-    if (hasEvery && parseEvery(recurrence.every) === null) problems.push(`every "${recurrence.every}" is not a whole number of minutes, hours or days (15m, 2h, 1d)`);
-    if (hasCron) {
-        const parsed = parseCron(recurrence.cron);
-        if (parsed.error) problems.push(parsed.error);
-        // EventBridge (and Quartz) cannot express "this day of month OR this weekday"; refuse it everywhere, so a
-        // schedule that validates here runs on every host.
-        else if (parsed.restricted.dom && parsed.restricted.dow) problems.push('Restrict day of month or day of week, not both');
-        else if (scan(parsed).count === 0) problems.push(`"${recurrence.cron}" never fires`);
-    }
-    if (recurrence.timezone !== undefined && (hasEvery || !isTimeZone(recurrence.timezone))) {
-        problems.push(hasEvery ? 'timezone applies to cron schedules only' : `Unknown time zone "${recurrence.timezone}"`);
-    }
-    if (!problems.length && min !== undefined) {
-        const floor = parseEvery(min);
-        const gap = minGapMinutes(recurrence);
-        if (floor === null) problems.push(`minimum interval "${min}" is not a duration (15m, 2h, 1d)`);
-        else if (gap !== null && gap < floor) problems.push(`Runs every ${gap} minute${gap === 1 ? '' : 's'} at its most frequent; the minimum is ${min}`);
-    }
-    return problems;
-}
-
-/** The comparable identity of a recurrence (what decides whether a stored schedule must be updated). */
-function recurrenceKey(r) {
-    if (!r) return '';
-    return r.every !== undefined ? `every:${parseEvery(r.every)}` : `cron:${String(r.cron).trim().split(/\s+/).join(' ')}@${r.timezone || 'UTC'}`;
-}
-
-const wallClockFormats = new Map();
-/**
- * The wall-clock time of an instant in a time zone, as a Date whose UTC fields hold that wall clock (what `matches`
- * reads). Seconds are dropped.
- */
-function wallClock(ms, timezone = 'UTC') {
-    if (timezone === 'UTC') return new Date(Math.floor(ms / 60000) * 60000);
-    let format = wallClockFormats.get(timezone);
-    if (!format) {
-        format = new Intl.DateTimeFormat('en-US', { timeZone: timezone, hourCycle: 'h23', year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric' });
-        wallClockFormats.set(timezone, format);
-    }
-    const p = Object.fromEntries(format.formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
-    return new Date(Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour) % 24, Number(p.minute)));
-}
-
-/**
- * The latest whole minute in (fromMs, toMs] at which a cron recurrence fires in its time zone, as epoch ms, or null.
- *
- * This is how one shared tick serves a calendar each installation chose: the tick asks whether the cron fired since
- * the previous tick. It is stateless, so a tick that runs twice for the same slot gives the same answer (and the same
- * `scheduledFor`, which is what a run dedupes on). Real instants are walked, so a wall-clock time a DST change skips
- * does not fire that day, and one it repeats fires twice.
- */
-function lastFiringIn(recurrence, fromMs, toMs) {
-    const parsed = parseCron(recurrence?.cron);
-    if (parsed.error) return null;
-    const tz = recurrence.timezone || 'UTC';
-    for (let t = Math.floor(toMs / 60000) * 60000; t > fromMs; t -= 60000) {
-        if (matches(parsed, wallClock(t, tz))) return t;
-    }
-    return null;
-}
-
-module.exports = { parseEvery, parseCron, minGapMinutes, validateRecurrence, recurrenceKey, isTimeZone, matches, wallClock, lastFiringIn };