@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.588657b.0

package/CHANGELOG.md

@@ -1,14 +1,3 @@
-# Unreleased
-
-#### 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

@@ -332,12 +332,14 @@ 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
@@ -500,6 +502,29 @@ 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.
@@ -750,6 +775,9 @@ 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,6 +305,7 @@ 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
@@ -352,6 +353,110 @@ 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/integration-commands.js

@@ -18,7 +18,7 @@ const {
     ListIntegrationsByEntityExternalIdUseCase,
 } = require('../../integrations/use-cases/list-integrations-by-entity-external-id');
 const {
-    GetIntegrationsForUser,
+    GetIntegrationsByUserId,
 } = require('../../integrations/use-cases/get-integrations-for-user');
 const {
     CreateIntegration,
@@ -152,7 +152,7 @@ function createIntegrationCommands({ integrationClass, moduleDefinitions } = {})
             moduleRepository,
         });
 
-    const getIntegrationsForUserUseCase = new GetIntegrationsForUser({
+    const getIntegrationsForUserUseCase = new GetIntegrationsByUserId({
         integrationRepository,
         integrationClasses: [integrationClass],
         moduleFactory,

package/application/commands/scheduler-commands.js

@@ -121,17 +121,19 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                     throw error;
                 }
 
-                if (!queueUrl) {
+                // 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) {
                     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`
@@ -157,7 +159,9 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                 const result = await service.scheduleOneTime({
                     scheduleName: jobId,
                     scheduleAt: scheduledAt,
-                    queueResourceId: queueArn,
+                    queueResourceId: resolvesOwnTarget
+                        ? service.toQueueResourceId(queueUrl)
+                        : deriveArnFromQueueUrl(queueUrl),
                     payload: sqsPayload,
                 });
 

package/application/commands/user-commands.js

@@ -1,6 +1,12 @@
 const {
     createUserRepository,
 } = require('../../user/repositories/user-repository-factory');
+const {
+    createOrganizationMembershipRepository,
+} = require('../../user/repositories/organization-membership-repository-factory');
+const {
+    FindIndividualUsersByOrganization,
+} = require('../../user/use-cases/find-individual-users-by-organization');
 
 const ERROR_CODE_MAP = {
     USER_NOT_FOUND: 404,
@@ -26,6 +32,12 @@ function mapErrorToResponse(error) {
  */
 function createUserCommands() {
     const userRepository = createUserRepository();
+    const findIndividualUsersByOrganization =
+        new FindIndividualUsersByOrganization({
+            userRepository,
+            organizationMembershipRepository:
+                createOrganizationMembershipRepository(),
+        });
 
     return {
         /**
@@ -170,7 +182,8 @@ function createUserCommands() {
         },
 
         /**
-         * Find all individual users linked to an organization user
+         * Find all individual users who belong to an organization user: those with
+         * a membership and those the legacy organizationId pointer places there.
          * @param {string} organizationUserId - Organization user ID to search for
          * @returns {Promise<Object[]>} Array of individual user objects (empty if none)
          */
@@ -182,10 +195,9 @@ function createUserCommands() {
                     throw error;
                 }
 
-                const users =
-                    await userRepository.findIndividualUsersByOrganizationId(
-                        organizationUserId
-                    );
+                const users = await findIndividualUsersByOrganization.execute(
+                    organizationUserId
+                );
 
                 return (users || []).map((user) => ({
                     id: user._id?.toString() || user.id,

package/core/Worker.js

@@ -1,4 +1,3 @@
-const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
@@ -6,18 +5,44 @@ const { readQueueDelivery } = require('../queues/queue-delivery');
 const { runMessageScope } = require('./invocation-scope');
 const { getLogger } = require('../logs');
 
-const sqs = new SQSClient({ region: process.env.AWS_REGION });
 const log = getLogger('frigg.worker');
 
+/**
+ * Worker - queue message producer/consumer base class.
+ *
+ * Subclass and override _run(). The queue transport is behind
+ * QueueClientInterface and can be injected (friggframework/frigg#545):
+ * `new MyWorker({ queueClient })`. Unlike #545 it is not required: without
+ * one the worker uses an SqsQueueClient configured exactly as before
+ * (AWS_REGION), created on first use rather than at module load, so
+ * requiring core constructs no AWS client and a Netlify/QStash worker that
+ * only calls _run() never touches SQS.
+ */
 class Worker {
+    /**
+     * @param {Object} [options]
+     * @param {import('../queues/queue-client-interface').QueueClientInterface} [options.queueClient]
+     */
+    constructor(options = {}) {
+        this._queueClient = options.queueClient || null;
+    }
+
+    _getQueueClient() {
+        if (!this._queueClient) {
+            const { SqsQueueClient } = require('../queues/sqs-queue-client');
+            this._queueClient = new SqsQueueClient({
+                clientConfig: { region: process.env.AWS_REGION },
+            });
+        }
+        return this._queueClient;
+    }
+
     async getQueueURL(params) {
         // Passing params in because there will be multiple QueueNames
         // let params = {
         //     QueueName:  process.env.QueueName
         // };
-        const command = new GetQueueUrlCommand(params);
-        const data = await sqs.send(command);
-        return data.QueueUrl;
+        return this._getQueueClient().getQueueUrl(params);
     }
 
     async run(params, context = {}) {
@@ -91,8 +116,7 @@ class Worker {
     }
 
     async sendAsyncSQSMessage(params) {
-        const command = new SendMessageCommand(params);
-        const data = await sqs.send(command);
+        const data = await this._getQueueClient().sendMessage(params);
         return data.MessageId;
     }
 

package/core/create-handler.js

@@ -81,6 +81,15 @@ const createHandler = (optionByName = {}) => {
                     if (shouldUseDatabase) {
                         const { connectPrisma } = require('../database/prisma');
                         await connectPrisma();
+
+                        // Extension bootstraps (e.g. db-credentials swapping a
+                        // module's env for its DB loader) run once per
+                        // process, after the connect and before any request
+                        // builds a module. AWS and Netlify both reach here.
+                        const {
+                            initializeApp,
+                        } = require('../extensions/initialize-app');
+                        await initializeApp();
                     }
 
                     // Helps reuse the database connection.  Lowers response times.

package/credential/use-cases/credential-operations-for-user.js

@@ -1,10 +1,28 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+const {
+    createScopePolicy,
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+    SCOPES,
+} = require('../../modules/entity-scope');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
- * Management API v2 credential operations. A credential has no module name
- * of its own; its `type` and the entities that use it come from the
- * caller's entities. A missing or foreign credential is a 404.
+ * Management API v2 credential operations (ADR-056 §3.4, §3.6). A credential
+ * has no module name and no organization of its own:
+ *
+ * - its `type` and `entityIds` come from the entities that use it that the
+ *   caller may see, so the same person's account connected in two
+ *   organizations (one credential, two entities) lists in each organization
+ *   with that organization's entity only;
+ * - who it belongs to is its OWNER (`credential.userId`), never the entities:
+ *   a credential an individual entity and an organization entity both point at
+ *   (possible only through legacy data) is described by whoever owns the
+ *   credential, so the answer cannot change with the order the entities load;
+ * - a credential whose entities are all out of sight (another organization's)
+ *   is a 404, and one with no entities at all (its entity was deleted) is
+ *   visible to its owner only, as it was before scoping.
  */
 
 const credentialIdOf = (entity) => {
@@ -37,31 +55,82 @@ function withEntityUsage(credentials, entities) {
     });
 }
 
-/** The caller's credentials with their type and entity usage. */
+/**
+ * `{scope, owner, organizationId, access}` of a credential for this caller, or
+ * null when its owner is neither the caller nor the active organization. Built
+ * by `describeRecord` over the row a connection by this owner has: the
+ * organization of a visible entity, else the one a new entity would get.
+ */
+function credentialTenancy(credential, visibleEntities, ctx) {
+    const entityOrg = visibleEntities.find(
+        (entity) => entity.organizationId !== undefined && entity.organizationId !== null
+    )?.organizationId;
+    const organizationId =
+        entityOrg ?? (ctx.individualAcross === 'all' ? null : ctx.activeOrgId);
+    return describeRecord({ userId: credential.userId, organizationId }, ctx, 'entity');
+}
+
+/** The entities of `entities` the caller may see, each with its `tenancy`. */
+function visibleOf(entities, ctx) {
+    const visible = [];
+    for (const entity of entities || []) {
+        const tenancy = describeRecord(entity, ctx, 'entity');
+        if (tenancy) visible.push({ ...entity, tenancy });
+    }
+    return visible;
+}
+
+/**
+ * The caller's credentials with their type, the entities of them they may see
+ * and `tenancy`. Credentials with no entity at all are listed too, for the
+ * person and the active organization that own them.
+ */
 class ListCredentialsForUser {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
-    async execute(user) {
-        const userId = user.getId();
-        const [credentials, entities] = await Promise.all([
-            this.credentialRepository.findCredentialsByUserId(userId),
-            this.moduleRepository.findEntitiesByUserId(userId),
+    /** @param {{scope?: string, owner?: string}} [filters] */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const owners = [...new Set([ctx.callerId, ctx.activeOrgId].filter(Boolean))];
+        const [found, perOwner, owned] = await Promise.all([
+            this.moduleRepository.findEntitiesByOwnership(visibilityClauses(ctx, 'entity')),
+            Promise.all(owners.map((id) => this.credentialRepository.findCredentialsByUserId(id))),
+            // Every entity of those owners, in any organization: only to tell a credential
+            // with no entity at all from one used elsewhere.
+            Promise.all(owners.map((id) => this.moduleRepository.findEntitiesByUserId(id))),
         ]);
-        return withEntityUsage(credentials || [], entities);
+        const visible = visibleOf(found, ctx);
+        const usedAnywhere = new Set(owned.flat().map(credentialIdOf).filter(Boolean));
+        const listed = [];
+        for (const credential of perOwner.flat().filter(Boolean)) {
+            const id = String(credential.id);
+            const referencing = visible.filter((entity) => credentialIdOf(entity) === id);
+            if (referencing.length === 0 && usedAnywhere.has(id)) continue;
+            const tenancy = credentialTenancy(credential, referencing, ctx);
+            if (!tenancy || !matchesListFilters(tenancy, filters)) continue;
+            listed.push({ ...withEntityUsage([credential], referencing)[0], tenancy });
+        }
+        return listed;
     }
 }
 
-/** One credential the caller owns, with its type and entity usage. */
+/** One credential the caller may see: see the header. 404 otherwise. */
 class GetCredentialForUserV2 {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
     async execute(credentialId, user) {
+        const notFound = () =>
+            Boom.notFound(`Credential ${credentialId} not found`, {
+                code: 'CREDENTIAL_NOT_FOUND',
+            });
         let credential = null;
         try {
             credential = await this.credentialRepository.findCredentialById(
@@ -72,22 +141,29 @@ class GetCredentialForUserV2 {
                 throw error;
             }
         }
-        if (!credential || !userOwns(user, credential.userId)) {
-            throw Boom.notFound(`Credential ${credentialId} not found`, {
-                code: 'CREDENTIAL_NOT_FOUND',
-            });
-        }
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            credential.userId
-        );
-        return withEntityUsage([credential], entities)[0];
+        if (!credential) throw notFound();
+        const ctx = this.scopePolicy.accessContext(user);
+
+        const referencing =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        const visible = visibleOf(referencing, ctx);
+        if (referencing.length > 0 && visible.length === 0) throw notFound();
+        const tenancy = credentialTenancy(credential, visible, ctx);
+        if (!tenancy) throw notFound();
+        return { ...withEntityUsage([credential], visible)[0], tenancy };
     }
 }
 
 /**
- * Deletes a credential the caller owns. The entities that used it stay, with
- * their credential unset, so they show as needing re-authorization rather
+ * Deletes a credential the caller may manage. The entities that used it stay,
+ * with their credential unset, so they show as needing re-authorization rather
  * than disappearing from integrations.
+ *
+ * Refuses with 409 `CREDENTIAL_SHARED` while an entity the caller cannot see
+ * still uses it: one credential row serves the same provider account in every
+ * organization, and deleting it from one would break the other. The message
+ * says nothing about the other connections (not even how many): remove the
+ * entities that use it, and it goes with the last one.
  */
 class DeleteCredentialForUser {
     constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
@@ -101,6 +177,15 @@ class DeleteCredentialForUser {
             credentialId,
             user
         );
+        assertCanManage(credential.tenancy.access, `credential ${credential.id}`);
+        const usedBy =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        if (usedBy.length > credential.entityIds.length) {
+            throw Boom.conflict(
+                `Credential ${credential.id} is still in use by other connections and cannot be deleted from here`,
+                { code: 'CREDENTIAL_SHARED' }
+            );
+        }
         for (const entityId of credential.entityIds) {
             await this.moduleRepository.unsetCredential(entityId);
         }

package/credential/use-cases/reauthorize-credential-for-user.js

@@ -1,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
  * Re-authorization of a credential the caller owns (Management API v2). It
@@ -14,7 +15,13 @@ async function credentialEntityType(getCredentialForUser, credentialId, user) {
             { code: 'CREDENTIAL_TYPE_UNKNOWN' }
         );
     }
-    return { entityType: credential.type, credentialId: String(credential.id) };
+    return {
+        entityType: credential.type,
+        credentialId: String(credential.id),
+        // A re-authorization keeps the scope the connection already has.
+        fixedScope: credential.tenancy?.scope,
+        access: credential.tenancy?.access,
+    };
 }
 
 /** GET /api/v2/credentials/:credentialId/reauthorize */
@@ -25,14 +32,12 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const binding = await credentialEntityType(
-            this.getCredentialForUser,
-            credentialId,
-            user
-        );
+        const { entityType, credentialId: boundCredentialId } =
+            await credentialEntityType(this.getCredentialForUser, credentialId, user);
         return this.getAuthorizationStep.execute({
             user,
-            ...binding,
+            entityType,
+            credentialId: boundCredentialId,
             step,
             sessionId,
             state,
@@ -48,11 +53,13 @@ class ReauthorizeCredentialForUser {
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const binding = await credentialEntityType(
+        const { access, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
         );
+        // A credential an organization owns: the organization's admins only.
+        assertCanManage(access, `credential ${credentialId}`);
         return this.submitAuthorizationStep.execute({
             user,
             ...binding,