[seanspeaks]

Summary

This implements ADR-056 §3.1–§3.4 and the entity, integration and list parts of §3.6. An entity or integration is now owned by a person, by an organization, or globally, and lists show only what belongs to the active organization.

Stack: this is the first of three PRs: #681 (memberships) → this → #683 (org roles) → #684 (credential scoping). It is stacked on #681 and also merges #679 (entity registry), because the scope chain reads the registry's per-type scope. Until #679 merges, the diff against #681 includes #679's commits.

Scope resolution (modules/scope-*.js, re-exported from entity-scope.js)

• Pure resolution in ADR order:

  1. request override ({ default, allow });
  2. integration binding;
  3. integration;
  4. app entity type (registry settings.scope);
  5. appDefinition.ownership;
  6. a default derived from user.primary.

  ownership.individualAcross ('organization' or 'all') is supported.

• Validated at app-definition load (OwnershipConfigError). This includes §3.3: an organization-owned integration cannot bind an individual entity. Schemas, OpenAPI and types are updated.

Data

• organizationId (nullable) on Entity and Integration, in both Prisma schemas, with a Postgres migration (20261016000000_add_entity_integration_organization) and an index on [userId, organizationId].
  • The migration was checked on a throwaway Postgres 16: it applies cleanly and migrate diff is empty.
  • There is no data migration.
  • There is no scope column, because the owner already encodes the scope.
  • organizationId is deliberately not a foreign key.
• Release note: a plain CREATE INDEX takes a SHARE lock while it builds, and Prisma migrations cannot use CONCURRENTLY. Adopters with very large Entity or Integration tables can pre-create the index by hand under the same name.

Ownership on create

• Authorize: v1 and v2 authorize own the entity by its resolved scope and set organizationId. organizationId comes only from the active organization, never from provider data. A tenant request for global returns 403.
• Integration create: stores organizationId and derives the owner per the ADR table.
• Security fix (v1): POST /api/integrations used to accept any entity id. It now uses the same ownership resolver as v2, which returns 404 before anything is written.
• Mixed scopes: an integration that mixes scopes (an individual integration using an org-owned entity) is refused with 400 before anything is persisted.

Lists and access

• What lists return: /api/v2/entities, /credentials and /integrations return, for the active organization:
  • its organization records;
  • the caller's individual records, by the §3.6 rule owner = caller AND (organizationId = active OR (all AND organizationId IS NULL)).
• List fields: each record carries scope, owner, organizationId and access. Lists take ?scope= and ?owner=me|org filters.
• One rule everywhere: one clause list is both the repository query (Postgres, Mongo and DocumentDB; on Mongo it matches null or unset) and the in-memory access check. Proxy, test-auth, options, delete, reauthorize and every v1 per-integration route use the same rule.

Legacy rows (existing data, organizationId null)

• Default individual app with no organizations: unchanged.
• Org-primary apps:
  • Org-owned legacy rows stay visible to the organization.
  • A person's legacy individual rows show in the organization named by their legacy organizationId pointer.
  • Repeating POST /api/integrations for a legacy org-owned integration still reuses it, with no duplicate and no second ON_CREATE. This is tested with org-only headers and with a pointer mismatch.
• Entity proxy: until F6 adds managementApi.proxy.scopes, the entity proxy refuses organization-scope entities (ADR §3.5: narrowest by default). Org-primary apps that proxy through org entities must opt in once F6 lands.

Left for later PRs

• Org role gates: feat(core): organization roles for organization-owned records #683.
• Credential listing through entities: feat(core): scope credentials through their entities #684.
• proxy.scopes and the real-Postgres isolation suite: F6.
• ORPHANED, member removal, and GET /api/v2/me/organizations.

Test plan

• Core suite, run with a no-op global setup (Mongo binaries can't run here): 14 suites and 61 tests fail, the same set by name as base; 3357 pass.
• packages/schemas: 194 pass.
• ESLint on changed files: 0 errors.
• Two independent reviews, one on spec and compatibility and one on code quality.
  • The spec reviewer checked the ownership queries and the migration against a real Postgres 16 with seeded legacy rows.
  • Both blocking findings are fixed: the org-primary duplicate create (here), and a missing role read as admin (feat(core): organization roles for organization-owned records #683).
  • The review asked for this split.
• 38 of 38 mutations killed on this branch.

Docs: docs/guides/entity-scopes.md is new; organization-memberships.md and the core README are updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HyrF4oqcTdK2AtvcrocxE6

---

Note

High Risk
Changes core tenancy, authorization, integration binding, and list visibility across v1/v2 APIs, with a DB migration and legacy compatibility rules—mistakes could leak or hide the wrong org’s data.

Overview
Implements ADR-056 entity scopes: entities and integrations are owned by individual, organization, or (tenant-refused) global scope, with nullable organizationId on both models, Postgres migration, and Mongo null OR unset matching for legacy rows.

Scope resolution lives in scope-*.js / createScopePolicy: validated at loadAppDefinition (OwnershipConfigError), applied on authorize/create, and used for list + access via one clause set (findIntegrationsByOwnership / entity equivalents + in-memory describeRecord). v2 (and docs) expose scope, owner, organizationId, access and ?scope / ?owner filters. Credentials stay unscoped in this PR; entity proxy fails closed for organization-scoped entities until F6 proxy.scopes.

Integration create resolves owner + org through ResolveIntegrationOwnership (mixed scopes, scope mismatch, org+individual entity → 400; invisible entities → 404). CreateIntegration stores organizationId, dedupes within org (with adoptUnscoped for legacy rows), and loads modules before persisting to avoid orphan IN_CREATION rows. v1 POST /api/integrations and authorize/entity routes now follow the same rules (security fix: no arbitrary entity binding).

Also wires ADR-059 entity registry: loadAppDefinition returns entityTypeRegistry / moduleDefinitions; health, workers, webhooks, and createFriggCommands pass the full offered module set (registry-only types authorizeable). getModulesDefinitionFromIntegrationClasses is deprecated; GetIntegrationsByUserId splits app-level “all for user id” from request-scoped GetIntegrationsForUser. Integration GET responses strip credentials via toPublicEntities.

New guide docs/guides/entity-scopes.md; membership docs mark F5 scoping done.

^{Reviewed by Cursor Bugbot for commit 451c957. Bugbot is set up for automated code reviews on this repo. Configure here.}

📦 Published PR as canary version: 2.0.0--canary.682.451c957.0

✨ Test out this PR locally via:

npm install @friggframework/admin-scripts@2.0.0--canary.682.451c957.0
npm install @friggframework/core@2.0.0--canary.682.451c957.0
npm install @friggframework/devtools@2.0.0--canary.682.451c957.0
npm install @friggframework/eslint-config@2.0.0--canary.682.451c957.0
npm install @friggframework/prettier-config@2.0.0--canary.682.451c957.0
npm install @friggframework/schemas@2.0.0--canary.682.451c957.0
npm install @friggframework/serverless-plugin@2.0.0--canary.682.451c957.0
npm install @friggframework/test@2.0.0--canary.682.451c957.0
npm install @friggframework/ui@2.0.0--canary.682.451c957.0
# or 
yarn add @friggframework/admin-scripts@2.0.0--canary.682.451c957.0
yarn add @friggframework/core@2.0.0--canary.682.451c957.0
yarn add @friggframework/devtools@2.0.0--canary.682.451c957.0
yarn add @friggframework/eslint-config@2.0.0--canary.682.451c957.0
yarn add @friggframework/prettier-config@2.0.0--canary.682.451c957.0
yarn add @friggframework/schemas@2.0.0--canary.682.451c957.0
yarn add @friggframework/serverless-plugin@2.0.0--canary.682.451c957.0
yarn add @friggframework/test@2.0.0--canary.682.451c957.0
yarn add @friggframework/ui@2.0.0--canary.682.451c957.0

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d8626c4. Configure here.}

[cursor]

Credential data can override owner check

Medium Severity

CreateEntityFromCredential authorizes the request with credential.userId from findCredentialById, but those adapters still spread the JSON data blob after the identity columns. A userId (or id) key inside stored token data replaces the real owner, so the new INVALID_CREDENTIAL check can accept another user's credential or reject a valid one.

 

^{Reviewed by Cursor Bugbot for commit d8626c4. Configure here.}

[cursor]

Frigg 2.0.1 review (Stack A) — COMMENT only

Verdict (would): changes needed

Cross-org gates (describeRecord / visibilityClauses / GetOwned* → 404) are generally sound. v2 DTOs strip secrets (credentialId only). v1 still embeds full credentials, and this PR newly lets individual-primary org members use org-owned entities — expanding who can pull those secrets.

Blocking

1. Org members get raw credentials via v1 entity/integration payloads
   • packages/core/modules/use-cases/get-module.js (~69–76) — GET /api/entities/:id returns credential
   • map-module-dto.js / integration DTOs — entity / entities[] can carry populated credential blobs
     Failure: Member of org X (individual primary) lists or gets an org Slack/CRM connection → receives OAuth tokens / API keys in JSON. Before this PR those org rows were not visible under individual primary. v2 is fine; v1 is still on by default.
     Fix: Mirror v2 (credentialId + authIsValid only) in GetModule, module/integration DTOs — or disable v1 when ownership scopes are enabled.

Should-fix

2. ENTITY_IN_USE may disclose foreign integration ids via global findIntegrationsByEntityId. Filter to integrations the caller may see, or omit ids.
3. Hydration trusts entitiesIds without re-checking visibility — defense-in-depth: skip entities that fail describeRecord so legacy/corrupt ids cannot pull another org’s credential into the DTO (especially until v1 secret stripping lands).

Nits

• Missing vs foreign → same 404 on ownership load path looks good.
• Unscoped org rows { userId: activeOrgId, organizationId: null } match ADR legacy behavior.

No formal approve / request-changes on this review.

[cursor]

blocking — widening canUseEntity exposes v1 credential payloads to org members

Switching from ownsUserId to canUseEntity correctly implements ADR-056 use-access — but the return value below still includes credential: module.credential (full decrypted secrets). Integration DTOs similarly embed populated entities[].

Scenario: Individual-primary member of org X calls v1 GET /api/entities/:id (or lists integrations) for an org-owned connection → receives OAuth tokens / API keys. Those rows were not visible under individual primary before this PR. v2 masks credentials; v1 is still on by default.

Please strip secrets from v1 entity/integration responses (mirror v2: credentialId + authIsValid only), or refuse to enable ownership scopes while v1 returns raw credentials.

[seanspeaks]

Verdict: confirmed, and wider than described. Checked on this branch's head (d8626c44) with a throwaway test (not committed).

Live today, for org members

• GET /api/entities (integration-router.js → GetEntitiesForUser.execute, modules/use-cases/get-entities-for-user.js:30-40). findEntitiesByOwnership populates credential through _mapEntity (module-repository-postgres.js:238-241, module-repository-mongo.js:199-202). mapModuleClassToModuleDTO (modules/utils/map-module-dto.js:12) then returns entity: moduleInstance.entity unfiltered. A member of org 17 who lists entities gets org 17's entity with entity.credential.data.access_token / refresh_token. The test asserted this and it passed.
• GET /api/integrations (v1) and GET /api/v2/integrations. GetIntegrationsForUser.toDto (integrations/use-cases/get-integrations-for-user.js:69-98) embeds entities from findEntitiesByIds, which also populates the credential. v1 mapIntegrationClassToIntegrationDTO passes them through (map-integration-dto.js:12), and so does v2 toIntegrationDto (management-api/v2/dto.js, entities: integration.entities ?? []). So "v2 masks credentials" holds only for v2 entity responses. v2 integration responses leak the same way. (The same toIntegrationDto is on feat: Management API v2, /api/meta, v1 deprecation and the locked-down entity proxy (ADR-052, ADR-053) #671.)

Latent: GET /api/entities/:entityId

• GetModule.execute (modules/use-cases/get-module.js:69-76) returns credential: module.credential, which is the full decrypted record. Today this route 500s before it gets there: Module.getEntityModelFromDefinition (get-module.js:49) is not defined anywhere (typeof Module.getEntityModelFromDefinition === 'undefined' on this head). The tests that cover it mock the static. Once the static exists (fix(devtools): route /api/entity and /api/entities to the integration router #667 adds the missing piece), the member gets credential.data.refresh_token. The test asserted that too.

Minimal fix (recommended before ownership scopes merge)

1. Add one shared mapper, e.g. modules/utils/public-entity.js → toPublicEntity(entity). It returns the entity without credential, plus credentialId and authIsValid, the same fields v2's toEntityDto exposes.
2. Use it in mapModuleClassToModuleDTO (entity: toPublicEntity(...), which already has credentialId), in GetModule (replace credential: with credentialId + authIsValid), in mapIntegrationClassToIntegrationDTO (entities.map(toPublicEntity)), and in v2 toIntegrationDto.
3. Apply it to every caller, not only members. An owner has no need for their own refresh token over HTTP either, and one rule is easier to test. The only in-repo consumer I found reads result.credential?.id from the authorize response (packages/ui/lib/api/api.js:267), which is a different route.
4. Add a regression test: an org member lists entities and integrations, and asserts that no access_token / refresh_token / data appears anywhere in the JSON.

🤖 Generated with Claude Code

[seanspeaks]

Confirmed, and fixed in 451c957b (pushing now).

What leaked (reproduced by the new test on the previous commit):

• v1 GET /api/integrations: in entities.authorized, the entity record came from mapModuleClassToModuleDTO.
• v1 GET /api/integrations and v2 GET /api/v2/integrations: the integration DTOs embedded the entities from findEntitiesByIds.
• v1 GET /api/entities/:id: GetModule returned module.credential.

Fix: one shared toPublicEntity in modules/utils/public-entity.js.

• It keeps a fixed set of descriptive fields and reduces the credential to credentialId and authIsValid, for every caller including the owner.
• It is used by:
  • the module DTO;
  • GetModule;
  • the v1 integration DTO;
  • v2 toIntegrationDto;
  • v1 GET /api/integrations/:id;
  • the POST /api/entity response.

#667: this branch doesn't contain it, and its CreateEntityFromCredential differs from #667's, so I didn't rebase.

• I ported findModuleDefinitionForEntity unchanged from f74cf3b. GetModule, TestModuleAuth, GetEntityOptionsById and RefreshEntityOptions no longer call the missing Module.getEntityModelFromDefinition.
• GET /api/entities/:id answers 200 again.

Test: management-api/credential-exposure.test.js uses the real v1 and v2 routers and use cases.

• The repositories attach the decrypted credential, as the real ones do.
• It signs in as a member of the organization that owns the connection.
• It calls:
  • v1 /api/integrations, /api/integrations/:id and /api/entities/:id;
  • v2 /api/v2/entities, /entities/:id, /integrations and /integrations/:id.
• It asserts no access_token, refresh_token, api_key, id_token or client_secret value or key, and no credential object, appears in any body.
• It also asserts the connection is present, so a 404 or an empty list can't pass.

Mutation checks:

• Undoing the module DTO, the v1 integration DTO or GetModule each fails it.
• Undoing the v2 toIntegrationDto is caught by a new unit test in dto.test.js. In the router test that layer is covered twice, so the router test alone doesn't catch it.

Wider run: the modules, integrations, management-api, handlers, user and credential suites fail the same 61 tests by name as before, with 12 more passing.

---

Generated by Claude Code

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[gitguardian]

⚠️ GitGuardian has uncovered 4 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
38932763	Triggered	Generic High Entropy Secret	451c957	packages/core/management-api/credential-exposure.test.js	View secret
38932765	Triggered	Generic High Entropy Secret	451c957	packages/core/management-api/credential-exposure.test.js	View secret
38932766	Triggered	Generic High Entropy Secret	451c957	packages/core/management-api/credential-exposure.test.js	View secret
38932764	Triggered	Generic High Entropy Secret	451c957	packages/core/management-api/credential-exposure.test.js	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[sonarqubecloud]

Quality Gate passed

Issues
12 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.5% Duplication on New Code

See analysis details on SonarQube Cloud