feat(core): Introduce CredentialDependency entity to track credential dependencies

[alielkhateeb]

Summary

Introduces a new CredentialDependency entity and supporting infrastructure to track which external secret providers a credential depends on.

https://www.loom.com/share/27e084b98d7945aeb4308a1de505de0a

Changes

• New CredentialDependency entity (packages/@n8n/db): Stores credentialId, dependencyType (externalSecretProvider), and dependencyId with a unique constraint and cascade delete on credential removal.
• DB migration (1773000000000-CreateCredentialDependencyTable): Creates the credential_dependency table for both SQLite and PostgreSQL.
• New CredentialDependencyRepository: Provides findCredentialIdsByDependencyId, upsertDependenciesForCredential, and syncDependenciesForCredential methods.
• Updated CredentialsService: Parses credential data on create/update to extract and persist external secret provider dependencies.
• Updated validation.ts: Adds helpers to extract dependency IDs from credential values.
• Updated repositories for CredentialsRepository and SecretsProviderConnectionRepository to support dependency-aware queries.
• Tests: Updated and extended tests for CredentialsService, CredentialsController, and the public API credentials service.

How to test

Create flow

1. Create a credential that references an external secret provider value (e.g. ={{ $secrets.myVault.myKey }}).
2. Verify a row is created in credential_dependency with dependencyType = 'externalSecretProvider'.

Update flow

3. Update the credential to add a new external secret provider reference — verify a new dependency row is inserted.
4. Update the credential to remove an existing external secret provider reference — verify the corresponding dependency row is deleted.
5. Update the credential to swap one external secret provider reference for another — verify the old row is removed and the new one is inserted.
6. Update the credential without changing any references — verify the dependency rows are unchanged.

Delete flow

7. Delete the credential and verify all associated dependency rows are cascade-deleted.

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/LIGO-230/be-switch-to-index-based-query-for-getting-all-credentials-referencing

Review / Merge checklist

• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)

[codecov]

Codecov Report

❌ Patch coverage is 65.23297% with 97 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...n/1773000000000-CreateCredentialDependencyTable.ts	7.86%	82 Missing ⚠️
...@n8n/db/src/repositories/credentials.repository.ts	79.16%	5 Missing ⚠️
...ackages/cli/src/credentials/credentials.service.ts	82.14%	2 Missing and 3 partials ⚠️
...s/project-secrets-provider-access.repository.ee.ts	33.33%	2 Missing ⚠️
...i/src/credentials/credential-dependency.service.ts	96.55%	0 Missing and 1 partial ⚠️
...ages/cli/src/credentials/external-secrets.utils.ts	96.77%	1 Missing ⚠️
...ets.ee/secrets-providers-connections.service.ee.ts	93.33%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[alielkhateeb]

Sort of a duplicate of

n8n/packages/cli/src/credentials/validation.ts

Line 16 in 7a73194

const PROVIDER_KEY_PATTERN = '[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*';

but since migrations should be self-contained I created a new one here

[alielkhateeb]

The utilities in this file might give the impression of duplicate code, that's because it is duplicate code 😂 somehow

Usually migrations are meant to be self contained with minimal dependencies to avoid breaking when business logic change over time, if this is not the right way here at n8n I'm happy to amend and reuse the existing utility methods :)

[konstantintieber]

I think it's good that migrations don't import code but rather duplicate it 👍
I wouldn't want the behaviour of the migration to change if we change the util implementation in the future (or at least I wouldn't expect as a dev that changing a function in our code will affect a migration that was built in the past).

[alielkhateeb]

@konstantintieber Awesome, thanks for reassuring me 🫶

[cubic-dev-ai]

1 issue found across 18 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/@n8n/db/src/repositories/credentials.repository.ts">

<violation number="1" location="packages/@n8n/db/src/repositories/credentials.repository.ts:302">
P1: According to linked Linear issue LIGO-230, this path must handle filtering across ~120k credential IDs. Expanding `credentialIds` into `IN (:...credentialIds)` can exceed DB parameter limits (and degrade heavily before that), causing large queries to fail rather than scale.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant U as User/Client
    participant Ctrl as CredentialsController
    participant Svc as CredentialsService
    participant V as Validation/Helpers
    participant SecRepo as SecretsProviderConnectionRepo
    participant DepRepo as CredentialDependencyRepo
    participant CredRepo as CredentialsRepo
    participant DB as Database

    Note over U,DB: Flow: Create or Update Credential with Secret References

    U->>Ctrl: POST/PATCH /credentials (data: "{{ $secrets.vault.key }}")
    Ctrl->>Svc: update() / save()
    
    Svc->>V: NEW: extractExternalSecretProviderKeys(decryptedData)
    V-->>Svc: ['vault']
    
    Svc->>SecRepo: NEW: findIdsByProviderKeys(['vault'])
    SecRepo-->>Svc: ['provider-uuid-123']

    rect rgb(30, 41, 59)
        Note right of Svc: Transaction Started
        Svc->>CredRepo: Save/Update Credential Entity
        CredRepo->>DB: INSERT/UPDATE credentials_entity
        
        Svc->>DepRepo: NEW: syncDependenciesForCredential(credId, ['provider-uuid-123'])
        DepRepo->>DB: DELETE removed / INSERT NEW dependencies
        Note right of DB: Table: credential_dependency
    end

    Svc-->>Ctrl: Updated Credential
    Ctrl-->>U: 200/201 Response

    Note over U,DB: Flow: List Credentials filtered by Secret Provider

    U->>Ctrl: GET /credentials?externalSecretsStore=vault
    Ctrl->>Svc: getMany(filter: { externalSecretsStore: 'vault' })

    Svc->>SecRepo: NEW: findIdByProviderKey('vault')
    SecRepo-->>Svc: 'provider-uuid-123'

    Svc->>DepRepo: NEW: findCredentialIdsByDependencyId('provider-uuid-123')
    DepRepo-->>Svc: ['cred-id-A', 'cred-id-B']

    alt Found matching IDs
        Svc->>CredRepo: CHANGED: getManyAndCountWithSharingSubquery(credentialIds: [...])
        CredRepo->>DB: SELECT * FROM credentials_entity WHERE id IN (...)
        DB-->>CredRepo: Rows
        CredRepo-->>Svc: Credentials[]
    else No matches
        Svc-->>Ctrl: []
    end

    Svc-->>Ctrl: Enriched Credentials
    Ctrl-->>U: JSON List

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[alielkhateeb]

wrapping update in transaction now so the dependency sync is atomic with the credential update

[ireneea]

❤️ Love this refactoring

[cubic-dev-ai]

1 issue found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/credentials/external-secrets.utils.ts">

<violation number="1" location="packages/cli/src/credentials/external-secrets.utils.ts:43">
P2: Dot-notation provider regex can extract partial provider IDs, causing incorrect dependency mapping.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[konstantintieber]

Should we throw an error here telling the user that we couldn't query by the provided external secret provider key, because no secret provider with that key exists?

[alielkhateeb]

@konstantintieber I would see this as a filter, so if the secret provider doesn't exist we return an empty array, just like searching a list of items by a keyword that matches nothing

But I definitely see a potential refactoring here, basically the params aren't clear, I'll amend and send the commit hash here for another round and to get your opinion

[konstantintieber]

Yeah you're right. a "get many credentials" endpoint is likely not the place to validate that the external secret provider key that was passed in has a match in our db.

We're essentially saying: if you're looking for credentials that use a vault that doesn't exist, then you also won't find any credentials 👍

[alielkhateeb]

59176ed I think this makes the filter more explicit, IMO, what do u think?

[konstantintieber]

Hmm I'm indecisive on that one. Is includeGlobal not a filter? Classic naming things...

[konstantintieber]

Found one thing: when I delete a secrets vault that is used in a credential, any rows in credential_dependency that reference this deleted secret vault are not cleaned up.
The credential_dependency row is only deleted when the associated credential is deleted.

EDIT:
maybe we should not go for the combination of dependencyType and dependencyId after all, since that way won't allow us to use foreign keys.
We can cascade deletes of secret vaults on the credential_dependency table if we change the schema to this:

@Column({ type: 'int' }) // today, this will not be nullable, but in the future, if we have another dependency column, it may be
secretsProviderConnectionId: number;

@ManyToOne('SecretsProviderConnection', { onDelete: 'CASCADE' })
@JoinColumn({ name: 'secretsProviderConnectionId' })
secretsProviderConnection: Relation<SecretsProviderConnection>;

If we stick to the current schema, we could also add a call to a method like CredentialDependencyRepository.deleteOnDependencyDelete({ type: CredentialDependencyType, dependencyId: string }) inside SecretsProviderConnectionsService.deleteConnection to unblock the current PR (and maybe even keep it that way 🤷 )

[konstantintieber]

Nit: While I'm fine with the dependencyId, the existing WorkflowDependency entity calls this dependencyKey

[konstantintieber]

That might be specific to the fact that a workflow has more varied kinds of dependencies though (e.g. node type).

[alielkhateeb]

Initially I had it as dependencyKey to follow the same as workflowDepdency and I've given this a thought, and I didn't want people to mistakenly insert providerKey instead of secretConnectionId, this is the only reason why I went with dependencyId rather than dependencyKey

[konstantintieber]

Good call 👍

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/credentials/credentials.controller.ts">

<violation number="1" location="packages/cli/src/credentials/credentials.controller.ts:79">
P2: Add a controller test that asserts `getMany()` forwards `externalSecretsStore` under `filters`. Without that coverage, this request-shape change can regress while the service tests still pass.

(Based on your team's feedback about controller unit tests for query-shape changes.) [FEEDBACK_USED]</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Add a controller test that asserts getMany() forwards externalSecretsStore under filters. Without that coverage, this request-shape change can regress while the service tests still pass.

(Based on your team's feedback about controller unit tests for query-shape changes.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/credentials/credentials.controller.ts, line 79:

<comment>Add a controller test that asserts `getMany()` forwards `externalSecretsStore` under `filters`. Without that coverage, this request-shape change can regress while the service tests still pass.

(Based on your team's feedback about controller unit tests for query-shape changes.) </comment>

<file context>
@@ -75,7 +75,9 @@ export class CredentialsController {
 			includeGlobal: query.includeGlobal,
-			externalSecretsStore: query.externalSecretsStore,
+			filters: {
+				externalSecretsStore: query.externalSecretsStore,
+			},
 		});
</file context>

[alielkhateeb]

@konstantintieber Really good observation, I have missed that one
I will fix it right after eating 😂

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts">

<violation number="1" location="packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts:210">
P0: Custom agent: **Security Review**

**Missing connection deletion**: `deleteConnectionForProject` never actually removes the connection entity from the database. The old `removeByProviderKeyAndProjectId` was replaced with `findByProviderKeyAndProjectId`, but `entityManager.remove(connection)` was never added to the transaction (unlike the correctly-implemented `deleteConnection` method above). This means external secrets provider connections with encrypted vault credentials will persist in the DB after a user tries to delete them.</violation>

<violation number="2" location="packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts:503">
P2: Custom agent: **Quality & Performance Review**

**Duplicate project access deletion**: Both `entityManager.delete(this.projectAccessRepository.target, { secretsProviderConnectionId: connectionId })` and `this.projectAccessRepository.deleteByConnectionId(connectionId, entityManager)` delete the same project access rows within the same transaction. One of these should be removed. The `deleteConnection` method above only uses `deleteByConnectionId`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts">

<violation number="1" location="packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts:213">
P1: `deleteConnectionForProject()` lost transactional atomicity for multi-table deletes, so partial failures can corrupt dependency/access state.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: deleteConnectionForProject() lost transactional atomicity for multi-table deletes, so partial failures can corrupt dependency/access state.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/modules/external-secrets.ee/secrets-providers-connections.service.ee.ts, line 213:

<comment>`deleteConnectionForProject()` lost transactional atomicity for multi-table deletes, so partial failures can corrupt dependency/access state.</comment>

<file context>
@@ -209,12 +210,12 @@ export class SecretsProvidersConnectionsService {
 		await this.repository.manager.transaction(async (entityManager) => {
 			await this.projectAccessRepository.deleteByConnectionId(connection.id, entityManager);
-			await this.credentialDependencyRepository.deleteByDependency({
+			await this.credentialDependencyService.deleteDependencyById({
 				dependencyType: EXTERNAL_SECRET_PROVIDER_DEPENDENCY_TYPE,
 				dependencyId,
</file context>

[alielkhateeb]

How did deleteConnectionForProject lose transactional atomicity? In this PR this is unchanged compared to master isn't it?

[cubic-dev-ai]

Thanks for flagging that—I'll recheck the diff to confirm whether anything changed in deleteConnectionForProject; if it’s unchanged from master, I’ll update or withdraw the comment accordingly.

[konstantintieber]

I think what this bot means is that these three statements should be in one transaction:

await this.credentialDependencyService.deleteDependencyById({
	dependencyType: EXTERNAL_SECRET_PROVIDER_DEPENDENCY_TYPE,
	dependencyId: connectionId.toString(),
});
await this.projectAccessRepository.deleteByConnectionId(connectionId);
await this.repository.delete({ id: connectionId });

Because the first two depend on the successful deletion in the third statement.

So even on master right now, the fact that await this.projectAccessRepository.deleteByConnectionId and await this.repository.delete are not in a transaction is not our usual way of implementing this.
I also wonder why we're not using onDelete: 'cascade' on the ManyToOne project relation of ProjectSecretsProviderAccess.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

Thanks for pointing that out—looks like it’s already addressed in that change. I’ll update the review accordingly.

[cubic-dev-ai]

Thanks for the link—confirmed it’s already fixed there; I’ll mark this as resolved.

[konstantintieber]

Weird, but the bot is talking about a different piece of code. The one I mentioned is in SecretsProvidersConnectionsService.deleteConnectionForProject, while the bot commented about SecretsProvidersConnectionsService.deleteConnection 🤔

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[konstantintieber]

LGTM

[konstantintieber]

TIL how default values in JS's destructuring syntax works 👍

[guillaumejacquart]

one nit comment, but looks good, thanks 🚀

[guillaumejacquart]

Why the separate createIndex ? why not another .withIndexOn( ?

[alielkhateeb]

That’s an absolutely valid question ✅

The main reason is that I found it hard to clearly spot unique indexes when they’re defined alongside non-unique ones using withIndexOn. For example:

.withIndexOn(['credentialId'])
.withIndexOn(['dependencyType', 'dependencyId'])
.withIndexOn(['credentialId', 'dependencyType', 'dependencyId'], true);

Here, the true is quite subtle and easy to miss when scanning the code.

Since this is a migration file (and not something we expect to revisit or refactor), I preferred to make the unique index explicit. This makes it easier for reviewers and future readers to spot which index enforces uniqueness vs which ones are just for performance.

Also… the fact that you pointed it out probably means my plan worked 😂 haha

[n8n-assistant]

Got released with n8n@2.14.0