@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/types/user/index.d.ts

@@ -0,0 +1,134 @@
+declare module "@friggframework/core/user" {
+  export type AdopterJwtAlgorithm =
+    | "ES256"
+    | "ES384"
+    | "RS256"
+    | "RS384"
+    | "RS512"
+    | "HS256"
+    | "HS384"
+    | "HS512";
+
+  /**
+   * Verification of tokens issued by the adopter's identity system
+   * (`authModes.adopterJwt`, ADR-056 §2). Set exactly one of `jwksUri` or `secret`.
+   */
+  export interface AdopterJwtConfig {
+    /** https URL of the issuer's JWKS (http only for localhost, 127.0.0.0/8, ::1). */
+    jwksUri?: string;
+    /** Shared HMAC secret for HS* tokens. */
+    secret?: string;
+    /** Required `iss`. With `jwksUri`, a startup warning is logged when unset. */
+    issuer?: string;
+    /** Accepted `aud`. Required with `jwksUri`. */
+    audience?: string | string[];
+    /** Allow-list. Default ES256 and RS256 with `jwksUri`, HS256 with `secret`. */
+    algorithms?: AdopterJwtAlgorithm[];
+    /** @deprecated Use `algorithms`. Setting both is an error. */
+    algorithm?: AdopterJwtAlgorithm;
+    /** Skew allowed on `exp` and `nbf`. Default 30. */
+    clockToleranceSec?: number;
+    /** Default `sub`. */
+    userIdClaim?: string;
+    /** Default `org_id`. */
+    orgIdClaim?: string;
+    /** Default `org_role`. Exposed as `User#getOrgRole()`; stored on a new membership. */
+    roleClaim?: string;
+  }
+
+  export interface UserAuthModes {
+    friggToken?: boolean;
+    sharedSecret?: boolean;
+    adopterJwt?: boolean;
+  }
+
+  /** The `user` block of the app definition. */
+  export interface UserConfig {
+    usePassword?: boolean;
+    primary?: "individual" | "organization";
+    individualUserRequired?: boolean;
+    organizationUserRequired?: boolean;
+    /**
+     * With `x-frigg` headers, refuse (400) to make a person a member of an
+     * organization that already existed: anyone not already a member, a
+     * brand-new `appUserId` included, is rejected. Naming an organization the
+     * request itself creates is still allowed. Default false (a non-member is
+     * added).
+     */
+    strictMembership?: boolean;
+    /**
+     * @deprecated Alias of `strictMembership`, with the same new meaning (it
+     * used to reject a mismatched individual/organization pair). Logs a warning
+     * at startup. `strictMembership` wins when both are set.
+     */
+    strictUserValidation?: boolean;
+    /**
+     * Roles that may manage organization-level things (ADR-056 §3). Default
+     * `['ADMIN']`. The role is the adopter token's role claim, else the stored
+     * membership `orgRole`, else `MEMBER` (never admin). A shared-secret
+     * (`x-frigg` header) caller needs no role, nor does a Frigg bearer token
+     * unless `orgAdminGateBearerTokens`. Compared case-insensitively.
+     * Validated at load.
+     */
+    orgAdminRoles?: string[];
+    /**
+     * Judge Frigg bearer-token callers by role like adopter-token callers.
+     * Default false: they keep their behaviour from before organization roles.
+     */
+    orgAdminGateBearerTokens?: boolean;
+    authModes?: UserAuthModes;
+    jwtConfig?: AdopterJwtConfig;
+  }
+
+  /**
+   * One person's membership of one organization (ADR-056 §3.6). `implicit` is
+   * true when it is only the legacy `IndividualUser.organizationId` pointer.
+   */
+  export interface OrganizationMembership {
+    id: string | null;
+    individualUserId: string;
+    organizationUserId: string;
+    /** Defaults to `MEMBER`. */
+    orgRole: string;
+    createdAt?: Date;
+    implicit: boolean;
+  }
+
+  export interface OrganizationMembershipRepository {
+    /** The stored row or null: the legacy `organizationId` pointer is not read here. */
+    findMembership(
+      individualUserId: string,
+      organizationUserId: string
+    ): Promise<OrganizationMembership | null>;
+    /** Idempotent: adds when absent, never changes an existing membership. */
+    addMembership(
+      individualUserId: string,
+      organizationUserId: string,
+      options?: { orgRole?: string | null }
+    ): Promise<OrganizationMembership>;
+    /** Stored rows only, oldest first; legacy-pointer people are not here. */
+    listMembershipsForOrganization(
+      organizationUserId: string
+    ): Promise<OrganizationMembership[]>;
+  }
+
+  export function createOrganizationMembershipRepository(): OrganizationMembershipRepository;
+
+  export class User {
+    /** The primary user's id; under `primary: 'organization'` the ACTIVE organization. */
+    getId(): string | undefined;
+    /** The organization this request acts in (token or `x-frigg-apporgid`), or null. */
+    getActiveOrganizationId(): string | null;
+    getAppUserId(): string | null;
+    getAppOrgId(): string | null;
+    getIndividualUser(): any;
+    getOrganizationUser(): any;
+    getPrimaryUser(): any;
+    /** The organization role from the adopter token for this request, or null. */
+    getOrgRole(): string | null;
+    setOrgRole(orgRole: string | null): void;
+    /** The stored `orgRole` of the membership of the active organization, or null. Used when the token carries no role. */
+    getMembershipRole(): string | null;
+    setMembershipRole(membershipRole: string | null): void;
+  }
+}

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 };