Secret management in Executor is handled by a suite of plugins that implement the CredentialProvider interface. These plugins allow the system to securely store and retrieve sensitive information like API tokens and OAuth client secrets across different environments, ranging from local development to cloud-scale deployments.
In the v2 architecture, credential providers interact with opaque ProviderItemId keys. The multi-tenancy partitioning (Tenant, Owner, Subject) is managed at the Connection layer, while the providers focus on the physical storage and retrieval of the raw secret strings packages/plugins/file-secrets/src/index.ts38-43
All secret plugins contribute to the credentialProviders array during plugin registration packages/plugins/keychain/src/index.ts80-95 A provider typically implements:
get(id): Retrieves a secret by its unique ID.set(id, value): Persists a secret (if writable: true).has(id): Checks for existence without returning the value.delete(id): Removes a secret.Sources: packages/plugins/file-secrets/src/index.ts138-166 packages/plugins/keychain/src/provider.ts40-55
The keychain plugin provides integration with OS-native credential stores (macOS Keychain, Windows Credential Manager, and Linux Secret Service) via the keyring package.
The plugin uses napi-rs/keyring for native bindings. Because bun build --compile does not bundle .node files into the binary filesystem, the CLI build process copies the platform-specific .node file next to the binary, and the plugin loads it via EXECUTOR_KEYRING_NATIVE_PATH apps/cli/src/build.ts126-134 packages/plugins/keychain/src/keyring.ts46-54
To prevent registration on systems where a keyring is technically supported but unreachable (e.g., headless Linux or WSL2 without a DBus session), the plugin performs a "write-then-delete" probe using a sentinel account packages/plugins/keychain/src/index.ts15-23 If the probe fails, the provider is not registered packages/plugins/keychain/src/index.ts81-94
The following diagram shows how a secret request flows from the SDK through the native bridge.
Diagram: Keychain Native Resolution Flow
Sources: packages/plugins/keychain/src/index.ts74-95 packages/plugins/keychain/src/provider.ts40-55 packages/plugins/keychain/src/keyring.ts91-100
The file-secrets plugin is the default provider for local environments. It stores secrets in a flat JSON file, typically following XDG-compliant paths.
~/.local/share/executor/auth.json on Linux/macOS or AppData/Local/executor/auth.json on Windows packages/plugins/file-secrets/src/index.ts19-330o700 and files with 0o600 to ensure only the current user can read them packages/plugins/file-secrets/src/index.ts91-101.tmp file and then renames it to prevent corruption during crashes packages/plugins/file-secrets/src/index.ts98-105The storage is a simple Record<string, string> where keys are ProviderItemId strings packages/plugins/file-secrets/src/index.ts45-46
Sources: packages/plugins/file-secrets/src/index.ts17-107
The onepassword plugin integrates with 1Password via two backends: the 1Password SDK (native IPC) and the 1Password CLI (op command).
The plugin attempts to use the native SDK first but provides a fallback to the CLI backend if the SDK module fails to load or if the environment lacks the necessary WASM/native dependencies packages/plugins/onepassword/src/sdk/service.ts89-101 packages/plugins/onepassword/src/sdk/service.test.ts51-74
The SDK requires a core WASM file (onepassword-core_bg.wasm). The CLI build script explicitly resolves and copies this file to ensure it is available to the compiled binary apps/cli/src/build.ts26-34 apps/desktop/scripts/smoke-sidecar.ts42-51
| Code Entity | Role |
|---|---|
OnePasswordService | Interface for resolving secrets and listing vaults/items packages/plugins/onepassword/src/sdk/service.ts21-32 |
makeNativeSdkService | Implements the service using @1password/sdk packages/plugins/onepassword/src/sdk/service.ts126-175 |
ResolvedAuth | Discriminated union for desktop-app or service-account auth packages/plugins/onepassword/src/sdk/service.ts43-45 |
Sources: packages/plugins/onepassword/src/sdk/service.ts11-175
The workos-vault plugin is designed for multi-tenant cloud environments. It provides cryptographically isolated secret storage using WorkOS Vault.
WorkOS provisions a Key Encryption Key (KEK) per distinct context. The plugin maps the Executor's multi-tenancy model onto these contexts:
WorkosVaultStore (backed by standard pluginStorage) to keep track of metadata and allow listing of secrets packages/plugins/workos-vault/src/sdk/secret-store.ts122-135WorkOS creates KEKs just-in-time. To handle the race condition where a KEK is created but not yet ready for immediate use, the client implements a retry loop with backoff packages/plugins/workos-vault/src/sdk/secret-store.ts25-31
Diagram: WorkOS Vault Entity Mapping
Sources: packages/plugins/workos-vault/src/sdk/secret-store.ts21-135 packages/plugins/workos-vault/src/sdk/client.ts9-21
The encrypted-secrets plugin (often used in tandem with the Cloud host) provides a layer of application-level encryption before secrets are passed to a storage provider. This ensures that even if the underlying database or file is compromised, the secrets remain encrypted without the master key.
(Note: Implementation details for encrypted-secrets follow the standard CredentialProvider pattern but utilize a Cipher interface for transformation.)
Sources: packages/plugins/workos-vault/src/sdk/secret-store.ts33-40 (contextual pattern)
Refresh this wiki