@friggframework/core 2.0.0--canary.680.b3ca7f1.0 → 2.0.0--canary.681.d970b9e.0

package/CHANGELOG.md

@@ -1,14 +1,3 @@
-# Unreleased
-
-#### Behaviour change: module credential fields are now encrypted
-
-- `credentialFields` declared in an API module's `encryption` config (for example `Definition.encryption.credentialFields`) were never registered for encryption: `loadModuleEncryptionSchemas` required a path that does not exist and the error was swallowed. They are now registered, for modules bound by integrations and for modules registered in `appDefinition.entities` (ADR-059).
-- Existing rows are not rewritten. A credential saved before this release stays plaintext until it is next written, and is read as stored.
-- Reads now tolerate plaintext: a value is only treated as ciphertext when it has the exact `keyId:iv:ciphertext:encryptedKey` shape (previously any string with three or more colons, such as `https://user:pw@host:443`), and a value that fails to decrypt is returned as stored with a warning instead of failing the whole read.
-- An app's own `encryption.schema` is no longer replaced when module fields are added to it.
-
----
-
 # v1.2.2 (Fri Aug 09 2024)
 
 #### 🐛 Bug Fix

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,74 @@ 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` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). |
+
+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.
+- **The token's organization is the request's active organization**, and a person can belong to
+  several (ADR-056 §3.6). The first time a person presents a token for an organization they are
+  not a member of, Frigg adds an `OrganizationMembership` and the request runs as that
+  organization (`user.getActiveOrganizationId()`; `user.getId()` under `primary: 'organization'`).
+  Nothing is moved: `IndividualUser.organizationId` is a legacy pointer, set only on a person's
+  first link and read as an implicit membership. The same applies to `x-frigg-apporgid` with
+  `sharedSecret`. With `user.strictMembership: true` those headers cannot add anyone to an organization
+  that already existed (400 for a non-member, a brand-new `appUserId` included); only an organization
+  the request itself creates is allowed. `strictUserValidation` is a deprecated alias with that same
+  meaning. See
+  [Organization memberships](../../docs/guides/organization-memberships.md). A token naming a second
+  organization is no longer a `403` (`multi_org_unsupported` is gone).
+- Two first logins for the same new person or organization, even in different organizations, both
+  succeed: a create that loses to a unique constraint finds the winner's row.
+
 ### 8. Lambda Utilities (`/lambda`)
 
 AWS Lambda-specific utilities and helpers.

package/application/commands/integration-commands.js

@@ -30,9 +30,8 @@ const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
 const {
-    getEntityTypeRegistry,
-    getEntityTypeDefinitions,
-} = require('../../modules/entity-type-registry');
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../../integrations/utils/map-integration-dto');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
@@ -52,16 +51,7 @@ function mapErrorToResponse(error) {
     };
 }
 
-/**
- * @param {Object} [params]
- * @param {Function} [params.integrationClass]
- * @param {Array<object>} [params.moduleDefinitions] - the app's offered module
- *   definitions (`loadAppDefinition().moduleDefinitions`). Integration code
- *   calls this from a constructor with no app definition in hand, so when it
- *   is omitted the commands hydrate with this integration's own modules only
- *   (a registry built from `{ integrations: [integrationClass] }`).
- */
-function createIntegrationCommands({ integrationClass, moduleDefinitions } = {}) {
+function createIntegrationCommands({ integrationClass } = {}) {
     // Always use Frigg's default repositories and use cases
     const integrationRepository = createIntegrationRepository();
 
@@ -118,13 +108,13 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
 
     const moduleRepository = createModuleRepository();
 
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses([
+        integrationClass,
+    ]);
+
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions:
-            moduleDefinitions ??
-            getEntityTypeDefinitions(
-                getEntityTypeRegistry({ integrations: [integrationClass] })
-            ),
+        moduleDefinitions,
     });
 
     const loadIntegrationContextUseCase = new LoadIntegrationContextUseCase({

package/application/commands/user-commands.js

@@ -1,6 +1,12 @@
 const {
     createUserRepository,
 } = require('../../user/repositories/user-repository-factory');
+const {
+    createOrganizationMembershipRepository,
+} = require('../../user/repositories/organization-membership-repository-factory');
+const {
+    FindIndividualUsersByOrganization,
+} = require('../../user/use-cases/find-individual-users-by-organization');
 
 const ERROR_CODE_MAP = {
     USER_NOT_FOUND: 404,
@@ -26,6 +32,12 @@ function mapErrorToResponse(error) {
  */
 function createUserCommands() {
     const userRepository = createUserRepository();
+    const findIndividualUsersByOrganization =
+        new FindIndividualUsersByOrganization({
+            userRepository,
+            organizationMembershipRepository:
+                createOrganizationMembershipRepository(),
+        });
 
     return {
         /**
@@ -170,7 +182,8 @@ function createUserCommands() {
         },
 
         /**
-         * Find all individual users linked to an organization user
+         * Find all individual users who belong to an organization user: those with
+         * a membership and those the legacy organizationId pointer places there.
          * @param {string} organizationUserId - Organization user ID to search for
          * @returns {Promise<Object[]>} Array of individual user objects (empty if none)
          */
@@ -182,10 +195,9 @@ function createUserCommands() {
                     throw error;
                 }
 
-                const users =
-                    await userRepository.findIndividualUsersByOrganizationId(
-                        organizationUserId
-                    );
+                const users = await findIndividualUsersByOrganization.execute(
+                    organizationUserId
+                );
 
                 return (users || []).map((user) => ({
                     id: user._id?.toString() || user.id,

package/application/index.js

@@ -17,7 +17,6 @@ const { createUsageCommands } = require('./commands/usage-commands');
  *
  * @param {Object} params
  * @param {Object} params.integrationClass - Integration class (required)
- * @param {Array<object>} [params.moduleDefinitions] - the app's offered module definitions; defaults to the integration's own modules
  * @returns {Object} Unified commands object with all CRUD operations
  *
  * @example
@@ -25,12 +24,9 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass, moduleDefinitions }) {
+function createFriggCommands({ integrationClass }) {
     // All commands use Frigg's default repositories and use cases
-    const integrationCommands = createIntegrationCommands({
-        integrationClass,
-        moduleDefinitions,
-    });
+    const integrationCommands = createIntegrationCommands({ integrationClass });
 
     const userCommands = createUserCommands();
 

package/database/documentdb-utils.js

@@ -58,7 +58,12 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            throw new Error(`${errorMsg} - Duplicate key violation`);
+            // `code` lets callers recognise a lost race without parsing text
+            // (see database/unique-violation.js).
+            throw Object.assign(
+                new Error(`${errorMsg} - Duplicate key violation`),
+                { code: 11000 }
+            );
         }
         throw new Error(errorMsg);
     }

package/database/encryption/README.md

@@ -428,8 +428,6 @@ Format: "keyId:encryptedText:encryptedKey"
 Example: "base64KeyId:iv:ciphertext:base64EncryptedDataKey"
 ```
 
-**Recognising ciphertext on read.** A value is decrypted only when it has exactly four colon-separated parts: base64 `keyId`, 32-hex-character `iv`, hex ciphertext, base64 `encryptedKey`. Plaintext that merely contains colons (`https://user:pw@host:443`) is left alone. A value with that shape that still fails to decrypt is returned as stored and logged as a warning, so one bad field never fails a whole read. A field that becomes encrypted later (for example a module's `credentialFields`) stays plaintext in existing rows until they are next written.
-
 **Why Envelope Encryption?**
 
 -   Reduces KMS API calls (one DEK per field, cached)

package/database/encryption/encryption-schema-registry.js

@@ -10,11 +10,6 @@
 
 const { logger } = require('./logger');
 const { registerDeniedKeys } = require('../../logs/denied-keys');
-const {
-    getEntityTypeRegistry,
-    getEntityTypeDefinitions,
-    EntityRegistryError,
-} = require('../../modules/entity-type-registry');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -171,9 +166,8 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
  * Each module can declare credentialFields to encrypt in its encryption config.
  *
  * @param {Array} integrations - Array of integration classes with modules
- * @param {object} [entities] - `appDefinition.entities` (ADR-059 registry)
  */
-function loadModuleEncryptionSchemas(integrations, entities) {
+function loadModuleEncryptionSchemas(integrations) {
     if (!integrations) {
         throw new Error('integrations parameter is required');
     }
@@ -182,39 +176,27 @@ function loadModuleEncryptionSchemas(integrations, entities) {
         throw new Error('integrations must be an array');
     }
 
-    // `entities` is the app definition's registry (ADR-059): a module an app
-    // registers without any integration still carries credentials to encrypt.
-    if (integrations.length === 0 && !entities) {
+    if (integrations.length === 0) {
         return;
     }
 
-    const moduleDefinitions = getEntityTypeDefinitions(
-        getEntityTypeRegistry({ integrations, entities })
-    );
+    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
     const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
 
-    // Core fields are encrypted already and a custom schema may not repeat
-    // them. Everything the app registered itself stays: module fields are added
-    // to the custom schema, never substituted for it (other models included).
-    const coreFields = new Set(CORE_ENCRYPTION_SCHEMA.Credential?.fields || []);
-    const fields = [
-        ...new Set([
-            ...(customSchema.Credential?.fields || []),
-            ...credentialFields.filter((field) => !coreFields.has(field)),
-        ]),
-    ];
-
-    if (fields.length === 0) {
+    if (credentialFields.length === 0) {
         return;
     }
 
     const moduleSchema = {
-        ...customSchema,
-        Credential: { ...customSchema.Credential, fields },
+        Credential: {
+            fields: credentialFields
+        }
     };
 
     logger.info(
-        `Registering module-level encryption for ${fields.length} credential fields`
+        `Registering module-level encryption for ${credentialFields.length} credential fields`
     );
 
     registerCustomSchema(moduleSchema);
@@ -266,15 +248,10 @@ function loadCustomEncryptionSchema() {
 
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
-        if (Array.isArray(integrations) || appDefinition.entities) {
-            loadModuleEncryptionSchemas(
-                Array.isArray(integrations) ? integrations : [],
-                appDefinition.entities
-            );
+        if (integrations && Array.isArray(integrations)) {
+            loadModuleEncryptionSchemas(integrations);
         }
     } catch (error) {
-        // A bad entity registry is a configuration error, not "no custom schema".
-        if (error instanceof EntityRegistryError) throw error;
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
         // - Backend package.json not found (tests, standalone usage)

package/database/encryption/field-encryption-service.js

@@ -4,16 +4,6 @@
  * Infrastructure layer service that orchestrates field-level encryption/decryption.
  * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
  */
-const { logger } = require('./logger');
-
-// Cryptor.encrypt() returns `${keyId}:${iv}:${ciphertext}:${encryptedKey}`:
-// keyId and encryptedKey are base64, iv is 16 bytes of hex, ciphertext is hex.
-// Plaintext with three colons (`https://user:pw@host:443`, `a:b:c:d`) must not
-// be mistaken for it.
-const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
-const IV_PART = /^[0-9a-f]{32}$/i;
-const CIPHERTEXT_PART = /^(?:[0-9a-f]{2})+$/i;
-
 class FieldEncryptionService {
     constructor({ cryptor, schema }) {
         if (!cryptor) {
@@ -107,23 +97,12 @@ class FieldEncryptionService {
         const decryptionPromises = fields.map(async (fieldPath) => {
             const value = this._getNestedValue(decrypted, fieldPath);
 
-            if (!this._isEncrypted(value)) {
-                return null;
-            }
-            try {
+            if (this._isEncrypted(value)) {
                 const decryptedValue = await this.cryptor.decrypt(value);
                 const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
                 return { fieldPath, decryptedValue: deserializedValue };
-            } catch (error) {
-                // A value that looks like ciphertext but is not (or was written
-                // before the field was encrypted) is read as it is stored. One
-                // such field must not fail the whole read, findMany included.
-                logger.warn(
-                    `Could not decrypt ${modelName}.${fieldPath}; returning the stored value`,
-                    { errorName: error?.name }
-                );
-                return null;
             }
+            return null;
         });
 
         const results = await Promise.all(decryptionPromises);
@@ -173,13 +152,7 @@ class FieldEncryptionService {
         }
 
         const parts = value.split(':');
-        return (
-            parts.length === 4 &&
-            BASE64_PART.test(parts[0]) &&
-            IV_PART.test(parts[1]) &&
-            CIPHERTEXT_PART.test(parts[2]) &&
-            BASE64_PART.test(parts[3])
-        );
+        return parts.length >= 4;
     }
 
     _getNestedValue(obj, path) {

package/database/unique-violation.js

@@ -0,0 +1,25 @@
+/** Mongo/DocumentDB duplicate-key error code. */
+const DUPLICATE_KEY_CODE = 11000;
+/** Prisma's unique-constraint error code (PostgreSQL and MongoDB). */
+const PRISMA_UNIQUE_CODE = 'P2002';
+
+/**
+ * Whether `error` is a unique-constraint violation, however the database
+ * layer raised it: a Prisma `P2002`, or a duplicate-key `11000`
+ * (`documentdb-utils` `insertOne` sets `code` on the error it throws).
+ * Matches on the code only, never on message text.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isUniqueViolation(error) {
+    return (
+        error?.code === PRISMA_UNIQUE_CODE || error?.code === DUPLICATE_KEY_CODE
+    );
+}
+
+module.exports = {
+    isUniqueViolation,
+    DUPLICATE_KEY_CODE,
+    PRISMA_UNIQUE_CODE,
+};