@friggframework/core 2.0.0--canary.681.2df9ef0.0 → 2.0.0--canary.682.cbca9e2.0

package/modules/use-cases/process-authorization-callback.js

@@ -1,5 +1,16 @@
 const { Module } = require('../module');
 const { ModuleConstants } = require('../ModuleConstants');
+const { pickExistingEntity } = require('../scope-resolution');
+
+/**
+ * What an entity belongs to when the caller says nothing: the person's own,
+ * outside any organization.
+ */
+const DEFAULT_TENANCY = Object.freeze({
+    scope: 'individual',
+    organizationId: null,
+    legacyOrgId: null,
+});
 const { getLogger } = require('../../logs');
 
 const log = getLogger('frigg.modules.authorization_callback');
@@ -30,7 +41,17 @@ class ProcessAuthorizationCallback {
         this.integrationRepository = integrationRepository;
     }
 
-    async execute(userId, entityType, params) {
+    /**
+     * @param {string} userId - the OWNER of what this creates (ADR-056 §3.2): the
+     *   person for `individual`, the organization's user for `organization`.
+     *   Not necessarily the caller; callers resolve it from the scope.
+     * @param {string} entityType
+     * @param {Object} params - what the module's authorization needs
+     * @param {{scope: string, organizationId: (string|null), legacyOrgId: (string|null)}} [tenancy]
+     *   the entity's scope and organization (§3.6); default: the person's own,
+     *   with no organization
+     */
+    async execute(userId, entityType, params, tenancy = DEFAULT_TENANCY) {
         log.debug('Authorization callback started', {
             eventName: `${log.name}.started`,
             userId,
@@ -57,10 +78,7 @@ class ProcessAuthorizationCallback {
                 userId,
                 entityType
             );
-        const existingEntity =
-            existingEntities && existingEntities.length > 0
-                ? existingEntities[0]
-                : null;
+        const existingEntity = pickExistingEntity(existingEntities, tenancy);
 
         if (existingEntity) {
             log.debug('Existing entity found', {
@@ -156,7 +174,8 @@ class ProcessAuthorizationCallback {
         const persistedEntity = await this.findOrCreateEntity(
             entityDetails,
             entityType,
-            module.credential.id
+            module.credential.id,
+            tenancy
         );
         log.debug('Authorization callback completed', {
             eventName: `${log.name}.completed`,
@@ -233,7 +252,12 @@ class ProcessAuthorizationCallback {
         module.credential = persisted;
     }
 
-    async findOrCreateEntity(entityDetails, moduleName, credentialId) {
+    async findOrCreateEntity(
+        entityDetails,
+        moduleName,
+        credentialId,
+        tenancy = DEFAULT_TENANCY
+    ) {
         const { identifiers, details } = entityDetails;
 
         // Support both 'user' and 'userId' field names from module definitions
@@ -247,11 +271,16 @@ class ProcessAuthorizationCallback {
             );
         }
 
-        const existingEntity = await this.moduleRepository.findEntity({
-            externalId: identifiers.externalId,
-            user: userId,
-            moduleName: moduleName,
-        });
+        // The same provider account in two organizations is two entities
+        // (ADR-056 §3.6), so the match is per organization.
+        const existingEntity = pickExistingEntity(
+            await this.moduleRepository.findEntities({
+                externalId: identifiers.externalId,
+                user: userId,
+                moduleName: moduleName,
+            }),
+            tenancy
+        );
 
         if (existingEntity) {
             // Repoint the entity's credentialId when re-auth produced a
@@ -282,12 +311,17 @@ class ProcessAuthorizationCallback {
             return existingEntity;
         }
 
-        return await this.moduleRepository.createEntity({
-            ...identifiers,
-            ...details,
-            moduleName: moduleName,
-            credential: credentialId,
-        });
+        // `organizationId` is not part of the entity data: that carries provider
+        // fields, and one that happens to be called organizationId is theirs.
+        return await this.moduleRepository.createEntity(
+            {
+                ...identifiers,
+                ...details,
+                moduleName: moduleName,
+                credential: credentialId,
+            },
+            { organizationId: tenancy.organizationId ?? null }
+        );
     }
 }
 

package/modules/use-cases/refresh-entity-options.js

@@ -1,4 +1,5 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class RefreshEntityOptions {
     /**
@@ -6,9 +7,11 @@ class RefreshEntityOptions {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {} params.moduleDefinitions
      */
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -36,7 +39,7 @@ class RefreshEntityOptions {
 
         // Validate entity ownership
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {

package/modules/use-cases/test-module-auth.js

@@ -1,4 +1,5 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class TestModuleAuth {
     /**
@@ -6,9 +7,11 @@ class TestModuleAuth {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module data operations.
      * @param {Array<Object>} params.moduleDefinitions - Array of module definitions.
      */
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -35,7 +38,7 @@ class TestModuleAuth {
 
         // Validate entity ownership
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.681.2df9ef0.0",
+    "version": "2.0.0--canary.682.cbca9e2.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.681.2df9ef0.0",
-        "@friggframework/prettier-config": "2.0.0--canary.681.2df9ef0.0",
-        "@friggframework/test": "2.0.0--canary.681.2df9ef0.0",
+        "@friggframework/eslint-config": "2.0.0--canary.682.cbca9e2.0",
+        "@friggframework/prettier-config": "2.0.0--canary.682.cbca9e2.0",
+        "@friggframework/test": "2.0.0--canary.682.cbca9e2.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "2df9ef0d1e98841190c6a8136ff77c886ca9e629"
+    "gitHead": "cbca9e22cf6af8765f83f03b2e6d3700d1e149b5"
 }

package/prisma-mongodb/schema.prisma

@@ -134,6 +134,14 @@ model Entity {
   moduleName   String?
   externalId   String?
 
+  // Organization this entity was connected in (ADR-056 §3.6): the active
+  // organization for `individual`, the owner for `organization`, null for
+  // `global`. Null on an `individual` entity is also what every row written
+  // before this column existed has, and what `individualAcross: 'all'` writes.
+  // Deliberately not a relation: a deleted organization must leave its rows
+  // invisible, not turn them into "unscoped" ones (SetNull would do that).
+  organizationId String? @db.ObjectId
+
   data Json @default("{}")
 
   createdAt DateTime @default(now())
@@ -150,6 +158,7 @@ model Entity {
   associationObjects AssociationObject[]
 
   @@index([userId])
+  @@index([userId, organizationId])
   @@index([externalId])
   @@index([moduleName])
   @@index([credentialId])
@@ -167,6 +176,11 @@ model Integration {
   user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)
   status IntegrationStatus @default(IN_CREATION)
 
+  // Organization this integration was created in (ADR-056 §3.6): the active
+  // organization at create time. Null for rows that predate the column. Not a
+  // relation, for the same reason as Entity.organizationId.
+  organizationId String? @db.ObjectId
+
   // Configuration and version
   config  Json? // Integration configuration object
   version String?
@@ -191,6 +205,7 @@ model Integration {
   processes    Process[]
 
   @@index([userId])
+  @@index([userId, organizationId])
   @@index([status])
   @@map("Integration")
 }

package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql

@@ -0,0 +1,25 @@
+-- Entity and Integration carry the organization they were created in (ADR-056 §3.6).
+-- Nullable, no default and no backfill: a row written before this migration keeps
+-- NULL, and the domain (modules/entity-scope.js) reads NULL as "predates scoping"
+-- (docs/guides/entity-scopes.md). No scope column: the owner's user type says it.
+-- Deliberately no foreign key: a deleted organization must leave its rows
+-- invisible, and ON DELETE SET NULL would turn them into unscoped ones.
+--
+-- Release note: the two CREATE INDEX statements below are plain (not
+-- CONCURRENTLY, which Prisma migrations cannot run inside a transaction). Each
+-- takes a SHARE lock on its table while it builds, so writes to "Entity" and
+-- "Integration" wait for it. Both tables are small in a typical Frigg
+-- deployment; on a very large one, create the indexes by hand first with
+-- CREATE INDEX CONCURRENTLY IF NOT EXISTS under the same names, then deploy.
+
+-- AlterTable
+ALTER TABLE "Entity" ADD COLUMN     "organizationId" INTEGER;
+
+-- AlterTable
+ALTER TABLE "Integration" ADD COLUMN     "organizationId" INTEGER;
+
+-- CreateIndex
+CREATE INDEX "Entity_userId_organizationId_idx" ON "Entity"("userId", "organizationId");
+
+-- CreateIndex
+CREATE INDEX "Integration_userId_organizationId_idx" ON "Integration"("userId", "organizationId");

package/prisma-postgresql/schema.prisma

@@ -131,6 +131,14 @@ model Entity {
   moduleName   String?
   externalId   String?
 
+  // Organization this entity was connected in (ADR-056 §3.6): the active
+  // organization for `individual`, the owner for `organization`, null for
+  // `global`. Null on an `individual` entity is also what every row written
+  // before this column existed has, and what `individualAcross: 'all'` writes.
+  // Deliberately not a relation: a deleted organization must leave its rows
+  // invisible, not turn them into "unscoped" ones (SetNull would do that).
+  organizationId Int?
+
   data Json @default("{}")
 
   createdAt DateTime @default(now())
@@ -144,6 +152,7 @@ model Entity {
   associationObjects AssociationObject[]
 
   @@index([userId])
+  @@index([userId, organizationId])
   @@index([externalId])
   @@index([moduleName])
   @@index([credentialId])
@@ -160,6 +169,11 @@ model Integration {
   user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)
   status IntegrationStatus @default(IN_CREATION)
 
+  // Organization this integration was created in (ADR-056 §3.6): the active
+  // organization at create time. Null for rows that predate the column. Not a
+  // relation, for the same reason as Entity.organizationId.
+  organizationId Int?
+
   // Configuration and version
   config  Json? // Integration configuration object
   version String?
@@ -183,6 +197,7 @@ model Integration {
   processes    Process[]
 
   @@index([userId])
+  @@index([userId, organizationId])
   @@index([status])
 }
 

package/types/index.d.ts

@@ -13,3 +13,4 @@
 /// <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,145 @@
+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;
+  }
+
+  /**
+   * One level's setting: a scope, or a default plus the scopes a request may
+   * choose from (ADR-056 §3.1). `global` is never chosen by a tenant request.
+   */
+  export type ScopeSetting =
+    | EntityScope
+    | { default?: EntityScope; allow?: EntityScope[] };
+
+  /**
+   * `appDefinition.ownership` (ADR-056 §3, §3.6). Resolution order for a new
+   * connection: request, binding, integration, entity type (`entities[name].scope`),
+   * this `scope`, then `organization` for an organization-primary app and
+   * `individual` otherwise.
+   */
+  export interface AppOwnership {
+    scope?: ScopeSetting;
+    /**
+     * `'organization'` (default): an individual entity belongs to the organization
+     * it was connected in. `'all'`: one connection per person across every
+     * organization, stored with no `organizationId`.
+     */
+    individualAcross?: "organization" | "all";
+  }
+
+  /** `Definition.ownership` on an integration (ADR-056 §3.1, §3.3). */
+  export interface IntegrationOwnership {
+    /** Scope every binding of this integration accepts unless it sets its own. */
+    scope?: ScopeSetting;
+    /** `'derive'` (default): organization when every entity it uses is organization-scoped. */
+    owner?: "derive" | "individual" | "organization";
+  }
+
+  export interface AppDefinition {
+    integrations: any[];
+    /** App-level entity type registry (ADR-059). */
+    entities?: AppDefinitionEntities;
+    /** Who owns what a person connects (ADR-056). */
+    ownership?: AppOwnership;
+    [key: string]: unknown;
+  }
+
+  /** Whose a record is and what the caller may do with it (ADR-056 §3.4). */
+  export interface RecordTenancy {
+    scope: Exclude<EntityScope, "global">;
+    owner: { type: Exclude<EntityScope, "global">; id: string };
+    /** Null for an individual entity connected outside an organization, or under `individualAcross: 'all'`. */
+    organizationId: string | null;
+    /** `manage`: create, reauthorize, delete. `use`: bind it, proxy through it. `view`: metadata only. */
+    access: "manage" | "use" | "view";
+  }
+
+  /** Which scope a connection gets, and from which level of the order (ADR-056 §3.1). */
+  export interface ResolvedScope {
+    scope: EntityScope;
+    /** Where `scope` came from. `request` when the request chose within the allowed list. */
+    source: "request" | "binding" | "integration" | "entityType" | "app" | "default";
+    /** The level that decided what a request may choose from. */
+    decidedBy: "binding" | "integration" | "entityType" | "app" | "default";
+    allow: EntityScope[];
+  }
+
+  /**
+   * First match wins, each level overriding the ones below it. A request may
+   * choose only from the deciding level's `allow`; `global` never comes from a
+   * tenant request. Throws a Boom 400/403 for a request scope that is not allowed.
+   */
+  export function resolveScope(levels: {
+    request?: EntityScope;
+    binding?: ScopeSetting;
+    integration?: ScopeSetting;
+    entityType?: ScopeSetting;
+    app?: ScopeSetting;
+    primary?: "individual" | "organization";
+  }): ResolvedScope;
+
+  /** Every binding of every integration with its resolved scope (for tooling that wants to show the chain). */
+  export function listBindingScopes(
+    appDefinition: Pick<AppDefinition, "integrations" | "ownership">,
+    entityTypeRegistry: EntityTypeRegistry,
+    primary?: "individual" | "organization"
+  ): Array<{
+    integration: string;
+    binding: string;
+    moduleName: string | null;
+    scope: EntityScope;
+    source: ResolvedScope["source"];
+    owner: "derive" | "individual" | "organization";
+  }>;
+
+  /** Invalid ownership or scope setting, thrown at app-definition load. `code` is always `OWNERSHIP_CONFIG_INVALID`. */
+  export class OwnershipConfigError extends Error {
+    code: "OWNERSHIP_CONFIG_INVALID";
+  }
+
+  /**
+   * 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";
+  }
+}