@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.680.daae24e.0

package/modules/use-cases/multi-step-authorization.js

@@ -0,0 +1,302 @@
+const Boom = require('@hapi/boom');
+const { FetchError } = require('../../errors/fetch-error');
+const { getLogger } = require('../../logs');
+const { AuthorizationSession } = require('../domain/authorization-session');
+const { findDefinition, getAuthStepCount } = require('./entity-types');
+
+const log = getLogger('frigg.api.authorize');
+
+const defaultCreateModule = (params) => {
+    const { Module } = require('../module');
+    return new Module(params);
+};
+
+const isMultiStep = (definition) =>
+    getAuthStepCount(definition) > 1 ||
+    typeof definition.processAuthorizationStep === 'function';
+
+const sessionNotFound = () =>
+    Boom.notFound('Authorization session not found or expired', {
+        code: 'AUTHORIZATION_SESSION_NOT_FOUND',
+    });
+
+/**
+ * Maps a failure from the module or the provider to a client-facing error.
+ * Boom errors pass through. A provider HTTP failure is a 502; a failed auth
+ * test or a ClientSafeError is a 400. Anything else stays a 500.
+ */
+function toAuthorizationError(error, { passMessage = false } = {}) {
+    if (error?.isBoom) return error;
+    if (error instanceof FetchError) {
+        return Boom.badGateway('The provider rejected the authorization request', {
+            code: 'UPSTREAM_ERROR',
+            expose: true,
+            details: { upstreamStatus: error.statusCode ?? null },
+        });
+    }
+    if (error?.isClientSafe || passMessage) {
+        return Boom.badRequest(error?.message || 'Authorization failed', {
+            code: 'AUTHORIZATION_FAILED',
+        });
+    }
+    if (error?.message === 'Authorization failed') {
+        return Boom.badRequest(
+            'Authorization failed: the credentials did not pass the module auth test',
+            { code: 'AUTHORIZATION_FAILED' }
+        );
+    }
+    return error;
+}
+
+/**
+ * Loads the session a caller continues, checking it belongs to them, to the
+ * entity type and (for re-authorization) to the credential.
+ */
+async function loadSession(repository, sessionId, binding) {
+    if (typeof sessionId !== 'string' || !sessionId) throw sessionNotFound();
+    const session = await repository.findBySessionId(sessionId);
+    if (!session || session.isExpired() || !session.belongsTo(binding)) {
+        throw sessionNotFound();
+    }
+    if (session.completed) {
+        throw Boom.conflict('Authorization session is already complete', {
+            code: 'AUTHORIZATION_SESSION_COMPLETED',
+        });
+    }
+    return session;
+}
+
+async function startSession(repository, binding, maxSteps) {
+    // Expired sessions are removed opportunistically; PostgreSQL has no TTL.
+    Promise.resolve()
+        .then(() => repository.deleteExpired())
+        .catch((error) =>
+        log.warn('Expired authorization sessions were not removed', {
+            eventName: `${log.name}.session_cleanup_failed`,
+            error,
+        })
+    );
+    return repository.create(AuthorizationSession.start({ ...binding, maxSteps }));
+}
+
+/**
+ * GET /api/v2/authorize (and GET /api/v2/credentials/:id/reauthorize): what
+ * the caller must submit next. A multi-step flow gets a session on step 1;
+ * later steps need that sessionId and must be the session's current step.
+ */
+class GetAuthorizationStep {
+    /**
+     * @param {Object} params
+     * @param {Array<Object>} params.moduleDefinitions
+     * @param {import('./get-authorization-requirements').GetAuthorizationRequirements} params.getAuthorizationRequirements
+     * @param {import('../repositories/authorization-session-repository-interface').AuthorizationSessionRepositoryInterface} params.authorizationSessionRepository
+     */
+    constructor({ moduleDefinitions, getAuthorizationRequirements, authorizationSessionRepository }) {
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.getAuthorizationRequirements = getAuthorizationRequirements;
+        this.sessions = authorizationSessionRepository;
+    }
+
+    async execute({ user, entityType, step = 1, sessionId, credentialId = null, state }) {
+        const definition = findDefinition(this.moduleDefinitions, entityType);
+        const userId = user.getId();
+        const requirementsFor = (n) =>
+            this.getAuthorizationRequirements.execute({ entityType, step: n, userId, state });
+
+        if (!isMultiStep(definition)) return requirementsFor(step);
+
+        const binding = { userId, entityType, credentialId };
+        let session;
+        if (sessionId) {
+            session = await loadSession(this.sessions, sessionId, binding);
+            if (step !== session.currentStep) {
+                throw Boom.conflict(
+                    `This session expects step ${session.currentStep}`,
+                    { code: 'STEP_OUT_OF_ORDER', details: { expectedStep: session.currentStep } }
+                );
+            }
+        } else {
+            if (step !== 1) {
+                throw Boom.badRequest('sessionId is required after step 1', {
+                    code: 'SESSION_REQUIRED',
+                });
+            }
+            session = await startSession(this.sessions, binding, getAuthStepCount(definition));
+        }
+        return { ...(await requirementsFor(step)), sessionId: session.sessionId };
+    }
+}
+
+/**
+ * POST /api/v2/authorize (and POST /api/v2/credentials/:id/reauthorize).
+ *
+ * Single-step modules complete at once through ProcessAuthorizationCallback
+ * (the v1 authorize logic). Multi-step modules run
+ * definition.processAuthorizationStep(api, step, data, stepData) per step;
+ * when it reports `completed`, its `authData` goes through the same
+ * callback. Returns either
+ * `{ status: 'complete', entity, credential }` (domain records; the handler
+ * masks them) or
+ * `{ status: 'pending', step, totalSteps, sessionId, requirements, message? }`.
+ */
+class SubmitAuthorizationStep {
+    constructor({
+        moduleDefinitions,
+        getAuthorizationRequirements,
+        authorizationSessionRepository,
+        processAuthorizationCallback,
+        moduleRepository,
+        credentialRepository,
+        createModule,
+    }) {
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.getAuthorizationRequirements = getAuthorizationRequirements;
+        this.sessions = authorizationSessionRepository;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.moduleRepository = moduleRepository;
+        this.credentialRepository = credentialRepository;
+        this.createModule = createModule || defaultCreateModule;
+    }
+
+    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null }) {
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            throw Boom.badRequest('data must be an object', {
+                code: 'VALIDATION_ERROR',
+                details: { field: 'data' },
+            });
+        }
+        const definition = findDefinition(this.moduleDefinitions, entityType);
+        const userId = user.getId();
+
+        if (!isMultiStep(definition)) {
+            if (step !== 1) {
+                throw Boom.badRequest(`${entityType} has a single authorization step`, {
+                    code: 'INVALID_STEP',
+                });
+            }
+            return this.complete({ userId, entityType, params: data, credentialId });
+        }
+
+        const totalSteps = getAuthStepCount(definition);
+        const binding = { userId, entityType, credentialId };
+        let session;
+        if (sessionId) {
+            session = await loadSession(this.sessions, sessionId, binding);
+            if (step === 1 && session.currentStep !== 1) {
+                session.restart();
+            } else if (step !== session.currentStep) {
+                throw Boom.conflict(`This session expects step ${session.currentStep}`, {
+                    code: 'STEP_OUT_OF_ORDER',
+                    details: { expectedStep: session.currentStep },
+                });
+            }
+        } else {
+            if (step !== 1) {
+                throw Boom.badRequest('sessionId is required after step 1', {
+                    code: 'SESSION_REQUIRED',
+                });
+            }
+            session = await startSession(this.sessions, binding, totalSteps);
+        }
+
+        if (typeof definition.processAuthorizationStep !== 'function') {
+            throw Boom.badImplementation(
+                `Module ${entityType} declares ${totalSteps} steps but no processAuthorizationStep`
+            );
+        }
+
+        const module = this.createModule({ userId, definition });
+        let result;
+        try {
+            result = await definition.processAuthorizationStep(
+                module.api,
+                step,
+                data,
+                session.stepData
+            );
+        } catch (error) {
+            // processAuthorizationStep errors are written for the end user
+            // (docs/MULTI_STEP_AUTH_MIGRATION_GUIDE.md), e.g. "Invalid code".
+            throw toAuthorizationError(error, { passMessage: true });
+        }
+
+        if (result?.completed) {
+            session.markComplete();
+            await this.sessions.update(session);
+            const outcome = await this.complete({
+                userId,
+                entityType,
+                params: result.authData || {},
+                credentialId,
+            });
+            // The collected data is no longer needed once the credential exists.
+            await Promise.resolve()
+                .then(() => this.sessions.deleteBySessionId(session.sessionId))
+                .catch(() => {});
+            return outcome;
+        }
+
+        const nextStep = result?.nextStep ?? step + 1;
+        try {
+            session.advanceTo(nextStep, result?.stepData);
+        } catch (error) {
+            throw Boom.badImplementation(
+                `Module ${entityType} returned an invalid next step: ${error.message}`
+            );
+        }
+        await this.sessions.update(session);
+
+        const requirements = await this.getAuthorizationRequirements.execute({
+            entityType,
+            step: nextStep,
+            userId,
+        });
+        return {
+            status: 'pending',
+            step: nextStep,
+            totalSteps,
+            sessionId: session.sessionId,
+            requirements,
+            ...(result?.message && { message: String(result.message) }),
+        };
+    }
+
+    async complete({ userId, entityType, params, credentialId }) {
+        let callback;
+        try {
+            callback = await this.processAuthorizationCallback.execute(
+                userId,
+                entityType,
+                params
+            );
+        } catch (error) {
+            throw toAuthorizationError(error);
+        }
+        const [entity, credential] = await Promise.all([
+            this.moduleRepository.findEntityById(callback.entity_id),
+            this.credentialRepository.findCredentialById(callback.credential_id),
+        ]);
+        const outcome = {
+            status: 'complete',
+            entity,
+            credential: credential && {
+                ...credential,
+                type: entityType,
+                entityIds: entity ? [String(entity.id)] : [],
+            },
+        };
+        if (credentialId && String(callback.credential_id) !== String(credentialId)) {
+            // The provider account differs from the one being re-authorized,
+            // so a separate credential was stored.
+            outcome.previousCredentialId = String(credentialId);
+        }
+        return outcome;
+    }
+}
+
+module.exports = {
+    GetAuthorizationStep,
+    SubmitAuthorizationStep,
+    toAuthorizationError,
+    isMultiStep,
+};

package/modules/utils/map-module-dto.js

@@ -1,5 +1,3 @@
-const { toCredentialId } = require('./to-credential-id');
-
 /**
  * @param {import('../module').Module} moduleInstance
  * Convert a Module domain instance to a plain DTO suitable for JSON responses.
@@ -12,9 +10,9 @@ function mapModuleClassToModuleDTO(moduleInstance) {
         name: moduleInstance.name,
         userId: moduleInstance.userId,
         entity: moduleInstance.entity,
-        credentialId: toCredentialId(moduleInstance.credential),
-        type: moduleInstance.getName(),
+        credentialId: moduleInstance.credential?._id?.toString(),
+        type: moduleInstance.getName()
     };
 }
 
-module.exports = { mapModuleClassToModuleDTO };
+module.exports = { mapModuleClassToModuleDTO }; 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.704.79d9a63.0",
+    "version": "2.0.0--canary.680.daae24e.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.704.79d9a63.0",
-        "@friggframework/prettier-config": "2.0.0--canary.704.79d9a63.0",
-        "@friggframework/test": "2.0.0--canary.704.79d9a63.0",
+        "@friggframework/eslint-config": "2.0.0--canary.680.daae24e.0",
+        "@friggframework/prettier-config": "2.0.0--canary.680.daae24e.0",
+        "@friggframework/test": "2.0.0--canary.680.daae24e.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "79d9a635432643710e9fb815cf16453d01f7e12c"
+    "gitHead": "daae24ec9d6b03c59759b6b42f6f99369b683981"
 }

package/prisma-mongodb/schema.prisma

@@ -453,3 +453,30 @@ model UsageCounter {
   @@index([metric, integrationType, window])
   @@map("UsageCounter")
 }
+
+// ============================================================================
+// MANAGEMENT API MODELS
+// ============================================================================
+
+/// Multi-step authorization state for Management API v2 (/api/v2/authorize,
+/// /api/v2/credentials/:id/reauthorize). Short-lived: expired documents are
+/// removed opportunistically. stepData is encrypted at rest.
+model AuthorizationSession {
+  id           String   @id @default(auto()) @map("_id") @db.ObjectId
+  sessionId    String   @unique
+  userId       String
+  entityType   String
+  credentialId String?
+  currentStep  Int      @default(1)
+  maxSteps     Int
+  stepData     Json     @default("{}")
+  expiresAt    DateTime
+  completed    Boolean  @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId, entityType])
+  @@index([expiresAt])
+  @@map("AuthorizationSession")
+}

package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql

@@ -0,0 +1,28 @@
+-- CreateTable
+-- Multi-step authorization state for Management API v2 (/api/v2/authorize).
+-- Short-lived rows; "stepData" is encrypted at rest by the application.
+CREATE TABLE "AuthorizationSession" (
+    "id" SERIAL NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "entityType" TEXT NOT NULL,
+    "credentialId" TEXT,
+    "currentStep" INTEGER NOT NULL DEFAULT 1,
+    "maxSteps" INTEGER NOT NULL,
+    "stepData" JSONB NOT NULL DEFAULT '{}',
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "completed" BOOLEAN NOT NULL DEFAULT false,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AuthorizationSession_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AuthorizationSession_sessionId_key" ON "AuthorizationSession"("sessionId");
+
+-- CreateIndex
+CREATE INDEX "AuthorizationSession_userId_entityType_idx" ON "AuthorizationSession"("userId", "entityType");
+
+-- CreateIndex
+CREATE INDEX "AuthorizationSession_expiresAt_idx" ON "AuthorizationSession"("expiresAt");

package/prisma-postgresql/schema.prisma

@@ -434,3 +434,29 @@ model UsageCounter {
   // Covers series() (metric + integrationType + window range).
   @@index([metric, integrationType, window])
 }
+
+// ============================================================================
+// MANAGEMENT API MODELS
+// ============================================================================
+
+/// Multi-step authorization state for Management API v2 (/api/v2/authorize,
+/// /api/v2/credentials/:id/reauthorize). Short-lived: expired rows are removed
+/// opportunistically. stepData is encrypted at rest.
+model AuthorizationSession {
+  id           Int      @id @default(autoincrement())
+  sessionId    String   @unique
+  userId       String
+  entityType   String
+  credentialId String?
+  currentStep  Int      @default(1)
+  maxSteps     Int
+  stepData     Json     @default("{}")
+  expiresAt    DateTime
+  completed    Boolean  @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId, entityType])
+  @@index([expiresAt])
+}

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="./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/tests/doubles/test-user-repository.js

@@ -23,7 +23,7 @@ class TestUserRepository {
 
     async createToken(userId, rawToken, minutes = 120) {
         const token = `token-for-${userId}-for-${minutes}-mins`;
-        this.tokens.set(token, { id: token, userId, rawToken });
+        this.tokens.set(token, { user: userId, rawToken });
         return token;
     }
 

package/user/use-cases/get-user-from-bearer-token.js

@@ -40,13 +40,8 @@ class GetUserFromBearerToken {
             throw Boom.unauthorized('Session Token Not Found');
         }
 
-        const tokenUserId = sessionToken.userId;
-        if (!tokenUserId) {
-            throw Boom.unauthorized('Session Token Has No User');
-        }
-
         if (this.userConfig.primary === 'organization') {
-            const organizationUserData = await this.userRepository.findOrganizationUserById(tokenUserId);
+            const organizationUserData = await this.userRepository.findOrganizationUserById(sessionToken.user);
 
             if (!organizationUserData) {
                 throw Boom.unauthorized('Organization User Not Found');
@@ -62,7 +57,7 @@ class GetUserFromBearerToken {
             );
         }
 
-        const individualUserData = await this.userRepository.findIndividualUserById(tokenUserId);
+        const individualUserData = await this.userRepository.findIndividualUserById(sessionToken.user);
 
         if (!individualUserData) {
             throw Boom.unauthorized('Individual User Not Found');

package/errors/mapping-already-exists-error.js

@@ -1,14 +0,0 @@
-const { BaseError } = require('./base-error');
-
-class MappingAlreadyExistsError extends BaseError {
-    constructor(integrationId, sourceId, ...errorOptions) {
-        super(
-            `Mapping already exists for integration ${integrationId} and sourceId ${sourceId}`,
-            ...errorOptions
-        );
-        this.integrationId = integrationId;
-        this.sourceId = sourceId;
-    }
-}
-
-module.exports = { MappingAlreadyExistsError };

package/integrations/use-cases/add-entities-to-integration.js

@@ -1,92 +0,0 @@
-const {
-    assertEntityIdsInput,
-    integrationNotFound,
-    loadIntegration,
-} = require('../utils/assert-entity-ids-input');
-
-/**
- * Attaches entities to an existing integration, e.g. when a user grants
- * access to more accounts after the integration was created. Every entity
- * must exist, belong to the integration's user, and be of a module the
- * integration already holds (so hydration can load it). Entities that are
- * already attached are left as they are.
- * @class AddEntitiesToIntegration
- */
-class AddEntitiesToIntegration {
-    /**
-     * @param {Object} params
-     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository
-     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
-     */
-    constructor({ integrationRepository, moduleRepository }) {
-        this.integrationRepository = integrationRepository;
-        this.moduleRepository = moduleRepository;
-    }
-
-    /**
-     * @param {string} integrationId
-     * @param {string[]} entityIds
-     * @returns {Promise<Object>} The updated integration record.
-     */
-    async execute(integrationId, entityIds) {
-        assertEntityIdsInput(integrationId, entityIds);
-
-        const integration = await loadIntegration(
-            this.integrationRepository,
-            integrationId
-        );
-
-        const entities = await this.moduleRepository.findEntitiesByIds(
-            entityIds
-        );
-        const foundIds = new Set(entities.map((e) => String(e.id)));
-        const missing = entityIds.filter((id) => !foundIds.has(String(id)));
-        if (missing.length > 0) {
-            const error = new Error(
-                `Entities not found: ${missing.join(', ')}`
-            );
-            error.code = 'ENTITIES_NOT_FOUND';
-            throw error;
-        }
-
-        const foreign = entities.filter(
-            (e) => String(e.userId) !== String(integration.userId)
-        );
-        if (foreign.length > 0) {
-            const error = new Error(
-                `Entities do not belong to the integration's user: ${foreign
-                    .map((e) => e.id)
-                    .join(', ')}`
-            );
-            error.code = 'ENTITY_USER_MISMATCH';
-            throw error;
-        }
-
-        const attached = await this.moduleRepository.findEntitiesByIds(
-            integration.entitiesIds ?? []
-        );
-        const heldModules = new Set(attached.map((e) => e.moduleName));
-        const otherModules = entities.filter(
-            (e) => !heldModules.has(e.moduleName)
-        );
-        if (otherModules.length > 0) {
-            const error = new Error(
-                `Entities belong to a module the integration does not hold: ${otherModules
-                    .map((e) => `${e.id} (${e.moduleName})`)
-                    .join(', ')}`
-            );
-            error.code = 'ENTITY_MODULE_MISMATCH';
-            throw error;
-        }
-
-        const updated =
-            await this.integrationRepository.addEntitiesToIntegration(
-                integrationId,
-                entityIds
-            );
-        if (!updated) throw integrationNotFound(integrationId);
-        return updated;
-    }
-}
-
-module.exports = { AddEntitiesToIntegration };