@friggframework/core 2.0.0--canary.670.2873d95.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/credential/repositories/credential-repository-documentdb.js

@@ -186,6 +186,40 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
         return this._mapCredential(decryptedCredential);
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        const userObjectId = toObjectId(userId);
+        if (!userObjectId) return [];
+        const docs = await findManyDrained(
+            this.prisma,
+            'Credential',
+            { userId: userObjectId },
+            { sort: { createdAt: -1 } }
+        );
+        const credentials = [];
+        for (const doc of docs) {
+            const decrypted = await this.encryptionService.decryptFields(
+                'Credential',
+                doc
+            );
+            credentials.push({
+                ...this._mapCredential(decrypted),
+                id: fromObjectId(doc._id),
+                userId: fromObjectId(doc.userId) ?? doc.userId,
+                externalId: doc.externalId ?? null,
+                authIsValid: doc.authIsValid ?? null,
+                createdAt: doc.createdAt ?? null,
+                updatedAt: doc.updatedAt ?? null,
+            });
+        }
+        return credentials;
+    }
+
     async updateCredential(credentialId, updates) {
         const objectId = toObjectId(credentialId);
         if (!objectId) return null;

package/credential/repositories/credential-repository-interface.js

@@ -80,6 +80,21 @@ class CredentialRepositoryInterface {
         );
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string|number} userId - User ID (string from application layer)
+     * @returns {Promise<Array<Object>>} Credentials with string IDs, `createdAt`
+     *   and `updatedAt`, and the (decrypted) data fields spread in, as
+     *   findCredentialById returns them. Empty when the user has none.
+     * @abstract
+     */
+    async findCredentialsByUserId(userId) {
+        throw new Error(
+            'Method findCredentialsByUserId must be implemented by subclass'
+        );
+    }
+
     /**
      * Update a credential by ID
      *

package/credential/repositories/credential-repository-mongo.js

@@ -188,6 +188,29 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
         };
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        if (!userId) return [];
+        const credentials = await this.prisma.credential.findMany({
+            where: { userId: String(userId) },
+            orderBy: { createdAt: 'desc' },
+        });
+        return credentials.map((credential) => ({
+            ...(credential.data || {}),
+            id: credential.id,
+            userId: credential.userId,
+            externalId: credential.externalId,
+            authIsValid: credential.authIsValid,
+            createdAt: credential.createdAt,
+            updatedAt: credential.updatedAt,
+        }));
+    }
+
     /**
      * Update a credential by ID
      * Replaces: Credential.findByIdAndUpdate(credentialId, { $set: updates })

package/credential/repositories/credential-repository-postgres.js

@@ -205,6 +205,34 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         };
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID (string from application layer)
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        let intUserId;
+        try {
+            intUserId = this._convertId(userId);
+        } catch {
+            return [];
+        }
+        const credentials = await this.prisma.credential.findMany({
+            where: { userId: intUserId },
+            orderBy: { createdAt: 'desc' },
+        });
+        return credentials.map((credential) => ({
+            ...(credential.data || {}),
+            id: credential.id.toString(),
+            userId: credential.userId?.toString(),
+            externalId: credential.externalId,
+            authIsValid: credential.authIsValid,
+            createdAt: credential.createdAt,
+            updatedAt: credential.updatedAt,
+        }));
+    }
+
     /**
      * Update a credential by ID
      *

package/credential/use-cases/credential-operations-for-user.js

@@ -0,0 +1,117 @@
+const Boom = require('@hapi/boom');
+const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+
+/**
+ * Management API v2 credential operations. A credential has no module name
+ * of its own; its `type` and the entities that use it come from the
+ * caller's entities. A missing or foreign credential is a 404.
+ */
+
+const credentialIdOf = (entity) => {
+    const ref = entity.credential ?? entity.credentialId;
+    if (ref === undefined || ref === null) return null;
+    if (typeof ref === 'object') {
+        const id = ref.id ?? ref._id;
+        return id === undefined || id === null ? null : String(id);
+    }
+    return String(ref);
+};
+
+/** Adds `type` and `entityIds` from the user's entities to each credential. */
+function withEntityUsage(credentials, entities) {
+    const usage = new Map();
+    for (const entity of entities || []) {
+        const credentialId = credentialIdOf(entity);
+        if (!credentialId) continue;
+        const entry = usage.get(credentialId) || { type: null, entityIds: [] };
+        entry.type = entry.type || entity.moduleName || null;
+        entry.entityIds.push(String(entity.id));
+        usage.set(credentialId, entry);
+    }
+    return credentials.map((credential) => {
+        const entry = usage.get(String(credential.id)) || {
+            type: null,
+            entityIds: [],
+        };
+        return { ...credential, type: entry.type, entityIds: entry.entityIds };
+    });
+}
+
+/** The caller's credentials with their type and entity usage. */
+class ListCredentialsForUser {
+    constructor({ credentialRepository, moduleRepository }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute(user) {
+        const userId = user.getId();
+        const [credentials, entities] = await Promise.all([
+            this.credentialRepository.findCredentialsByUserId(userId),
+            this.moduleRepository.findEntitiesByUserId(userId),
+        ]);
+        return withEntityUsage(credentials || [], entities);
+    }
+}
+
+/** One credential the caller owns, with its type and entity usage. */
+class GetCredentialForUserV2 {
+    constructor({ credentialRepository, moduleRepository }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute(credentialId, user) {
+        let credential = null;
+        try {
+            credential = await this.credentialRepository.findCredentialById(
+                credentialId
+            );
+        } catch (error) {
+            if (!/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+                throw error;
+            }
+        }
+        if (!credential || !userOwns(user, credential.userId)) {
+            throw Boom.notFound(`Credential ${credentialId} not found`, {
+                code: 'CREDENTIAL_NOT_FOUND',
+            });
+        }
+        const entities = await this.moduleRepository.findEntitiesByUserId(
+            credential.userId
+        );
+        return withEntityUsage([credential], entities)[0];
+    }
+}
+
+/**
+ * Deletes a credential the caller owns. The entities that used it stay, with
+ * their credential unset, so they show as needing re-authorization rather
+ * than disappearing from integrations.
+ */
+class DeleteCredentialForUser {
+    constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+        this.getCredentialForUser = getCredentialForUser;
+    }
+
+    async execute(credentialId, user) {
+        const credential = await this.getCredentialForUser.execute(
+            credentialId,
+            user
+        );
+        for (const entityId of credential.entityIds) {
+            await this.moduleRepository.unsetCredential(entityId);
+        }
+        await this.credentialRepository.deleteCredentialById(credential.id);
+        return { id: String(credential.id), entityIds: credential.entityIds };
+    }
+}
+
+module.exports = {
+    ListCredentialsForUser,
+    GetCredentialForUserV2,
+    DeleteCredentialForUser,
+    withEntityUsage,
+};

package/credential/use-cases/reauthorize-credential-for-user.js

@@ -0,0 +1,66 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * Re-authorization of a credential the caller owns (Management API v2). It
+ * runs the same flow as /api/v2/authorize for the credential's entity type,
+ * with the session bound to the credential so it cannot be reused for
+ * anything else.
+ */
+async function credentialEntityType(getCredentialForUser, credentialId, user) {
+    const credential = await getCredentialForUser.execute(credentialId, user);
+    if (!credential.type) {
+        throw Boom.conflict(
+            `Credential ${credentialId} is not used by any entity, so its type is unknown; authorize a new connection instead`,
+            { code: 'CREDENTIAL_TYPE_UNKNOWN' }
+        );
+    }
+    return { entityType: credential.type, credentialId: String(credential.id) };
+}
+
+/** GET /api/v2/credentials/:credentialId/reauthorize */
+class GetCredentialReauthorization {
+    constructor({ getCredentialForUser, getAuthorizationStep }) {
+        this.getCredentialForUser = getCredentialForUser;
+        this.getAuthorizationStep = getAuthorizationStep;
+    }
+
+    async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
+        const binding = await credentialEntityType(
+            this.getCredentialForUser,
+            credentialId,
+            user
+        );
+        return this.getAuthorizationStep.execute({
+            user,
+            ...binding,
+            step,
+            sessionId,
+            state,
+        });
+    }
+}
+
+/** POST /api/v2/credentials/:credentialId/reauthorize */
+class ReauthorizeCredentialForUser {
+    constructor({ getCredentialForUser, submitAuthorizationStep }) {
+        this.getCredentialForUser = getCredentialForUser;
+        this.submitAuthorizationStep = submitAuthorizationStep;
+    }
+
+    async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
+        const binding = await credentialEntityType(
+            this.getCredentialForUser,
+            credentialId,
+            user
+        );
+        return this.submitAuthorizationStep.execute({
+            user,
+            ...binding,
+            data,
+            step,
+            sessionId,
+        });
+    }
+}
+
+module.exports = { GetCredentialReauthorization, ReauthorizeCredentialForUser };

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

@@ -39,6 +39,12 @@ const CORE_ENCRYPTION_SCHEMA = {
     Token: {
         fields: ['token'],
     },
+
+    // Multi-step authorization (Management API v2): earlier steps can collect
+    // emails, usernames or one-time codes.
+    AuthorizationSession: {
+        fields: ['stepData'],
+    },
 };
 
 let customSchema = {};