@friggframework/core 2.0.0--canary.682.3c8b68a.0 → 2.0.0--canary.685.022c3c3.0

package/types/modules/index.d.ts

@@ -68,12 +68,49 @@ declare module "@friggframework/core" {
     owner?: "derive" | "individual" | "organization";
   }
 
+  /** One operation a module or the app lets the entity proxy forward (ADR-052). */
+  export interface ProxyAllowRule {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "*";
+    /** Relative to the module's base URL. `:param` is one segment; a trailing `/**` is a subtree. */
+    path: string;
+  }
+
+  /** `appDefinition.managementApi.proxy`: the entity proxy, POST /api/v2/entities/:id/proxy (ADR-052). */
+  export interface ManagementApiProxyConfig {
+    /** Mount the route. Default false. */
+    enable?: boolean;
+    /** Upstream timeout in ms; can only be lowered from 25000. */
+    timeoutMs?: number;
+    /** Largest request body in bytes; default 1 MiB, at most 10 MiB. */
+    maxRequestBytes?: number;
+    /** Largest response body in bytes; can only be lowered from 5 MiB. */
+    maxResponseBytes?: number;
+    /**
+     * Entity scopes the proxy accepts (ADR-056 §3.5). Default `['individual']`.
+     * Add `'organization'` to let a member with use access proxy through the
+     * organization's shared credential. `global` is never accepted. An unknown,
+     * empty or repeated value throws ManagementApiConfigError at load.
+     */
+    scopes?: Array<Exclude<EntityScope, "global">>;
+    /** Per-module allow-list override; `'module'` uses the module's own list. */
+    modules?: Record<string, { allow: "module" | ProxyAllowRule[] }>;
+  }
+
+  /** `appDefinition.managementApi` (ADR-052, ADR-053). */
+  export interface ManagementApiConfig {
+    /** Serve the deprecated v1 routes. Default true. */
+    v1?: boolean;
+    proxy?: ManagementApiProxyConfig;
+  }
+
   export interface AppDefinition {
     integrations: any[];
     /** App-level entity type registry (ADR-059). */
     entities?: AppDefinitionEntities;
     /** Who owns what a person connects (ADR-056). */
     ownership?: AppOwnership;
+    /** Management API versions and the entity proxy (ADR-052, ADR-053, ADR-056 §3.5). */
+    managementApi?: ManagementApiConfig;
     [key: string]: unknown;
   }
 
@@ -138,6 +175,11 @@ declare module "@friggframework/core" {
     appDefinition?: Pick<AppDefinition, "entities" | "integrations">
   ): EntityTypeRegistry;
 
+  /** Invalid `managementApi` setting (today: `proxy.scopes`), thrown at app-definition load. */
+  export class ManagementApiConfigError extends Error {
+    code: "MANAGEMENT_API_CONFIG_INVALID";
+  }
+
   /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
   export class EntityRegistryError extends Error {
     code: "ENTITY_REGISTRY_INVALID";

package/types/user/index.d.ts

@@ -62,6 +62,13 @@ declare module "@friggframework/core/user" {
      * at startup. `strictMembership` wins when both are set.
      */
     strictUserValidation?: boolean;
+    /**
+     * Roles (the adopter token's role claim) that may manage organization-level
+     * things (ADR-056 §3). Default `['ADMIN']`; a token with no role claim is
+     * `MEMBER`, never admin; a shared-secret (`x-frigg` header) caller needs no
+     * role. Compared case-insensitively. Validated at load.
+     */
+    orgAdminRoles?: string[];
     authModes?: UserAuthModes;
     jwtConfig?: AdopterJwtConfig;
   }

package/user/use-cases/authenticate-user.js

@@ -1,5 +1,6 @@
 const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
+const { AUTH_SOURCES } = require('../user');
 
 const log = getLogger('frigg.user.authentication');
 
@@ -68,10 +69,13 @@ class AuthenticateUser {
                 // Validate the API key (authentication)
                 await this.authenticateWithSharedSecret.execute(apiKey);
                 // Get user from x-frigg headers (authorization)
-                return await this.getUserFromXFriggHeaders.execute(
+                const user = await this.getUserFromXFriggHeaders.execute(
                     appUserId,
                     appOrgId
                 );
+                // The app's own backend: trusted to manage organization things.
+                user.setAuthSource(AUTH_SOURCES.SHARED_SECRET);
+                return user;
             }
             log.debug('No x-frigg-api-key header, skipping shared secret', {
                 eventName: `${log.name}.shared_secret_skipped`,
@@ -90,6 +94,7 @@ class AuthenticateUser {
             // Detect JWT format (3 parts separated by dots)
             if (token && token.split('.').length === 3) {
                 const user = await this.getUserFromAdopterJwt.execute(token);
+                user.setAuthSource(AUTH_SOURCES.ADOPTER_JWT);
                 // Validate x-frigg headers match JWT claims if present
                 if (appUserId || appOrgId) {
                     this.validateUserMatch(user, appUserId, appOrgId);
@@ -106,6 +111,7 @@ class AuthenticateUser {
             const user = await this.getUserFromBearerToken.execute(
                 req.headers.authorization
             );
+            user.setAuthSource(AUTH_SOURCES.BEARER_TOKEN);
             // Validate x-frigg headers match token user if present
             if (appUserId || appOrgId) {
                 this.validateUserMatch(user, appUserId, appOrgId);

package/user/user.js

@@ -1,5 +1,18 @@
 const bcrypt = require('bcryptjs');
 
+/**
+ * How the request that produced a `User` proved who it is. Set by
+ * AuthenticateUser, never inferred from a missing value. Organization roles
+ * (ADR-056 §3, §3.6) depend on it: a shared-secret caller is the app's own
+ * backend and is trusted to manage; a person with a token has the role the
+ * token carries, or `MEMBER`.
+ */
+const AUTH_SOURCES = Object.freeze({
+    SHARED_SECRET: 'shared-secret',
+    ADOPTER_JWT: 'adopter-jwt',
+    BEARER_TOKEN: 'bearer-token',
+});
+
 /**
  * Represents a user in the system. The User class is a domain entity,
  * @class User
@@ -21,6 +34,8 @@ class User {
         // Organization role from an adopter token claim (ADR-056 §2). Per request:
         // the role stored on a membership is only what the first token carried.
         this.orgRole = null;
+        // How this request authenticated (one of AUTH_SOURCES); null until AuthenticateUser says.
+        this.authSource = null;
 
         this.config = {
             primary,
@@ -84,6 +99,14 @@ class User {
         return this.config.individualUserRequired;
     }
 
+    getAuthSource() {
+        return this.authSource;
+    }
+
+    setAuthSource(authSource) {
+        this.authSource = authSource ?? null;
+    }
+
     getOrgRole() {
         return this.orgRole;
     }
@@ -149,4 +172,4 @@ class User {
     }
 }
 
-module.exports = { User }; 
+module.exports = { User, AUTH_SOURCES };