[seanspeaks]

Summary

This implements ADR-056 §3.6. A person can belong to many organizations, and each request runs as one active org: the org claim on the adopter JWT, or x-frigg-apporgid on the header path. This replaces the interim 403 multi_org_unsupported from #678, and it fixes the long-standing defect where header auth re-linked a person's single organizationId.

This is stacked on #678 (claude/internal-mcp-02-adopter-jwt).

Model and repositories

• OrganizationMembership is a new model (individualUserId, organizationUserId, orgRole default MEMBER, createdAt), unique on the pair. It is added to both Prisma schemas, with the Postgres migration 20261015000000_add_organization_membership. That migration matches prisma migrate diff; it has not been applied to any database.
• Repositories (Mongo and Postgres share an OrganizationMembershipRepositoryPrisma base; DocumentDB is separate) are atomic:
  • findMembership returns the row or null.
  • addMembership is an idempotent upsert that recovers from unique races.
  • listMembershipsForOrganization.
  • Postgres ids are parsed strictly, so '12abc' is refused.
• database/unique-violation.js holds the single isUniqueViolation check (P2002 or 11000, by code). DocumentDB insertOne now throws with code: 11000.

Domain and use cases

• Legacy pointer. user/membership.js treats a person's legacy organizationId as an implicit membership (implicitMembership). This is read-time and needs no data migration. It deviates from the ADR, which has the migration write rows; ADR-056 will be updated to match.
• EnsureOrganizationMembership. It adds the person to the active org if needed. It never overwrites organizationId, which is only set on first link, through a conditional update (linkIndividualToOrganizationIfUnset, which matches null or unset on MongoDB).
• Both auth paths take the injected ensureOrganizationMembership.
  • User.getActiveOrganizationId() returns the request's org, never the legacy pointer.
  • The x-frigg path no longer re-links. It also reads organizationId (the repositories never returned organizationUser), which makes 2 previously failing tests pass.
• strictMembership refuses any non-member of an org that existed before the request, including a brand-new appUserId. Only an org created by that same request is exempt.
  • strictUserValidation stays as a deprecated alias. It logs a warning once at construction, because its meaning has changed.
• FindIndividualUsersByOrganization. "Members of org X" now combines legacy-pointer people with membership rows, so a person in two orgs is listed in both.
• user/create-user-authentication.js builds the bearer, x-frigg and adopter use cases once. integration-router and the v2 dependencies both use it.

Not in this PR (F5)

Credentials, entities and integrations are still owned by user.getId(), which is the individual under the default primary. The active org does not scope them yet. F5 adds organizationId to Entity/Integration and scoped lists. docs/guides/organization-memberships.md says so.

Known limits

• Two concurrent first logins for a brand-new org can still create the org twice, because appOrgId has no unique index.
• On Mongo, deleting a user leaves its membership rows behind (no cascade).
• A legacy pointer can dangle after its org is deleted.
• These are documented in the guide.

Test plan

• Full packages/core run, with no-op global setup because the Mongo binaries can't run here: 14 suites and 61 tests fail, against 15 and 63 on feat(core): adopter-token (JWT) authentication #678. Compared by name, the difference is exactly the 2 x-frigg tests that now pass. 3061 pass.
• prisma validate passes for both schemas. migrate diff matches the migration.
• ESLint: 0 errors.
• Two independent reviews (spec/test and clean code), with the findings fixed. Across the rounds, 47 mutations were killed.
  • Covered: strict-mode holes, conditional pointer link per adapter (including the Mongo isSet branch), domain fallback, orgRole default, strict id parse, unique-violation codes, and compound-key name pinned against the schema files.
• Not tested against a real database: the Prisma adapters are tested against a mocked client, with the query shape asserted. F6 adds a real-Postgres isolation suite.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HyrF4oqcTdK2AtvcrocxE6

---

Generated by Claude Code

---

Note

High Risk
Changes adopter JWT and x-frigg authentication to auto-create memberships and redefines strictUserValidation; incorrect membership or strict-mode behavior could admit or deny the wrong org context.

Overview
Implements multi-organization membership (ADR-056 §3.6): each request has one active organization from the JWT org_id claim or x-frigg-appOrgId, and people can belong to several orgs without moving the legacy IndividualUser.organizationId pointer.

Adds an OrganizationMembership table/model (Postgres migration + both Prisma schemas), repositories for Postgres/Mongo/DocumentDB, and EnsureOrganizationMembership wired into adopter JWT and x-frigg auth via buildUserAuthentication. Existing users are covered by a read-time implicit membership from the legacy pointer (implicitMembership in user/membership.js), not a backfill. 403 multi_org_unsupported is removed; first-time org access creates an idempotent membership and stores orgRole from the token on first join. x-frigg stops re-linking organizationId and gains strictMembership (plus deprecated strictUserValidation as an alias) to block header-based joins to pre-existing orgs.

User.getActiveOrganizationId() reflects the request org; findIndividualUsersByOrganizationId unions membership rows with legacy-pointer users. Supporting changes include isUniqueViolation / race recovery on user create, linkIndividualToOrganizationIfUnset, and DocumentDB findManyDrained for large org lists. Docs: docs/guides/organization-memberships.md and README updates. F5 (scoping credentials/entities by active org) is explicitly out of scope.

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

📦 Published PR as canary version: 2.0.0--canary.681.2df9ef0.0

✨ Test out this PR locally via:

npm install @friggframework/admin-scripts@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/core@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/devtools@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/eslint-config@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/prettier-config@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/schemas@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/serverless-plugin@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/test@2.0.0--canary.681.2df9ef0.0
npm install @friggframework/ui@2.0.0--canary.681.2df9ef0.0
# or 
yarn add @friggframework/admin-scripts@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/core@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/devtools@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/eslint-config@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/prettier-config@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/schemas@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/serverless-plugin@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/test@2.0.0--canary.681.2df9ef0.0
yarn add @friggframework/ui@2.0.0--canary.681.2df9ef0.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]

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 ce2a674. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[cursor]

Frigg 2.0.1 review (Stack A) — COMMENT only

Verdict (would): would approve

Reviewed ADR-056 §3.6 memberships: active org from JWT / x-frigg-appOrgId, add-not-move membership, legacy organizationId as implicit membership. Cross-tenant IDOR posture is acceptable given the shared secret stays server-side.

Blocking

None for cross-tenant access assuming the BFF shared secret is not browser-exposed.

Should-fix

1. Duplicate org users for one appOrgId (race) — app-user-helpers documented race with no unique index. Concurrent first logins for the same org can create two ORGANIZATION users; later lookups pick one arbitrarily and split members/entities across “same” tenant. Add a partial unique index on (appOrgId) WHERE type = ORGANIZATION (and best-effort Mongo/DocumentDB equivalents), or transactional find-or-create with a recovery path.
2. Default non-strict header join — Any holder of the shared secret can add any appUserId to any existing org. Expected for a BFF; catastrophic if the secret reaches a browser. Product-profile scaffolds / docs should default or strongly recommend user.strictMembership: true, and state that BFFs must drop client x-frigg-* and only assert IdP-verified memberships.

Nits

• strictUserValidation alias meaning change is easy to misconfigure; keep the startup warn.

No formal approve / request-changes on this review.