@friggframework/core 2.0.0--canary.686.df38e8e.0 → 2.0.0--canary.710.9045bbc.0

package/CHANGELOG.md

@@ -1,19 +1,3 @@
-# Unreleased
-
-#### Netlify queue targets are allow-listed
-
-- `NetlifyBackgroundProvider.send()` now accepts only a background function path on the site (`/.netlify/functions/<name>-background`) and an absolute http(s) site URL without credentials. Anything else (`//host/x`, an absolute URL, `..`, a query, an empty `URL`) throws before any request. Previously the queue id was appended to the site URL as given, so an empty site URL and a stored `//host/x` sent a signed message to another host.
-- `NetlifySchedulerAdapter` maps any queue URL that is not such a path to the worker function, as it already did for SQS URLs.
-
-#### Behaviour change: module credential fields are now encrypted
-
-- `credentialFields` declared in an API module's `encryption` config (for example `Definition.encryption.credentialFields`) were never registered for encryption: `loadModuleEncryptionSchemas` required a path that does not exist and the error was swallowed. They are now registered, for modules bound by integrations and for modules registered in `appDefinition.entities` (ADR-059).
-- Existing rows are not rewritten. A credential saved before this release stays plaintext until it is next written, and is read as stored.
-- Reads now tolerate plaintext: a value is only treated as ciphertext when it has the exact `keyId:iv:ciphertext:encryptedKey` shape (previously any string with three or more colons, such as `https://user:pw@host:443`), and a value with that shape that fails to decrypt throws `FieldDecryptionError` in a deployed runtime (any stage, AWS Lambda or Netlify) and is returned as stored with a warning on a local run.
-- An app's own `encryption.schema` is no longer replaced when module fields are added to it.
-
----
-
 # v1.2.2 (Fri Aug 09 2024)
 
 #### 🐛 Bug Fix

package/CLAUDE.md

@@ -206,11 +206,51 @@ packages/core/
 - `delete-integration-for-user.js` - Remove integration
 - `get-integration-instance.js` - Load integration with modules
 - `load-integration-context.js` - Full integration context loading
+- `add-entities-to-integration.js` / `remove-entities-from-integration.js` - Attach or detach entities on an existing integration
 
 **Repositories**:
 - `integration-repository-factory.js` - Creates database-specific repositories
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
+- `addEntitiesToIntegration(integrationId, entityIds)` /
+  `removeEntitiesFromIntegration(integrationId, entityIds)` change the entity
+  set of an existing integration (all three adapters; `null` for an unknown
+  integration). Reach them through the `addEntitiesToIntegration` /
+  `removeEntitiesFromIntegration` commands. The add use case
+  (`add-entities-to-integration.js`) rejects unknown entities
+  (`ENTITIES_NOT_FOUND`, 404), entities of another user
+  (`ENTITY_USER_MISMATCH`, 403) and entities of a module the integration does
+  not already hold (`ENTITY_MODULE_MISMATCH`, 400). The remove use case
+  (`remove-entities-from-integration.js`) refuses to leave a module with no
+  entity (`LAST_ENTITY_OF_MODULE`, 409). Re-adding an attached entity or
+  removing a detached one changes nothing; a detached entity is not deleted.
+  `integration-repository-entities-parity.db.test.js` runs every adapter against
+  real databases when `INTEGRATION_ENTITIES_PARITY_MONGO_URL` /
+  `INTEGRATION_ENTITIES_PARITY_POSTGRES_URL` are set. The DocumentDB adapter
+  writes only `Integration.entityIds` (as its `createIntegration` does), not
+  `Entity.integrationIds`.
+  **One credential, many accounts**: when one credential covers several
+  provider accounts, give each account its own entity (externalId = account
+  id) and attach them all to one integration; webhooks then route with
+  `findIntegrationByEntityExternalId`. Traps:
+  (1) `IntegrationBase` keys modules by module name, so `this.<moduleKey>`
+  holds only one entity's module, and on the queue/webhook path
+  (`get-integration-instance.js`) `this.entities` holds entity **ids**, not
+  records. For per-account work (a webhook for one account, teardown of every
+  account in `onDelete`), load
+  `this.commands.loadIntegrationContextById(this.id)` and use
+  `context.modules`: one module per entity, each with its record on
+  `module.entity` (pick by `module.entity.externalId`).
+  (2) `findIntegrationByEntityExternalId` counts every entity with that
+  externalId, attached or not, across users: reuse an existing entity
+  (`findEntity`) when an account comes back, or delete it when it is revoked,
+  never create a second one.
+  (3) `createIntegration` reuses an existing integration of the same user
+  and type whose entities include all requested ones (an exact match wins),
+  so a reconnect that sends the original entities finds the integration that
+  now holds more.
+  (4) Every module's delegate is the integration: an auth failure on any
+  account marks the shared credential invalid and the integration ERROR.
 - `integration-mapping-repository-*.js` - Mapping data persistence.
   `queryMappings(integrationId, { where, orderBy, skip, take, omit })`
   returns `{ mappings, total }`: one filtered, ordered page of an
@@ -226,7 +266,7 @@ packages/core/
   mapping keys to leave out of the rows; never write such rows back. Path
   segments must match `^[A-Za-z_][A-Za-z0-9_]*$`. The PostgreSQL, MongoDB and
   DocumentDB adapters give the same pages and totals;
-  `integration-mapping-repository-query-parity.test.js` checks that against
+  `integration-mapping-repository-query-parity.db.test.js` checks that against
   real databases when `QUERY_MAPPINGS_PARITY_MONGO_URL` /
   `QUERY_MAPPINGS_PARITY_POSTGRES_URL` are set. Two orderings still differ:
   strings compare by the database collation on PostgreSQL and by code point
@@ -332,14 +372,12 @@ 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
@@ -502,29 +540,6 @@ The single source of the max receive count is
 devtools integration builder uses it for the queue's `RedrivePolicy` and sets
 it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
 
-### Management API v2 notes (`/management-api`)
-
-- Handlers in `management-api/v2/handlers/` call use cases only; dependencies are wired in
-  `management-api/v2/dependencies.js`. Errors are `{ error: { code, message, details? } }`.
-- `appDefinition.managementApi` is resolved by `resolveManagementApiConfig`, which `loadAppDefinition`
-  also calls so a bad value stops the app at load. Numeric proxy limits fall back to their defaults;
-  `proxy.scopes` (ADR-056 §3.5, default `['individual']`) never does: an unknown scope, `'global'`, a
-  non-list, an empty list or a repeated scope throws `ManagementApiConfigError`
-  (`MANAGEMENT_API_CONFIG_INVALID`).
-- **Entity proxy** (`ExecuteEntityProxyRequest`): visibility in the active organization comes from
-  `GetEntityModuleForUser` (404), then `assertProxyable` reads the same `{ scope, access }` description
-  the v2 lists return: `grantsUse(access)` (`use` or `manage`, from `modules/scope-visibility.js`) or 403
-  `PROXY_NOT_ALLOWED` `reason: 'access'`, and the scope must be in `proxy.scopes` or 403 `reason: 'scope'`.
-  Do not add a second ownership rule for the proxy; change the description instead.
-- **Not visible is 404, and so is missing.** Module repositories throw `entityNotFoundError(id)`
-  (`modules/repositories/entity-not-found.js`) for a missing row and use cases match it with
-  `isEntityNotFound`. A 500 for a missing id next to a 404 for another tenant's id tells a caller which
-  ids exist. A test double that resolves `findEntityById` to `null` hides this: no adapter does that.
-- **Tenant isolation on real PostgreSQL**: `management-api/v2/tenant-isolation.postgres.test.js`, run with
-  `FRIGG_TEST_POSTGRES_URL=<a database it may wipe>`. It applies the migrations, truncates every table
-  before each test, and drives real adopter-JWT auth through the real router and Prisma repositories.
-  Without the variable it is skipped (and says so), not passed. See `docs/guides/entity-scopes.md`.
-
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.
@@ -775,9 +790,6 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
 - `FRIGG_LOG_LEVEL` - Minimum log level (`TRACE` … `FATAL`, default `INFO`; `DEBUG` on local runs)
 - `FRIGG_QUEUE_MAX_RECEIVE_COUNT` - Set by devtools on integration queue workers whose queue the stack owns; feeds `delivery.maxReceiveCount`
-- `FRIGG_QUEUE_SIGNING_SECRET` - Required for HTTP-delivered queues (Netlify Background Functions). `NetlifyBackgroundProvider` signs each message (HMAC-SHA256 over `timestamp.rawBody`, `x-frigg-queue-signature` / `x-frigg-queue-timestamp`) and `verifyEvent()` refuses anything unsigned, tampered, signed with another secret or older than 5 minutes. Unset → `send()` throws and every event is refused (`queues/queue-message-auth.js`)
-- `FRIGG_QUEUE_ALLOW_UNSIGNED` - `true` accepts unsigned queue messages when no secret is set, outside production only (`STAGE` dev/test/local, `NODE_ENV` development/test, or `NETLIFY_DEV`); ignored in production and in any deployed function, whatever `STAGE` says (`providers/runtime-detection.js` `isDeployedRuntime`: AWS Lambda variables, or the active provider's `detect()`, e.g. provider-netlify via `FRIGG_PROVIDER=netlify`)
-- `QSTASH_CURRENT_SIGNING_KEY` / `QSTASH_NEXT_SIGNING_KEY` - Required with the QStash queue: `QStashQueueProvider.verifyEvent()` checks the `Upstash-Signature` JWT with them
 
 ## Version Information
 

package/README.md

@@ -305,7 +305,6 @@ 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
@@ -353,110 +352,6 @@ 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` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). For permissions the token's role wins; a token with none uses the role stored on the person's membership of the active organization, and is a member when there is none: it cannot create or change organization-level entities or integrations. `user.orgAdminRoles` (default `['ADMIN']`) names the roles that can. Frigg bearer tokens are not gated unless `user.orgAdminGateBearerTokens: true`. |
-
-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.
-- **The token's organization is the request's active organization**, and a person can belong to
-  several (ADR-056 §3.6). The first time a person presents a token for an organization they are
-  not a member of, Frigg adds an `OrganizationMembership` and the request runs as that
-  organization (`user.getActiveOrganizationId()`; `user.getId()` under `primary: 'organization'`).
-  Nothing is moved: `IndividualUser.organizationId` is a legacy pointer, set only on a person's
-  first link and read as an implicit membership. The same applies to `x-frigg-apporgid` with
-  `sharedSecret`. With `user.strictMembership: true` those headers cannot add anyone to an organization
-  that already existed (400 for a non-member, a brand-new `appUserId` included); only an organization
-  the request itself creates is allowed. `strictUserValidation` is a deprecated alias with that same
-  meaning. See
-  [Organization memberships](../../docs/guides/organization-memberships.md). A token naming a second
-  organization is no longer a `403` (`multi_org_unsupported` is gone).
-- Two first logins for the same new person or organization, even in different organizations, both
-  succeed: a create that loses to a unique constraint finds the winner's row.
-
-#### Entity scopes and ownership (ADR-056 §3)
-
-Who owns an entity (a connected account) or an integration follows its **scope**, not `user.primary`:
-
-| Scope | Owned by | Created with |
-|---|---|---|
-| `individual` | the person (`individualUser`) | the active organization (`organizationId`), or none under `individualAcross: 'all'` |
-| `organization` | the active organization's user | that organization |
-| `global` | nobody (the app owner) | none; refused by the tenant API (admin routes only) |
-
-The scope of a new connection is the first of: the request (`scope` on `POST /api/v2/authorize`, only from
-the deciding level's `allow` list), the integration binding (`Definition.modules[key].scope` or
-`Definition.entities[key].scope`), `Definition.ownership.scope`, the entity type
-(`appDefinition.entities[name].scope`), `appDefinition.ownership.scope`, then `organization` for an
-organization-primary app and `individual` otherwise. A setting is `'organization'` or
-`{ default: 'individual', allow: ['individual', 'organization'] }`.
-
-```javascript
-const appDefinition = {
-    user: { primary: 'individual', authModes: { adopterJwt: true } },
-    ownership: { scope: 'individual', individualAcross: 'organization' }, // the defaults
-    entities: {
-        google: { definition: google, scope: 'individual' },
-        xero: { definition: xero, scope: { default: 'organization', allow: ['organization', 'individual'] } },
-    },
-    integrations: [Sync], // Sync.Definition.ownership = { owner: 'derive' }
-};
-```
-
-`GET /api/v2/entities` and `/integrations` return, for the active organization, its own
-rows and the caller's, each with `scope`, `owner`, `organizationId` and `access`, and take `?scope=` and
-`?owner=me|org`. An individual entity is only visible and usable in the organization it was connected in
-(or in all of them, with `individualAcross: 'all'`). Rows written before this existed keep working: see
-[Entity scopes](../../docs/guides/entity-scopes.md), which also covers the schema (`organizationId` on
-`Entity` and `Integration`, no `scope` column) and what is deferred.
-
 ### 8. Lambda Utilities (`/lambda`)
 
 AWS Lambda-specific utilities and helpers.

package/application/commands/README.md

@@ -67,9 +67,10 @@ class MyIntegration extends IntegrationBase {
     async hydrateFromExternalUser(externalUserId) {
         // Find integration context by external entity ID
         const result =
-            await this.commands.findIntegrationContextByExternalEntityId(
-                externalUserId
-            );
+            await this.commands.findIntegrationContextByExternalEntityId({
+                externalId: externalUserId,
+                type: 'my-integration', // integration config.type to match
+            });
 
         if (result.error) {
             return { error: result.error };
@@ -231,9 +232,10 @@ Manage integration records and load full integration contexts.
 ```javascript
 // Find integration context by external entity ID
 // Returns { context, error } where context includes record + hydrated modules
-const result = await commands.findIntegrationContextByExternalEntityId(
-    'external-user-or-workspace-id'
-);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: 'external-user-or-workspace-id',
+    type: 'my-integration', // integration config.type to match
+});
 
 if (!result.error) {
     integration.setIntegrationRecord(result.context);
@@ -299,7 +301,10 @@ try {
 For integration context operations, errors are returned in the result:
 
 ```javascript
-const result = await commands.findIntegrationContextByExternalEntityId(userId);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 
 if (result.error) {
     return { error: result.error };
@@ -349,9 +354,10 @@ const result =
 const { createFriggCommands } = require('@friggframework/core');
 
 this.commands = createFriggCommands({ integrationClass: MyIntegration });
-const result = await this.commands.findIntegrationContextByExternalEntityId(
-    userId
-);
+const result = await this.commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 ```
 
 ## Best Practices
@@ -433,7 +439,7 @@ if (!user) {
 |                 | `findEntitiesByIds(ids)`                                | Find multiple by IDs                      |
 |                 | `updateEntity(id, updates)`                             | Update entity properties                  |
 |                 | `deleteEntity(id)`                                      | Delete entity                             |
-| **Integration** | `findIntegrationContextByExternalEntityId(externalId)`  | Load integration + modules by external ID |
+| **Integration** | `findIntegrationContextByExternalEntityId({ externalId, type })` | Load integration + modules by external ID |
 |                 | `loadIntegrationContextById(integrationId)`             | Load integration + modules by ID          |
 
 ## Support

package/application/commands/entity-commands.js

@@ -1,12 +1,24 @@
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
+const { toCredentialId } = require('../../modules/utils/to-credential-id');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 404,
     INVALID_ENTITY_DATA: 400,
 };
 
+function toEntityDto(entity) {
+    return {
+        id: entity.id,
+        userId: entity.userId,
+        externalId: entity.externalId,
+        name: entity.name,
+        moduleName: entity.moduleName,
+        credentialId: toCredentialId(entity.credential),
+    };
+}
+
 function mapErrorToResponse(error) {
     const status = ERROR_CODE_MAP[error?.code] || 500;
     return {
@@ -66,16 +78,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.createEntity(entityData);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -109,16 +112,7 @@ function createEntityCommands() {
                     return null;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -139,16 +133,7 @@ function createEntityCommands() {
 
                 const entities = await moduleRepo.findEntitiesByUserId(userId);
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -180,16 +165,7 @@ function createEntityCommands() {
                         moduleName
                     );
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -213,16 +189,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.findEntityById(entityId);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -250,16 +217,7 @@ function createEntityCommands() {
                     throw error;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }

package/application/commands/integration-commands.js

@@ -18,7 +18,7 @@ const {
     ListIntegrationsByEntityExternalIdUseCase,
 } = require('../../integrations/use-cases/list-integrations-by-entity-external-id');
 const {
-    GetIntegrationsByUserId,
+    GetIntegrationsForUser,
 } = require('../../integrations/use-cases/get-integrations-for-user');
 const {
     CreateIntegration,
@@ -30,9 +30,14 @@ const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
 const {
-    getEntityTypeRegistry,
-    getEntityTypeDefinitions,
-} = require('../../modules/entity-type-registry');
+    AddEntitiesToIntegration,
+} = require('../../integrations/use-cases/add-entities-to-integration');
+const {
+    RemoveEntitiesFromIntegration,
+} = require('../../integrations/use-cases/remove-entities-from-integration');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../../integrations/utils/map-integration-dto');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
@@ -41,6 +46,11 @@ const ERROR_CODE_MAP = {
     EXTERNAL_ID_REQUIRED: 400,
     TYPE_REQUIRED: 400,
     INTEGRATION_RECORD_NOT_FOUND: 404,
+    INVALID_INTEGRATION_DATA: 400,
+    ENTITIES_NOT_FOUND: 404,
+    ENTITY_USER_MISMATCH: 403,
+    ENTITY_MODULE_MISMATCH: 400,
+    LAST_ENTITY_OF_MODULE: 409,
 };
 
 function mapErrorToResponse(error) {
@@ -52,16 +62,7 @@ function mapErrorToResponse(error) {
     };
 }
 
-/**
- * @param {Object} [params]
- * @param {Function} [params.integrationClass]
- * @param {Array<object>} [params.moduleDefinitions] - the app's offered module
- *   definitions (`loadAppDefinition().moduleDefinitions`). Integration code
- *   calls this from a constructor with no app definition in hand, so when it
- *   is omitted the commands hydrate with this integration's own modules only
- *   (a registry built from `{ integrations: [integrationClass] }`).
- */
-function createIntegrationCommands({ integrationClass, moduleDefinitions } = {}) {
+function createIntegrationCommands({ integrationClass } = {}) {
     // Always use Frigg's default repositories and use cases
     const integrationRepository = createIntegrationRepository();
 
@@ -118,13 +119,13 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
 
     const moduleRepository = createModuleRepository();
 
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses([
+        integrationClass,
+    ]);
+
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions:
-            moduleDefinitions ??
-            getEntityTypeDefinitions(
-                getEntityTypeRegistry({ integrations: [integrationClass] })
-            ),
+        moduleDefinitions,
     });
 
     const loadIntegrationContextUseCase = new LoadIntegrationContextUseCase({
@@ -152,7 +153,7 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
             moduleRepository,
         });
 
-    const getIntegrationsForUserUseCase = new GetIntegrationsByUserId({
+    const getIntegrationsForUserUseCase = new GetIntegrationsForUser({
         integrationRepository,
         integrationClasses: [integrationClass],
         moduleFactory,
@@ -173,6 +174,17 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
         integrationRepository,
     });
 
+    const addEntitiesToIntegrationUseCase = new AddEntitiesToIntegration({
+        integrationRepository,
+        moduleRepository,
+    });
+
+    const removeEntitiesFromIntegrationUseCase =
+        new RemoveEntitiesFromIntegration({
+            integrationRepository,
+            moduleRepository,
+        });
+
     return {
         findIntegrationById,
         listIntegrations,
@@ -317,6 +329,47 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
             }
         },
 
+        /**
+         * Attach entities to an existing integration. Every entity must
+         * exist, belong to the integration's user, and be of a module the
+         * integration already holds; entities that are already attached are
+         * left as they are.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to attach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async addEntitiesToIntegration({ integrationId, entityIds }) {
+            try {
+                return await addEntitiesToIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Detach entities from an integration. Entities that are not
+         * attached are ignored; detached entities are not deleted. Each
+         * module must keep at least one entity.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to detach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async removeEntitiesFromIntegration({ integrationId, entityIds }) {
+            try {
+                return await removeEntitiesFromIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
         /**
          * Delete an integration by ID
          * @param {string} integrationId - Integration ID to delete

package/application/commands/scheduler-commands.js

@@ -121,19 +121,17 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                     throw error;
                 }
 
-                // An adapter with its own notion of a queue target (Netlify:
-                // the worker function) resolves it; otherwise the target is
-                // an SQS queue and its URL is required.
-                const service = getSchedulerService();
-                const resolvesOwnTarget =
-                    typeof service?.toQueueResourceId === 'function';
-
-                if (!queueUrl && !resolvesOwnTarget) {
+                if (!queueUrl) {
                     const error = new Error('queueUrl is required');
                     error.code = 'INVALID_JOB_DATA';
                     throw error;
                 }
 
+                // Derive ARN from URL (business logic - transformation)
+                const queueArn = deriveArnFromQueueUrl(queueUrl);
+
+                // Get scheduler service (via DI or factory)
+                const service = getSchedulerService();
                 if (!service) {
                     console.warn(
                         `[${integrationName}] Scheduler not configured, skipping job schedule`
@@ -159,9 +157,7 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                 const result = await service.scheduleOneTime({
                     scheduleName: jobId,
                     scheduleAt: scheduledAt,
-                    queueResourceId: resolvesOwnTarget
-                        ? service.toQueueResourceId(queueUrl)
-                        : deriveArnFromQueueUrl(queueUrl),
+                    queueResourceId: queueArn,
                     payload: sqsPayload,
                 });