@friggframework/core 2.0.0--canary.678.58db4b2.0 → 2.0.0--canary.680.b3ca7f1.0

package/user/adopter-jwt-config.js

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

@@ -1,65 +0,0 @@
-/* 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',
-    }),
-    multi_org_unsupported: Object.freeze({
-        status: 403,
-        message:
-            'This user already belongs to a different organization. ' +
-            'Membership in more than one organization is not supported yet (ADR-056 §3.6).',
-    }),
-    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

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

@@ -1,73 +0,0 @@
-const { User } = require('./user');
-
-/**
- * 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);
-
-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 }
-) {
-    let createdOrganization = false;
-    if (!individual && appUserId && wantsIndividual(userConfig)) {
-        individual = await userRepository.createIndividualUser({
-            appUserId,
-            username: `app-user-${appUserId}`,
-            email: `${appUserId}@app.local`,
-        });
-    }
-    if (!organization && wantsOrganization(userConfig, appOrgId)) {
-        organization = await userRepository.createOrganizationUser({
-            appOrgId,
-        });
-        createdOrganization = true;
-    }
-    return { individual, organization, createdOrganization };
-}
-
-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/tests/doubles/adopter-jwt-fixtures.js

@@ -1,130 +0,0 @@
-/* eslint-disable camelcase -- JWT claim names (org_id, org_role) and reason codes are snake_case by spec */
-const jose = require('jose');
-
-/**
- * Key material and token signing for adopter-JWT tests. Real keys and real
- * signatures: nothing here fakes the verifier.
- */
-async function createKeys() {
-    const es = await jose.generateKeyPair('ES256');
-    const rs = await jose.generateKeyPair('RS256');
-    const attacker = await jose.generateKeyPair('ES256');
-    const publicJwks = {
-        keys: [
-            {
-                ...(await jose.exportJWK(es.publicKey)),
-                kid: 'es-1',
-                alg: 'ES256',
-                use: 'sig',
-            },
-            {
-                ...(await jose.exportJWK(rs.publicKey)),
-                kid: 'rs-1',
-                alg: 'RS256',
-                use: 'sig',
-            },
-        ],
-    };
-    return {
-        es,
-        rs,
-        attacker,
-        publicJwks,
-        localJwks: jose.createLocalJWKSet(publicJwks),
-        hmacSecret: 'a-shared-secret-that-is-long-enough-for-hs256',
-    };
-}
-
-/**
- * @param {Object} claims
- * @param {Object} opts
- * @param {Object|Uint8Array} opts.key - signing key
- * @param {string} [opts.alg='ES256']
- * @param {string} [opts.kid]
- * @param {string|null} [opts.exp='5m'] - null omits exp
- */
-async function signToken(
-    claims,
-    { key, alg = 'ES256', kid, exp = '5m', iss, aud, nbf } = {}
-) {
-    const jwt = new jose.SignJWT(claims)
-        .setProtectedHeader(kid ? { alg, kid } : { alg })
-        .setIssuedAt();
-    if (exp !== null) jwt.setExpirationTime(exp);
-    if (iss) jwt.setIssuer(iss);
-    if (aud) jwt.setAudience(aud);
-    if (nbf) jwt.setNotBefore(nbf);
-    return jwt.sign(key);
-}
-
-const b64url = (value) =>
-    Buffer.from(JSON.stringify(value)).toString('base64url');
-
-/** An unsigned token: `alg: none`, empty signature. */
-function unsignedToken(claims) {
-    return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url({
-        ...claims,
-        exp: Math.floor(Date.now() / 1000) + 300,
-    })}.`;
-}
-
-/**
- * Stateful fake of the user repository, built from jest.fn so every call is
- * observable. Individuals carry `organizationId`, as the real repositories
- * return it.
- */
-function createUserRepositoryDouble({
-    individuals = [],
-    organizations = [],
-} = {}) {
-    const individualUsers = new Map(
-        individuals.map((u) => [u.appUserId, { ...u }])
-    );
-    const organizationUsers = new Map(
-        organizations.map((o) => [o.appOrgId, { ...o }])
-    );
-    let seq = 0;
-
-    const repo = {
-        findIndividualUserByAppUserId: jest.fn(
-            async (appUserId) => individualUsers.get(appUserId) ?? null
-        ),
-        findOrganizationUserByAppOrgId: jest.fn(
-            async (appOrgId) => organizationUsers.get(appOrgId) ?? null
-        ),
-        createIndividualUser: jest.fn(async (params) => {
-            const created = {
-                id: `ind-${++seq}`,
-                organizationId: undefined,
-                ...params,
-            };
-            individualUsers.set(created.appUserId, created);
-            return created;
-        }),
-        createOrganizationUser: jest.fn(async (params) => {
-            const created = { id: `org-${++seq}`, ...params };
-            organizationUsers.set(created.appOrgId, created);
-            return created;
-        }),
-        linkIndividualToOrganization: jest.fn(
-            async (individualId, organizationId) => {
-                for (const u of individualUsers.values()) {
-                    if (u.id === individualId) {
-                        u.organizationId = organizationId;
-                        return { ...u };
-                    }
-                }
-                throw new Error('individual not found');
-            }
-        ),
-    };
-    repo.state = { individualUsers, organizationUsers };
-    return repo;
-}
-
-module.exports = {
-    createKeys,
-    signToken,
-    unsignedToken,
-    createUserRepositoryDouble,
-};