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

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.678.58db4b2.0",
+    "version": "2.0.0--canary.680.b3ca7f1.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -28,7 +28,6 @@
         "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",
@@ -48,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@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",
+        "@friggframework/eslint-config": "2.0.0--canary.680.b3ca7f1.0",
+        "@friggframework/prettier-config": "2.0.0--canary.680.b3ca7f1.0",
+        "@friggframework/test": "2.0.0--canary.680.b3ca7f1.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "58db4b2bc17529f46b8dae1110771f5df39033ed"
+    "gitHead": "b3ca7f1295d79b4d0cb5fb9fb4ec41093033ba4d"
 }

package/types/index.d.ts

@@ -12,4 +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" />
+/// <reference path="./modules/index.d.ts" />

package/types/modules/index.d.ts

@@ -0,0 +1,58 @@
+declare module "@friggframework/core" {
+  /** Where an entity type comes from: the app's `entities` map or an integration binding it. */
+  export type EntityTypeSource =
+    | { kind: "app" }
+    | { kind: "integration"; name: string };
+
+  export type EntityScope = "individual" | "organization" | "global";
+
+  /** App-level settings carried from the `entities` entry; empty for an inferred-only type. */
+  export interface EntityTypeSettings {
+    scope?: EntityScope | { default?: EntityScope; allow?: EntityScope[] };
+    proxy?: Record<string, unknown>;
+    display?: Record<string, unknown>;
+  }
+
+  export interface EntityTypeEntry {
+    /** The API module definition. */
+    definition: any;
+    /** Frozen. `{ kind: 'app' }` first when registered, then each binding integration. */
+    sources: readonly EntityTypeSource[];
+    /** Frozen. */
+    settings: Readonly<EntityTypeSettings>;
+  }
+
+  /** Entity type name (the definition's moduleName) to its entry. */
+  export type EntityTypeRegistry = Map<string, EntityTypeEntry>;
+
+  /** One `appDefinition.entities` entry. The key must equal the definition's moduleName (and getName() when defined). */
+  export interface EntityRegistration extends EntityTypeSettings {
+    definition: any;
+  }
+
+  export interface AppDefinitionEntities {
+    /** false turns inference off: every module an integration binds must be registered. Default true. */
+    $infer?: boolean;
+    [entityType: string]: EntityRegistration | boolean | undefined;
+  }
+
+  export interface AppDefinition {
+    integrations: any[];
+    /** App-level entity type registry (ADR-059). */
+    entities?: AppDefinitionEntities;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Builds the registry from `entities` plus the modules integrations bind.
+   * Throws EntityRegistryError on an invalid registry.
+   */
+  export function getEntityTypeRegistry(
+    appDefinition?: Pick<AppDefinition, "entities" | "integrations">
+  ): EntityTypeRegistry;
+
+  /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
+  export class EntityRegistryError extends Error {
+    code: "ENTITY_REGISTRY_INVALID";
+  }
+}

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

@@ -1,136 +1,149 @@
-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 !== '';
-};
+const Boom = require('@hapi/boom');
 
 /**
- * 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.
+ * STUB: Use case for retrieving a user from adopter-provided JWT token.
  *
- * @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.
+ * 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
+ *
+ * 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
  *
- * 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.
+ * @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
  *
  * @class GetUserFromAdopterJwt
  */
 class GetUserFromAdopterJwt {
     /**
-     * @param {Object} params
-     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository
+     * 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.userConfig - The user config in the app definition.
-     * @param {{verify: Function, claimNames: Object}} params.tokenVerifier -
-     *   from `createAdopterTokenVerifier`.
      */
-    constructor({ userRepository, userConfig, tokenVerifier }) {
+    constructor({ userRepository, userConfig }) {
         this.userRepository = userRepository;
         this.userConfig = userConfig;
-        this.tokenVerifier = tokenVerifier;
     }
 
     /**
+     * Executes the use case.
      * @async
-     * @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).
+     * @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.
      */
-    async execute(token) {
-        const claims = await this.tokenVerifier.verify(token);
-        const { userIdClaim, orgIdClaim, roleClaim } =
-            this.tokenVerifier.claimNames;
+    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).'
+        );
 
-        const appUserId = idFromClaim(claims[userIdClaim]);
-        if (!appUserId) throw fail('token_missing_user_claim');
+        /* FUTURE IMPLEMENTATION PSEUDOCODE:
 
-        const rawOrgId = claims[orgIdClaim];
-        const appOrgId = idFromClaim(rawOrgId);
-        if (rawOrgId !== undefined && rawOrgId !== null && !appOrgId) {
-            throw fail('token_malformed');
+        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 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,
+        
+        try {
+            // Verify and decode JWT
+            const decoded = jwt.verify(jwtToken, this.userConfig.jwtConfig.secret, {
+                algorithms: [this.userConfig.jwtConfig.algorithm || 'HS256']
             });
-        let individual = createdIndividual;
-
-        if (individual && organization && !hasOrganization(individual)) {
-            individual = await this.userRepository.linkIndividualToOrganization(
-                individual.id,
-                organization.id
+            
+            // 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
             );
+            
+        } 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, assertSingleOrganization };
+module.exports = { GetUserFromAdopterJwt };
+
+

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

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

package/user/user.js

@@ -18,9 +18,6 @@ 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,
@@ -68,14 +65,6 @@ class User {
         return this.config.individualUserRequired;
     }
 
-    getOrgRole() {
-        return this.orgRole;
-    }
-
-    setOrgRole(orgRole) {
-        this.orgRole = orgRole ?? null;
-    }
-
     getIndividualUser() {
         return this.individualUser;
     }

package/types/user/index.d.ts

@@ -1,67 +0,0 @@
-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;
-  }
-}