@friggframework/core 2.0.0--canary.671.e50fe9c.0 → 2.0.0--canary.678.58db4b2.0

package/CLAUDE.md

@@ -332,12 +332,14 @@ class MyIntegration extends IntegrationBase {
 - Password-based (bcrypt hashed)
 - Token-based (Bearer tokens)
 - App-based (external app user IDs)
+- Adopter JWT (`authModes.adopterJwt`, `jwtConfig`; `jose`, JWKS or HMAC; see `README.md`)
 
 **Use Cases**:
 - `login-user.js` - User authentication
 - `create-individual-user.js` - Create personal account
 - `create-organization-user.js` - Create business account
 - `get-user-from-bearer-token.js` - Token authentication
+- `get-user-from-adopter-jwt.js` - Adopter JWT verification, find-or-create (ADR-056 §2); `adopter-jwt-config.js` validates `jwtConfig` at load
 
 **Repositories**:
 - `user-repository-factory.js` - Creates database-specific repositories

package/README.md

@@ -305,6 +305,7 @@ Comprehensive user authentication and authorization system supporting both indiv
 - **Password-based**: Traditional username/password authentication
 - **Token-based**: Bearer token authentication with session management
 - **App-based**: External app user ID authentication (passwordless)
+- **Adopter token (JWT)**: A token issued by your own identity system, verified by Frigg and safe to send from a browser (see below)
 
 **Usage:**
 ```javascript
@@ -352,6 +353,62 @@ console.log('Individual user:', user.getIndividualUser());
 console.log('Organization user:', user.getOrganizationUser());
 ```
 
+#### Adopter token (JWT) authentication
+
+For a multi-tenant product (ADR-056 §2), let the browser send the token your identity system
+already issues. Frigg verifies the signature and claims, then finds or creates the individual
+user and the organization user the token names. Unlike `sharedSecret` (`x-frigg-*` headers), a
+token cannot name a user other than the one it was issued for, so it is safe in a browser.
+
+```javascript
+// backend/index.js
+const appDefinition = {
+    user: {
+        primary: 'organization',
+        individualUserRequired: true,
+        organizationUserRequired: true,
+        authModes: { adopterJwt: true, friggToken: false, sharedSecret: false },
+        jwtConfig: {
+            jwksUri: 'https://login.example.com/.well-known/jwks.json',
+            issuer: 'https://login.example.com/',
+            audience: 'my-frigg-api', // required with jwksUri
+        },
+    },
+};
+```
+
+The client sends `Authorization: Bearer <token>`. `x-frigg-appuserid` / `x-frigg-apporgid`, if
+also sent, must match the token or the request is refused with 403. That match rule lives in
+`user/use-cases/authenticate-user.js` (`validateUserMatch`), not in the token verifier. A bearer
+value that is not a three-part JWT is not offered to the verifier at all; it falls through to
+`friggToken` (or is a 401 when that mode is off).
+
+| `jwtConfig` field | Default | Meaning |
+|---|---|---|
+| `jwksUri` | | Remote JWKS (rotating keys, one per verifier, cached by jose). Must be `https`; `http` only for `localhost`, `127.0.0.0/8` or `::1`. Set exactly one of this and `secret`. |
+| `secret` | | Shared HMAC secret. Read it from an environment variable. |
+| `issuer` | not checked | Required `iss`. With `jwksUri`, a startup warning is logged when it is unset. |
+| `audience` | not checked with `secret`; **required with `jwksUri`** | Accepted `aud` (a string or a list). |
+| `algorithms` | `['ES256','RS256']` with `jwksUri`, `['HS256']` with `secret` | Allow-list. HS* is only accepted with `secret`, never with `jwksUri`. The older single `algorithm` is a deprecated alias; setting both is an error. |
+| `clockToleranceSec` | `30` | Skew allowed on `exp` and `nbf`. |
+| `userIdClaim` | `sub` | App user id (required in the token). |
+| `orgIdClaim` | `org_id` | App organization id (optional). |
+| `roleClaim` | `org_role` | Read and exposed as `user.getOrgRole()`; not stored yet. |
+
+Rules worth knowing:
+
+- Tokens must carry `exp`. `alg: none` and any algorithm outside the allow-list are refused.
+- Startup fails (`loadAppDefinition` throws) when `adopterJwt` is on and the config is unusable:
+  neither or both of `jwksUri` and `secret`, a `jwksUri` that is not https (or loopback http),
+  no `audience` with `jwksUri`, or an algorithm list that does not fit the key type.
+- Failures are `401` with a stable `data.reason`: `token_expired`, `token_not_yet_valid`,
+  `token_invalid_signature`, `token_wrong_issuer`, `token_wrong_audience`,
+  `token_missing_user_claim`, `token_malformed`. The message never contains the token or its claims.
+  Any other verification failure, such as an unreachable or unresolvable JWKS, is `503`
+  `jwks_unavailable`, not a 401, so clients do not drop good sessions.
+- A person belongs to one organization for now: a token naming a second one gets `403`
+  `multi_org_unsupported` and nothing is moved (ADR-056 §3.6 replaces this with memberships).
+
 ### 8. Lambda Utilities (`/lambda`)
 
 AWS Lambda-specific utilities and helpers.

package/handlers/app-definition-loader.js

@@ -2,6 +2,7 @@ const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
+const { assertAdopterJwtConfig } = require('../user/adopter-jwt-config');
 const { registerDeniedKeys } = require('../logs/denied-keys');
 const {
     extractCredentialFieldsFromModules,
@@ -36,6 +37,7 @@ function registerCredentialLogKeys(appDefinition, integrations) {
  * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null, managementApi: object}} An object containing the application definition.
  * @throws {Error} Throws error if backend package.json cannot be found.
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
+ * @throws {Error} Throws error if user.authModes.adopterJwt is enabled without a usable user.jwtConfig.
  * @example
  * const { integrations, userConfig, telemetry } = loadAppDefinition();
  * console.log(`Found ${integrations.length} integrations`);
@@ -65,6 +67,10 @@ function loadAppDefinition() {
         managementApi = {},
     } = appDefinition;
 
+    // Fail at load, not on the first request: an adopter-token mode with no
+    // key source would otherwise start cleanly and answer every login with 500.
+    assertAdopterJwtConfig(userConfig);
+
     registerCredentialLogKeys(appDefinition, integrations);
 
     // Degrade consistently: an invalid telemetry block must never take down a

package/integrations/integration-router.js

@@ -63,6 +63,9 @@ const {
 const {
     GetUserFromAdopterJwt,
 } = require('../user/use-cases/get-user-from-adopter-jwt');
+const {
+    createAdopterTokenVerifier,
+} = require('../user/adopter-token-verifier');
 const {
     AuthenticateWithSharedSecret,
 } = require('../user/use-cases/authenticate-with-shared-secret');
@@ -94,6 +97,9 @@ function createIntegrationRouter() {
     const getUserFromAdopterJwt = new GetUserFromAdopterJwt({
         userRepository,
         userConfig,
+        tokenVerifier: createAdopterTokenVerifier({
+            jwtConfig: userConfig?.jwtConfig,
+        }),
     });
 
     const authenticateWithSharedSecret = new AuthenticateWithSharedSecret();

package/management-api/v2/dependencies.js

@@ -22,6 +22,7 @@ function buildV2Dependencies({ appDefinition, config }) {
     const { GetUserFromBearerToken } = require('../../user/use-cases/get-user-from-bearer-token');
     const { GetUserFromXFriggHeaders } = require('../../user/use-cases/get-user-from-x-frigg-headers');
     const { GetUserFromAdopterJwt } = require('../../user/use-cases/get-user-from-adopter-jwt');
+    const { createAdopterTokenVerifier } = require('../../user/adopter-token-verifier');
     const {
         AuthenticateWithSharedSecret,
     } = require('../../user/use-cases/authenticate-with-shared-secret');
@@ -82,7 +83,11 @@ function buildV2Dependencies({ appDefinition, config }) {
     const authenticateUser = new AuthenticateUser({
         getUserFromBearerToken: new GetUserFromBearerToken({ userRepository, userConfig }),
         getUserFromXFriggHeaders: new GetUserFromXFriggHeaders({ userRepository, userConfig }),
-        getUserFromAdopterJwt: new GetUserFromAdopterJwt({ userRepository, userConfig }),
+        getUserFromAdopterJwt: new GetUserFromAdopterJwt({
+            userRepository,
+            userConfig,
+            tokenVerifier: createAdopterTokenVerifier({ jwtConfig: userConfig.jwtConfig }),
+        }),
         authenticateWithSharedSecret: new AuthenticateWithSharedSecret(),
         userConfig,
     });

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.671.e50fe9c.0",
+    "version": "2.0.0--canary.678.58db4b2.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -28,6 +28,7 @@
         "express-async-handler": "^1.2.0",
         "form-data": "^4.0.6",
         "fs-extra": "^11.2.0",
+        "jose": "^5.10.0",
         "lodash": "4.18.1",
         "lodash.get": "^4.4.2",
         "node-fetch": "^2.6.7",
@@ -47,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.671.e50fe9c.0",
-        "@friggframework/prettier-config": "2.0.0--canary.671.e50fe9c.0",
-        "@friggframework/test": "2.0.0--canary.671.e50fe9c.0",
+        "@friggframework/eslint-config": "2.0.0--canary.678.58db4b2.0",
+        "@friggframework/prettier-config": "2.0.0--canary.678.58db4b2.0",
+        "@friggframework/test": "2.0.0--canary.678.58db4b2.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "e50fe9c3d910653eef00ca7248658e7a7f637493"
+    "gitHead": "58db4b2bc17529f46b8dae1110771f5df39033ed"
 }

package/types/index.d.ts

@@ -12,3 +12,4 @@
 /// <reference path="./eslint-config/index.d.ts" />
 /// <reference path="./associations/index.d.ts" />
 /// <reference path="./syncs/index.d.ts" />
+/// <reference path="./user/index.d.ts" />

package/types/user/index.d.ts

@@ -0,0 +1,67 @@
+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()`; not stored. */
+    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;
+    strictUserValidation?: boolean;
+    authModes?: UserAuthModes;
+    jwtConfig?: AdopterJwtConfig;
+  }
+
+  export class User {
+    getId(): string | undefined;
+    getAppUserId(): string | null;
+    getAppOrgId(): string | null;
+    getIndividualUser(): any;
+    getOrganizationUser(): any;
+    getPrimaryUser(): any;
+    /** The organization role from the adopter token, or null. */
+    getOrgRole(): string | null;
+    setOrgRole(orgRole: 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,65 @@
+/* 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

@@ -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,73 @@
+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

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

package/user/use-cases/get-user-from-adopter-jwt.js

@@ -1,149 +1,136 @@
-const Boom = require('@hapi/boom');
+const { getLogger } = require('../../logs');
+const { fail } = require('../adopter-jwt-errors');
+const {
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+    wantsOrganization,
+} = require('../app-user-helpers');
+
+const log = getLogger('frigg.user.adopter_jwt');
+
+const idFromClaim = (value) => {
+    if (typeof value === 'string' && value.trim() !== '') return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return null;
+};
+
+const hasOrganization = (individual) => {
+    const id = individual?.organizationId;
+    return id !== undefined && id !== null && id !== '';
+};
 
 /**
- * STUB: Use case for retrieving a user from adopter-provided JWT token.
- *
- * This is a stub implementation for future JWT authentication support.
- * When implemented, this will allow adopters to use their own JWT tokens
- * for authentication instead of Frigg's native token system.
- *
- * FUTURE IMPLEMENTATION REQUIREMENTS:
- * - Validate JWT signature using jwtConfig.secret from app definition
- * - Support configurable signing algorithms (HS256, HS384, HS512, RS256, RS384, RS512)
- * - Extract user identifiers from JWT claims based on jwtConfig.userIdClaim and jwtConfig.orgIdClaim
- * - Find or create user based on extracted claim values
- * - Handle token expiration and validation errors
- * - Support refresh tokens (optional)
- * - Validate user ID conflicts if both individual and org IDs present in JWT
+ * Interim rule until the membership table (ADR-056 §3.6): a person belongs to
+ * one organization. Callers run this before creating anything, so a refused
+ * request leaves no new organization behind.
  *
- * RECOMMENDED IMPLEMENTATION:
- * - Use 'jsonwebtoken' package for JWT parsing and validation
- * - Cache JWT public keys for RS* algorithms
- * - Add comprehensive error handling for invalid tokens
- * - Log authentication attempts for security auditing
+ * @param {Object|null} individual The individual user as the repository returns it.
+ * @param {Object|null} organization The organization the token names, or null
+ *   when it does not exist yet.
+ * @throws {Boom} 403 `multi_org_unsupported`
+ */
+function assertSingleOrganization(individual, organization) {
+    if (!hasOrganization(individual)) return;
+    if (
+        organization &&
+        String(individual.organizationId) === String(organization.id)
+    ) {
+        return;
+    }
+    log.debug('Adopter token names a second organization', {
+        eventName: `${log.name}.multi_org_refused`,
+    });
+    throw fail('multi_org_unsupported');
+}
+
+/**
+ * Authenticates a request by a token issued by the adopter's own identity
+ * system (ADR-056 §2): verifies it, then finds or creates the individual and
+ * organization users it names.
  *
- * @todo Implement JWT validation with jsonwebtoken package
- * @todo Add unit tests for JWT parsing and claim extraction
- * @todo Document adopter JWT integration guide in Frigg docs
- * @todo Add support for JWT refresh tokens
- * @todo Implement JWT public key caching for RS* algorithms
+ * Two limits, both replaced by the membership package (F4): the first request
+ * for a new person can race another and create the user twice (no upsert), and
+ * the individual-to-organization link is one-way and set once.
  *
  * @class GetUserFromAdopterJwt
  */
 class GetUserFromAdopterJwt {
     /**
-     * Creates a new GetUserFromAdopterJwt instance.
-     * @param {Object} params - Configuration parameters.
-     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository
      * @param {Object} params.userConfig - The user config in the app definition.
+     * @param {{verify: Function, claimNames: Object}} params.tokenVerifier -
+     *   from `createAdopterTokenVerifier`.
      */
-    constructor({ userRepository, userConfig }) {
+    constructor({ userRepository, userConfig, tokenVerifier }) {
         this.userRepository = userRepository;
         this.userConfig = userConfig;
+        this.tokenVerifier = tokenVerifier;
     }
 
     /**
-     * Executes the use case.
      * @async
-     * @param {string} jwtToken - The JWT token from the Authorization header.
-     * @returns {Promise<import('../user').User>} The authenticated user object.
-     * @throws {Boom} 501 Not Implemented - This feature is not yet available.
+     * @param {string} token - The JWT from the Authorization header.
+     * @returns {Promise<import('../user').User>}
+     * @throws {Boom} 401 with `data.reason` for a token the verifier refuses
+     *   (including `token_missing_user_claim`).
+     * @throws {Boom} 403 `multi_org_unsupported`.
+     * @throws {Boom} 503 `jwks_unavailable`, 500 `jwt_config_invalid` (from the verifier).
      */
-    async execute(jwtToken) {
-        throw Boom.notImplemented(
-            'Adopter JWT authentication is not yet implemented. ' +
-                'This feature is planned for a future Frigg release. ' +
-                'Please use one of the supported authentication modes instead: ' +
-                'friggToken (native bearer token) or xFriggHeaders (backend-to-backend with x-frigg-appUserId/appOrgId headers).'
-        );
+    async execute(token) {
+        const claims = await this.tokenVerifier.verify(token);
+        const { userIdClaim, orgIdClaim, roleClaim } =
+            this.tokenVerifier.claimNames;
 
-        /* FUTURE IMPLEMENTATION PSEUDOCODE:
+        const appUserId = idFromClaim(claims[userIdClaim]);
+        if (!appUserId) throw fail('token_missing_user_claim');
 
-        const jwt = require('jsonwebtoken');
-        
-        // Validate JWT configuration exists
-        if (!this.userConfig.jwtConfig || !this.userConfig.jwtConfig.secret) {
-            throw Boom.badImplementation('JWT configuration is required when adopterJwt auth mode is enabled');
+        const rawOrgId = claims[orgIdClaim];
+        const appOrgId = idFromClaim(rawOrgId);
+        if (rawOrgId !== undefined && rawOrgId !== null && !appOrgId) {
+            throw fail('token_malformed');
         }
-        
-        try {
-            // Verify and decode JWT
-            const decoded = jwt.verify(jwtToken, this.userConfig.jwtConfig.secret, {
-                algorithms: [this.userConfig.jwtConfig.algorithm || 'HS256']
+        const role = claims[roleClaim];
+
+        const user = await this._findOrCreateUser(appUserId, appOrgId);
+        user.setOrgRole(typeof role === 'string' && role !== '' ? role : null);
+
+        log.debug('Adopter token accepted', {
+            eventName: `${log.name}.accepted`,
+            hasOrganization: Boolean(user.getOrganizationUser()),
+        });
+        return user;
+    }
+
+    async _findOrCreateUser(appUserId, appOrgId) {
+        const cfg = this.userConfig;
+        const found = await findAppUsers(this.userRepository, cfg, {
+            appUserId,
+            appOrgId,
+        });
+
+        if (wantsOrganization(cfg, appOrgId)) {
+            assertSingleOrganization(found.individual, found.organization);
+        }
+
+        const { individual: createdIndividual, organization } =
+            await createMissingAppUsers(this.userRepository, cfg, {
+                appUserId,
+                appOrgId,
+                ...found,
             });
-            
-            // Extract user identifiers from claims
-            const appUserId = decoded[this.userConfig.jwtConfig.userIdClaim || 'sub'];
-            const appOrgId = decoded[this.userConfig.jwtConfig.orgIdClaim || 'org_id'];
-            
-            // At least one identifier required
-            if (!appUserId && !appOrgId) {
-                throw Boom.badRequest('JWT must contain user or organization identifier claims');
-            }
-            
-            // Find existing users
-            let individualUserData = null;
-            let organizationUserData = null;
-            
-            if (appUserId) {
-                individualUserData = await this.userRepository.findIndividualUserByAppUserId(appUserId);
-            }
-            
-            if (appOrgId) {
-                organizationUserData = await this.userRepository.findOrganizationUserByAppOrgId(appOrgId);
-            }
-            
-            // Validate no conflicts if both IDs present
-            if (appUserId && appOrgId && individualUserData && organizationUserData) {
-                const individualOrgId = individualUserData.organizationUser?.toString();
-                const expectedOrgId = organizationUserData.id?.toString();
-                
-                if (individualOrgId !== expectedOrgId) {
-                    throw Boom.badRequest(
-                        'User ID mismatch: JWT claims refer to different users. ' +
-                        'Individual and organization IDs must belong to the same user.'
-                    );
-                }
-            }
-            
-            // Auto-create if not found
-            if (!individualUserData && !organizationUserData) {
-                if (appUserId) {
-                    individualUserData = await this.userRepository.createIndividualUser({
-                        appUserId,
-                        username: `jwt-user-${appUserId}`,
-                        email: decoded.email || `${appUserId}@jwt.local`,
-                    });
-                } else {
-                    organizationUserData = await this.userRepository.createOrganizationUser({
-                        appOrgId,
-                    });
-                }
-            }
-            
-            return new User(
-                individualUserData,
-                organizationUserData,
-                this.userConfig.usePassword,
-                this.userConfig.primary,
-                this.userConfig.individualUserRequired,
-                this.userConfig.organizationUserRequired
+        let individual = createdIndividual;
+
+        if (individual && organization && !hasOrganization(individual)) {
+            individual = await this.userRepository.linkIndividualToOrganization(
+                individual.id,
+                organization.id
             );
-            
-        } catch (error) {
-            if (error.name === 'TokenExpiredError') {
-                throw Boom.unauthorized('JWT token has expired');
-            } else if (error.name === 'JsonWebTokenError') {
-                throw Boom.unauthorized('Invalid JWT token');
-            } else if (error.isBoom) {
-                throw error;
-            }
-            throw Boom.unauthorized('JWT authentication failed');
         }
-        */
+        return buildUser(cfg, individual, organization);
     }
 }
 
-module.exports = { GetUserFromAdopterJwt };
-
-
+module.exports = { GetUserFromAdopterJwt, assertSingleOrganization };

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

@@ -1,5 +1,9 @@
 const Boom = require('@hapi/boom');
-const { User } = require('../user');
+const {
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+} = require('../app-user-helpers');
 
 /**
  * Use case for retrieving or creating a user from x-frigg header identifiers.
@@ -36,22 +40,11 @@ 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
-                );
-        }
-
-        if (appOrgId && this.userConfig.organizationUserRequired) {
-            organizationUserData =
-                await this.userRepository.findOrganizationUserByAppOrgId(
-                    appOrgId
-                );
-        }
+        let { individual: individualUserData, organization: organizationUserData } =
+            await findAppUsers(this.userRepository, this.userConfig, {
+                appUserId,
+                appOrgId,
+            });
 
         // VALIDATION/AUTO-LINKING: If both IDs provided and both users exist, handle mismatch
         if (
@@ -84,48 +77,33 @@ class GetUserFromXFriggHeaders {
         }
 
         // 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,
-                });
+        const created = await createMissingAppUsers(
+            this.userRepository,
+            this.userConfig,
+            {
+                appUserId,
+                appOrgId,
+                individual: individualUserData,
+                organization: organizationUserData,
+            }
+        );
+        individualUserData = created.individual;
+        organizationUserData = created.organization;
 
-            // Link individual user to newly created org user if individual exists
-            if (individualUserData && organizationUserData) {
-                individualUserData = await this.userRepository.linkIndividualToOrganization(
+        // Link individual user to newly created org user if individual exists
+        if (created.createdOrganization && individualUserData) {
+            individualUserData =
+                await this.userRepository.linkIndividualToOrganization(
                     individualUserData.id,
                     organizationUserData.id
                 );
-            }
         }
 
-        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

@@ -18,6 +18,9 @@ class User {
         this.individualUser = individualUser;
         this.organizationUser = organizationUser;
         this.usePassword = usePassword;
+        // Organization role from an adopter token claim (ADR-056 §2). Read-only
+        // for now: nothing persists it until the membership package lands.
+        this.orgRole = null;
 
         this.config = {
             primary,
@@ -65,6 +68,14 @@ class User {
         return this.config.individualUserRequired;
     }
 
+    getOrgRole() {
+        return this.orgRole;
+    }
+
+    setOrgRole(orgRole) {
+        this.orgRole = orgRole ?? null;
+    }
+
     getIndividualUser() {
         return this.individualUser;
     }