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

package/user/adopter-jwt-config.js

@@ -0,0 +1,177 @@
+const { getLogger } = require('../logs');
+
+const log = getLogger('frigg.user.adopter_jwt');
+
+/**
+ * Normalises and validates `user.jwtConfig` from the app definition (ADR-056 §2).
+ * Called once at startup by the app definition loader and once per verifier,
+ * never per request.
+ */
+
+const ASYMMETRIC_ALGORITHMS = ['ES256', 'ES384', 'RS256', 'RS384', 'RS512'];
+const HMAC_ALGORITHMS = ['HS256', 'HS384', 'HS512'];
+const SUPPORTED_ALGORITHMS = [...ASYMMETRIC_ALGORITHMS, ...HMAC_ALGORITHMS];
+
+const DEFAULTS = Object.freeze({
+    jwksAlgorithms: Object.freeze(['ES256', 'RS256']),
+    secretAlgorithms: Object.freeze(['HS256']),
+    clockToleranceSec: 30,
+    userIdClaim: 'sub',
+    orgIdClaim: 'org_id',
+    roleClaim: 'org_role',
+});
+
+const isNonEmptyString = (value) =>
+    typeof value === 'string' && value.trim() !== '';
+
+const hasAudience = (audience) =>
+    isNonEmptyString(audience) ||
+    (Array.isArray(audience) &&
+        audience.length > 0 &&
+        audience.every(isNonEmptyString));
+
+const LOOPBACK_IPV4 = /^127(\.\d{1,3}){3}$/;
+
+function isLoopbackHost(hostname) {
+    return (
+        hostname === 'localhost' ||
+        hostname === '[::1]' ||
+        LOOPBACK_IPV4.test(hostname)
+    );
+}
+
+/**
+ * The JWKS is the trust root: fetched over https, or over http only to the
+ * machine itself (a local identity provider in development).
+ */
+function assertJwksUri(jwksUri) {
+    let url;
+    try {
+        url = new URL(jwksUri);
+    } catch {
+        throw new Error('user.jwtConfig.jwksUri is not a valid URL');
+    }
+    if (url.protocol === 'https:') return;
+    if (url.protocol === 'http:' && isLoopbackHost(url.hostname)) return;
+    throw new Error(
+        'user.jwtConfig.jwksUri must use https (http is allowed only for localhost, 127.0.0.0/8 and ::1)'
+    );
+}
+
+/**
+ * @param {Object} [jwtConfig] `userConfig.jwtConfig`
+ * @returns {{jwksUri?: string, secret?: string, issuer?: string,
+ *   audience?: string|string[], algorithms: string[], clockToleranceSec: number,
+ *   userIdClaim: string, orgIdClaim: string, roleClaim: string}}
+ * @throws {Error} When the config cannot verify any token safely.
+ */
+function resolveAdopterJwtConfig(jwtConfig) {
+    const config = jwtConfig && typeof jwtConfig === 'object' ? jwtConfig : {};
+    const hasJwks = isNonEmptyString(config.jwksUri);
+    const hasSecret = isNonEmptyString(config.secret);
+
+    if (!hasJwks && !hasSecret) {
+        throw new Error(
+            'user.authModes.adopterJwt is enabled but user.jwtConfig has neither jwksUri nor secret'
+        );
+    }
+    if (hasJwks && hasSecret) {
+        throw new Error(
+            'user.jwtConfig sets both jwksUri and secret; set one, so a token cannot choose which key family verifies it'
+        );
+    }
+    if (hasJwks) {
+        assertJwksUri(config.jwksUri);
+        // Without an audience, a token minted by the same issuer for another
+        // service verifies here. HMAC mode shares its secret with one issuer,
+        // so it stays lenient.
+        if (!hasAudience(config.audience)) {
+            throw new Error(
+                'user.jwtConfig.audience is required when jwksUri is used'
+            );
+        }
+    }
+    if (config.algorithm !== undefined && config.algorithms !== undefined) {
+        throw new Error(
+            'user.jwtConfig sets both algorithm and algorithms; use algorithms (algorithm is a deprecated alias)'
+        );
+    }
+
+    const configured =
+        config.algorithms ??
+        (config.algorithm ? [config.algorithm] : undefined);
+    const algorithms =
+        configured ??
+        (hasSecret ? DEFAULTS.secretAlgorithms : DEFAULTS.jwksAlgorithms);
+
+    if (
+        !Array.isArray(algorithms) ||
+        algorithms.length === 0 ||
+        algorithms.some((alg) => !SUPPORTED_ALGORITHMS.includes(alg))
+    ) {
+        throw new Error(
+            `user.jwtConfig.algorithms must be a non-empty list drawn from ${SUPPORTED_ALGORITHMS.join(
+                ', '
+            )}`
+        );
+    }
+    // A key family only verifies its own algorithms; mixing them is how
+    // algorithm-confusion attacks are built.
+    if (hasSecret && algorithms.some((alg) => !HMAC_ALGORITHMS.includes(alg))) {
+        throw new Error(
+            'user.jwtConfig.algorithms may only list HS* algorithms when secret is used'
+        );
+    }
+    if (hasJwks && algorithms.some((alg) => HMAC_ALGORITHMS.includes(alg))) {
+        throw new Error(
+            'user.jwtConfig.algorithms may not list HS* algorithms when jwksUri is used'
+        );
+    }
+
+    const clockToleranceSec =
+        config.clockToleranceSec ?? DEFAULTS.clockToleranceSec;
+    if (!Number.isInteger(clockToleranceSec) || clockToleranceSec < 0) {
+        throw new Error(
+            'user.jwtConfig.clockToleranceSec must be an integer >= 0'
+        );
+    }
+
+    return {
+        jwksUri: hasJwks ? config.jwksUri : undefined,
+        secret: hasSecret ? config.secret : undefined,
+        issuer: config.issuer || undefined,
+        audience: config.audience || undefined,
+        algorithms,
+        clockToleranceSec,
+        userIdClaim: config.userIdClaim || DEFAULTS.userIdClaim,
+        orgIdClaim: config.orgIdClaim || DEFAULTS.orgIdClaim,
+        roleClaim: config.roleClaim || DEFAULTS.roleClaim,
+    };
+}
+
+/**
+ * Startup check: throws when `authModes.adopterJwt` is on and `jwtConfig`
+ * is unusable, and warns when a jwksUri has no issuer. A no-op when the mode
+ * is off, so apps that never enabled it are not affected by a stray `jwtConfig`.
+ *
+ * @param {Object|null} [userConfig] `appDefinition.user`
+ * @throws {Error}
+ */
+function assertAdopterJwtConfig(userConfig) {
+    if (userConfig?.authModes?.adopterJwt !== true) return;
+    const config = resolveAdopterJwtConfig(userConfig.jwtConfig);
+    if (config.jwksUri && !config.issuer) {
+        log.warn(
+            'Adopter JWT issuer is not set; any issuer on this JWKS is accepted',
+            {
+                eventName: `${log.name}.issuer_unset`,
+            }
+        );
+    }
+}
+
+module.exports = {
+    resolveAdopterJwtConfig,
+    assertAdopterJwtConfig,
+    SUPPORTED_ALGORITHMS,
+};

package/user/adopter-jwt-errors.js

@@ -0,0 +1,59 @@
+/* eslint-disable camelcase -- the reason codes are snake_case by spec */
+const Boom = require('@hapi/boom');
+
+/**
+ * Every failure adopter-token authentication can produce, keyed by the stable
+ * reason code clients see in `error.data.reason`. Messages are fixed text:
+ * the token and its claims never reach a message, `data` or a log record.
+ */
+const ADOPTER_JWT_ERRORS = Object.freeze({
+    token_expired: Object.freeze({ status: 401, message: 'Token has expired' }),
+    token_not_yet_valid: Object.freeze({
+        status: 401,
+        message: 'Token is not yet valid',
+    }),
+    token_invalid_signature: Object.freeze({
+        status: 401,
+        message: 'Token signature could not be verified',
+    }),
+    token_wrong_issuer: Object.freeze({
+        status: 401,
+        message: 'Token issuer is not accepted',
+    }),
+    token_wrong_audience: Object.freeze({
+        status: 401,
+        message: 'Token audience is not accepted',
+    }),
+    token_missing_user_claim: Object.freeze({
+        status: 401,
+        message: 'Token does not identify a user',
+    }),
+    token_malformed: Object.freeze({
+        status: 401,
+        message: 'Token is malformed',
+    }),
+    // Our dependency failing, not the caller's token: not a 401, so a client
+    // does not discard a good session during a JWKS outage.
+    jwks_unavailable: Object.freeze({
+        status: 503,
+        message: 'Token verification keys are unavailable',
+    }),
+    jwt_config_invalid: Object.freeze({
+        status: 500,
+        message: 'Adopter JWT authentication is misconfigured',
+    }),
+});
+
+/**
+ * @param {keyof typeof ADOPTER_JWT_ERRORS} code
+ * @returns {Boom.Boom} with `data.reason` set to `code`
+ */
+function fail(code) {
+    const { status, message } = ADOPTER_JWT_ERRORS[code];
+    return new Boom.Boom(message, {
+        statusCode: status,
+        data: { reason: code },
+    });
+}
+
+module.exports = { ADOPTER_JWT_ERRORS, fail };

package/user/adopter-token-verifier.js

@@ -0,0 +1,122 @@
+const jose = require('jose');
+const { getLogger } = require('../logs');
+const { resolveAdopterJwtConfig } = require('./adopter-jwt-config');
+const { fail } = require('./adopter-jwt-errors');
+
+const log = getLogger('frigg.user.adopter_jwt');
+
+/**
+ * The only failures that are the caller's token. Anything else thrown while
+ * verifying (a refused connection, a DNS failure, a non-200 from the JWKS, a
+ * generic JOSE error) is our key source failing, not a bad token.
+ */
+function tokenFailureCode(error) {
+    const { errors } = jose;
+    if (error instanceof errors.JWTExpired) return 'token_expired';
+    if (error instanceof errors.JWTClaimValidationFailed) {
+        if (error.claim === 'iss') return 'token_wrong_issuer';
+        if (error.claim === 'aud') return 'token_wrong_audience';
+        if (error.claim === 'nbf') return 'token_not_yet_valid';
+        return 'token_malformed';
+    }
+    if (
+        error instanceof errors.JWSSignatureVerificationFailed ||
+        error instanceof errors.JOSEAlgNotAllowed ||
+        error instanceof errors.JWKSNoMatchingKey ||
+        error instanceof errors.JWKSMultipleMatchingKeys
+    ) {
+        return 'token_invalid_signature';
+    }
+    if (
+        error instanceof errors.JWSInvalid ||
+        error instanceof errors.JWTInvalid
+    ) {
+        return 'token_malformed';
+    }
+    return null;
+}
+
+/**
+ * Verifies adopter-issued tokens (ADR-056 §2). Owns config resolution, the key
+ * source and the mapping from jose failures to typed Boom errors.
+ *
+ * Build one per app definition: the config is resolved once here, and the
+ * remote JWKS is an instance field, so jose's key cache lives as long as the
+ * verifier does. A bad config does not throw here (apps with adopterJwt off
+ * build a verifier too); `verify` answers 500 and logs the real reason.
+ *
+ * @param {Object} params
+ * @param {Object} [params.jwtConfig] `userConfig.jwtConfig`
+ * @param {Function|Object|Uint8Array} [params.keySource] Replaces the key
+ *   derived from the config: a jose key or a getKey function such as
+ *   `jose.createLocalJWKSet(jwks)`. Tests and custom key stores use it.
+ * @returns {{verify: (token: string) => Promise<Object>,
+ *   claimNames: {userIdClaim: string, orgIdClaim: string, roleClaim: string}}}
+ */
+function createAdopterTokenVerifier({ jwtConfig, keySource } = {}) {
+    let config = null;
+    let configError = null;
+    try {
+        config = resolveAdopterJwtConfig(jwtConfig);
+    } catch (error) {
+        configError = error;
+    }
+
+    let key = null;
+    if (config) {
+        key =
+            keySource ??
+            (config.jwksUri
+                ? jose.createRemoteJWKSet(new URL(config.jwksUri))
+                : new TextEncoder().encode(config.secret));
+    }
+
+    const requireConfig = () => {
+        if (config) return config;
+        log.error('Adopter JWT config is invalid', {
+            eventName: `${log.name}.config_invalid`,
+            validationMessage: configError.message,
+        });
+        throw fail('jwt_config_invalid');
+    };
+
+    return {
+        get claimNames() {
+            const { userIdClaim, orgIdClaim, roleClaim } = requireConfig();
+            return { userIdClaim, orgIdClaim, roleClaim };
+        },
+
+        /**
+         * @param {string} token
+         * @returns {Promise<Object>} the verified claims
+         * @throws {Boom} 401 with `data.reason` for a token the verifier refuses
+         * @throws {Boom} 503 `jwks_unavailable` for any other verification failure
+         * @throws {Boom} 500 `jwt_config_invalid` when the config is unusable
+         */
+        async verify(token) {
+            const resolved = requireConfig();
+            try {
+                const { payload } = await jose.jwtVerify(token, key, {
+                    algorithms: resolved.algorithms,
+                    issuer: resolved.issuer,
+                    audience: resolved.audience,
+                    clockTolerance: resolved.clockToleranceSec,
+                    // A token that never expires is not browser-safe.
+                    requiredClaims: ['exp'],
+                });
+                return payload;
+            } catch (error) {
+                const code = tokenFailureCode(error) ?? 'jwks_unavailable';
+                if (code !== 'jwks_unavailable') {
+                    log.debug('Adopter token rejected', {
+                        eventName: `${log.name}.rejected`,
+                        reason: code,
+                    });
+                }
+                throw fail(code);
+            }
+        },
+    };
+}
+
+module.exports = { createAdopterTokenVerifier };

package/user/app-user-helpers.js

@@ -0,0 +1,97 @@
+const { User } = require('./user');
+const { isUniqueViolation } = require('../database/unique-violation');
+
+/**
+ * Find-or-create steps shared by the paths that identify a user by an app user
+ * id and/or app organization id (x-frigg headers, adopter token). Each path
+ * keeps its own policy between "find" and "create".
+ */
+
+const wantsIndividual = (userConfig) =>
+    userConfig.individualUserRequired !== false;
+
+const wantsOrganization = (userConfig, appOrgId) =>
+    Boolean(appOrgId) && Boolean(userConfig.organizationUserRequired);
+
+/**
+ * Runs `create`; if it loses a first-login race (a unique-constraint
+ * violation, see database/unique-violation.js), runs `find` once, since the
+ * winner has created the row by now. Anything else, and a violation with
+ * nothing to find, is rethrown.
+ */
+async function createOrFindOnRace(create, find) {
+    try {
+        return await create();
+    } catch (error) {
+        if (!isUniqueViolation(error)) throw error;
+        const found = await find();
+        if (!found) throw error;
+        return found;
+    }
+}
+
+async function findAppUsers(
+    userRepository,
+    userConfig,
+    { appUserId, appOrgId }
+) {
+    const individual =
+        appUserId && wantsIndividual(userConfig)
+            ? await userRepository.findIndividualUserByAppUserId(appUserId)
+            : null;
+    const organization = wantsOrganization(userConfig, appOrgId)
+        ? await userRepository.findOrganizationUserByAppOrgId(appOrgId)
+        : null;
+    return { individual, organization };
+}
+
+/**
+ * Creates whichever of the two users is wanted and missing. Does not link
+ * them: linking is policy.
+ */
+async function createMissingAppUsers(
+    userRepository,
+    userConfig,
+    { appUserId, appOrgId, individual, organization }
+) {
+    if (!individual && appUserId && wantsIndividual(userConfig)) {
+        individual = await createOrFindOnRace(
+            () =>
+                userRepository.createIndividualUser({
+                    appUserId,
+                    username: `app-user-${appUserId}`,
+                    email: `${appUserId}@app.local`,
+                }),
+            () => userRepository.findIndividualUserByAppUserId(appUserId)
+        );
+    }
+    if (!organization && wantsOrganization(userConfig, appOrgId)) {
+        // No race retry here: `appOrgId` has no unique index (MongoDB cannot
+        // express one that ignores individuals), so a lost race cannot raise a
+        // violation to recover from. Two simultaneous first logins for a new
+        // organization can still create it twice.
+        organization = await userRepository.createOrganizationUser({
+            appOrgId,
+        });
+    }
+    return { individual, organization };
+}
+
+function buildUser(userConfig, individual, organization) {
+    return new User(
+        individual,
+        organization,
+        userConfig.usePassword,
+        userConfig.primary,
+        userConfig.individualUserRequired,
+        userConfig.organizationUserRequired
+    );
+}
+
+module.exports = {
+    wantsIndividual,
+    wantsOrganization,
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+};

package/user/create-user-authentication.js

@@ -0,0 +1,64 @@
+const {
+    createUserRepository,
+} = require('./repositories/user-repository-factory');
+const {
+    createOrganizationMembershipRepository,
+} = require('./repositories/organization-membership-repository-factory');
+const { createAdopterTokenVerifier } = require('./adopter-token-verifier');
+const { GetUserFromBearerToken } = require('./use-cases/get-user-from-bearer-token');
+const {
+    GetUserFromXFriggHeaders,
+} = require('./use-cases/get-user-from-x-frigg-headers');
+const { GetUserFromAdopterJwt } = require('./use-cases/get-user-from-adopter-jwt');
+const {
+    EnsureOrganizationMembership,
+} = require('./use-cases/ensure-organization-membership');
+
+/**
+ * Composition root for the three "who is this request" use cases, so the
+ * Lambda integration router and the Management API v2 wire them identically.
+ *
+ * @param {Object} params
+ * @param {Object} params.userConfig The `user` block of the app definition.
+ * @param {Object} [params.userRepository] Defaults to the configured database's.
+ * @param {Object} [params.organizationMembershipRepository] Defaults to the configured database's.
+ * @param {{verify: Function, claimNames: Object}} [params.tokenVerifier]
+ *   Defaults to a verifier for `userConfig.jwtConfig`.
+ * @returns {{
+ *   getUserFromBearerToken: GetUserFromBearerToken,
+ *   getUserFromXFriggHeaders: GetUserFromXFriggHeaders,
+ *   getUserFromAdopterJwt: GetUserFromAdopterJwt,
+ * }}
+ */
+function buildUserAuthentication({
+    userConfig,
+    userRepository = createUserRepository(),
+    organizationMembershipRepository = createOrganizationMembershipRepository(),
+    tokenVerifier = createAdopterTokenVerifier({
+        jwtConfig: userConfig?.jwtConfig,
+    }),
+}) {
+    const ensureOrganizationMembership = new EnsureOrganizationMembership({
+        userRepository,
+        organizationMembershipRepository,
+    });
+    return {
+        getUserFromBearerToken: new GetUserFromBearerToken({
+            userRepository,
+            userConfig,
+        }),
+        getUserFromXFriggHeaders: new GetUserFromXFriggHeaders({
+            userRepository,
+            ensureOrganizationMembership,
+            userConfig,
+        }),
+        getUserFromAdopterJwt: new GetUserFromAdopterJwt({
+            userRepository,
+            ensureOrganizationMembership,
+            userConfig,
+            tokenVerifier,
+        }),
+    };
+}
+
+module.exports = { buildUserAuthentication };

package/user/membership.js

@@ -0,0 +1,51 @@
+/**
+ * Organization membership rules that are not persistence (ADR-056 §3.6). Pure.
+ *
+ * `IndividualUser.organizationId` is the legacy single-org pointer. It is not
+ * copied into membership rows; it is read as an implicit membership here, in
+ * the domain, so the repositories stay atomic (a row or nothing). See
+ * docs/guides/organization-memberships.md for why this is a read-time
+ * fallback rather than a data migration.
+ */
+
+/** The role a membership has when nothing says otherwise. */
+const DEFAULT_ORG_ROLE = 'MEMBER';
+
+const isPresent = (value) =>
+    value !== undefined && value !== null && value !== '';
+
+const idString = (value) => (isPresent(value) ? String(value) : null);
+
+/** Ids compare as strings: stores return numbers or strings. */
+const sameId = (a, b) => isPresent(a) && isPresent(b) && String(a) === String(b);
+
+/**
+ * The membership the legacy `organizationId` pointer stands for in
+ * `organizationUserId`, or null when the person has no pointer or it names a
+ * different organization.
+ *
+ * @param {Object|null} individual The individual user as the repository returns it.
+ * @param {string|number} organizationUserId
+ * @returns {{id: null, individualUserId: string|null, organizationUserId: string, orgRole: string, createdAt: *, implicit: true}|null}
+ */
+function implicitMembership(individual, organizationUserId) {
+    if (!individual || !sameId(individual.organizationId, organizationUserId)) {
+        return null;
+    }
+    return {
+        id: null,
+        individualUserId: idString(individual.id),
+        organizationUserId: idString(individual.organizationId),
+        orgRole: DEFAULT_ORG_ROLE,
+        createdAt: individual.createdAt,
+        implicit: true,
+    };
+}
+
+module.exports = {
+    DEFAULT_ORG_ROLE,
+    isPresent,
+    idString,
+    sameId,
+    implicitMembership,
+};

package/user/repositories/organization-membership-record.js

@@ -0,0 +1,19 @@
+const { idString } = require('../membership');
+
+/**
+ * A stored membership row as the application sees it: every id a string
+ * whatever the database holds. `implicit` is always false here: only the
+ * domain (`user/membership.js`) produces an implicit membership.
+ */
+function toMembership(row) {
+    return {
+        id: idString(row.id ?? row._id),
+        individualUserId: idString(row.individualUserId),
+        organizationUserId: idString(row.organizationUserId),
+        orgRole: row.orgRole,
+        createdAt: row.createdAt,
+        implicit: false,
+    };
+}
+
+module.exports = { toMembership };