[seanspeaks]

Stacked on #670 (ADR-056). Driven by Left Hook's internal MCP server, where each staff member connects their own Google, Xero and HubSpot in an organization-primary Frigg app, with no integration around those connections.

ADR-056 §3, new subsections

• §3.1 Where a scope comes from. Scope resolves request → binding → integration → app entity type → app → default. The most specific level that sets one wins; nothing intersects. The default follows user.primary, so apps that set nothing keep today's meaning.
• §3.2 Ownership is decided by scope, not user.primary. Today an x-frigg-appuserid-only request to an org-primary app resolves to an undefined owner. A request missing the identity its scope needs now gets a 400.
• §3.3 Integration ownership can be set explicitly. An organization-owned integration may not bind an individual entity.
• §3.4 Lists say whose each record is. /api/v2/entities, /credentials and /integrations return mixed ownership, and each record carries scope, owner, organizationId and access.
• §3.5 Entity proxy (ADR-052). It accepts only the scopes in managementApi.proxy.scopes, default ['individual'].
• §3.6 A user may belong to several organizations. This fixes a defect. GetUserFromXFriggHeaders re-links an individual to whichever org a request names, because membership is a single organizationId column, so a person in two orgs flips membership on every request.
  • Membership becomes its own relation, with orgRole.
  • Each request has one active organization.
  • Individual entities and integrations are paired with the organization they were created in, which reverses §3's earlier "no organizationId column".
  • Lists are scoped to the active organization.

ADR-059 (new)

• Adds an optional appDefinition.entities map, keyed by entity type name and merged with today's inference from integrations. Entities can then exist without an integration: agents and MCP servers, connect-first products, global entities.
• One getEntityTypeRegistry replaces the five call sites that derive module definitions from integrations: router, backend-utils, app-definition-loader, encryption schema registry and health. The encryption schema therefore covers registry-only types.
• $infer: false makes registration required for apps that want one explicit list.

Review

Daniel. These are the decisions the stacked implementation PRs follow, so comments here change those PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HyrF4oqcTdK2AtvcrocxE6

---

Generated by Claude Code

---

Note

Low Risk
Documentation-only ADR updates; no runtime code changes in this PR, though accepted decisions will drive substantial 2.1 auth and schema work later.

Overview
ADR-056 is revised (2026-10-15) by folding former ADR-058 into Decision §3 as §3.1–§3.6, so tenancy, scope resolution, and multi-org behavior are one document.

§3.1–§3.5 specify how scope is resolved (request → binding → integration → app entity type → app → default), that ownership follows resolved scope instead of user.getId() / user.primary, optional explicit integration ownership, v2 list payloads with scope / owner / organizationId / access, and entity-proxy scope defaults via managementApi.proxy.scopes.

§3.6 replaces single-column org membership with OrganizationMembership, per-request active org, and organizationId on Entity and Integration (reversing the earlier “no organizationId on Entity” note). orgRole moves to membership; org-admin rules differ by auth mode. Integration mixed-scope ownership rows are marked deferred for 2.1’s first cut (400 MIXED_ENTITY_SCOPES, global entities 404 on tenant API).

ADR-059 (new) adds an optional appDefinition.entities registry merged with today’s integration inference, getEntityTypeRegistry to replace five derivation call sites, optional $infer: false, and v2 /api/v2/entity-types plus authorize without an integration.

The ADR index lists ADR-056’s revision date and ADR-059.

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

[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]

Legacy membership cannot be revoked

High Severity

User.organizationId is a permanent implicit membership and is never moved, while OrganizationMembership has no removed state. Leaving the first organization has nothing to delete, and deleting a later row for that org makes the implicit membership apply again. The original org membership therefore comes back after removal.

Additional Locations (1)

• docs/architecture-decisions/056-app-profiles-tenancy-entity-scopes.md#L313-L332

 

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

[cursor]

List rules drop admin visibility

Medium Severity

§3.4 returns every record the caller may see under the permissions table, including an org admin's view access to other members' individual entities. §3.6 then restricts both lists and access checks to individual entities whose owner is the caller. An admin's metadata access and the view access value cannot both be implemented.

Additional Locations (2)

• docs/architecture-decisions/056-app-profiles-tenancy-entity-scopes.md#L403-L413
• docs/architecture-decisions/056-app-profiles-tenancy-entity-scopes.md#L275-L280

 

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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

[cursor]

Stored role outlives IdP demotion

Medium Severity

An adopter JWT role claim wins so an IdP demotion applies on that request, but the membership row keeps the first token's role and is the fallback whenever a later token omits the claim. A demoted caller who next presents a silent token is authorized as their original role again.

 

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

[seanspeaks]

ADR reconciliation needed after Stack A/B — drafted with Claude Code at Sean's request

Severity: must-reconcile. The scope vocabulary (individual|organization|global), the ownership table, ORPHANED and visible(context) are consistent with #670. These items are not:

ADR-056

• §2 vs feat(core): adopter-token (JWT) authentication #678. §2 specifies user.jwt.claims: { userId, orgId, role } and linking "through organizationId". feat(core): adopter-token (JWT) authentication #678 ships user.jwtConfig (jwksUri or secret, issuer, audience, algorithms, clockToleranceSec, userIdClaim/orgIdClaim/roleClaim, defaults sub/org_id/org_role), and §3.6 replaces linking with OrganizationMembership. Update §2 to the shipped keys and point it at §3.6.
• §3.5 needs ADR-052 to change. 052 §3 ("the entity's organisation must match the caller's") is still the rule in docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668. Please add the matching 052 amendment there (proposed on docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668): use access in the active organization, plus managementApi.proxy.scopes.
• §3.6 GET /api/v2/me/organizations is not in feat: Management API v2, /api/meta, v1 deprecation and the locked-down entity proxy (ADR-052, ADR-053) #671's route registry and no Stack A PR adds it. Mark it deferred, or register it in feat(core): organization memberships, one active org per request (ADR-056 §3.6) #681 (ADR-053: every v2 path goes through the registry).
• §3.1 levels 2–3 cover use(...) and Definition.*. Data-defined integrations (ADR-063, docs(adr): ADR-063 integration definitions as data #692) have no binding scope or ownership field yet. Add a row, or a note that 063 must map modules.<key> to level 2.
• Bearer tokens and ADR-034. §3.6 lets a Frigg bearer token manage org-level records unless orgAdminGateBearerTokens. ADR-034's API-key login (docs(adr): reconcile the register — 13 unmerged ADRs into one contiguous sequence #644/feat(core): API-key login auth mode (module-validated) #643) mints a Frigg session token from POST /user/login; if that is treated as a bearer token, every API-key login can manage by default. State which rule applies to 034 sessions (recommended: gated, with MEMBER unless the identity module reports a role).
• ADR-058 is cited as folded in. Add "058 — withdrawn, folded into 056" to the register so the number is not reused.

ADR-059

• §4 says GET /api/v2/entity-types. The registry serves GET /api/v2/entities/types[/:entityType[/requirements]]. Fix the text.
• Open question 1 (named entries, twilio:marketing) overlaps ADR-063's forward reference to an unwritten "ADR-062 per-app module instances" and feat(core): several named proxy base URLs per module (F8) #690's named proxy bases. Either 059 owns module instances, or 062 is written and cross-referenced.
• entities, ownership, user.strictMembership, user.orgAdminRoles, user.orgAdminGateBearerTokens, managementApi.proxy.scopes must also land in ADR-051's schema (feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666) (see there).

Merge order: this PR merges into adr/056-app-profiles before #670 merges. #668's 052 amendment comes before #685.