The Executor OAuth system provides a centralized, multi-tenant framework for managing third-party credentials. In the v2 architecture, OAuth is a core-owned service rather than being implemented individually by plugins packages/plugins/openapi/src/sdk/oauth-refresh.test.ts6-12 The system handles the entire lifecycle: from metadata discovery and dynamic client registration (DCR) to token exchange, secure storage, and background refresh packages/core/sdk/src/oauth-service.ts5-14
The OAuthService is the runtime implementation behind executor.oauth packages/core/sdk/src/oauth-service.ts2-3 It interacts with the IFumaClient for persistence and CredentialProvider for secure token storage packages/core/sdk/src/oauth-service.ts109-112
oauth.start): Generates PKCE material (code_verifier, code_challenge) and a random state packages/core/sdk/src/oauth-service.ts11-12 It persists an oauth_session and returns an authorization URL for authorization_code grants, or exchanges credentials immediately for client_credentials packages/core/sdk/src/oauth-service.ts12-14oauth.complete): Redeems the session using the returned code and state, exchanges them for tokens, and calls mintOAuthConnection to create the permanent connection row packages/core/sdk/src/oauth-service.ts13-14The following diagram bridges the high-level flow to the specific code entities involved in a standard OAuth 2.0 flow.
OAuth Flow Entity Mapping
Sources: packages/core/sdk/src/oauth-service.ts11-14 packages/core/sdk/src/oauth-helpers.ts105-112 packages/react/src/plugins/oauth-sign-in.tsx140-168
Executor supports "zero-config" OAuth through metadata discovery and Dynamic Client Registration (DCR). This is primarily used by the MCP (Model Context Protocol) plugin to connect to arbitrary servers packages/core/sdk/src/oauth-discovery.ts7-8
The system probes for metadata in the following order:
/.well-known/oauth-protected-resource packages/core/sdk/src/oauth-discovery.ts10/.well-known/oauth-authorization-server packages/core/sdk/src/oauth-discovery.ts11/.well-known/openid-configuration packages/core/sdk/src/oauth-discovery.ts12If a registration_endpoint is discovered, Executor can automatically register itself as a client packages/core/sdk/src/oauth-discovery.ts13 It sends redirect_uris and required grant_types to the server to obtain a client_id and client_secret packages/core/sdk/src/oauth-discovery.ts109-123
Discovery and DCR Mapping
Sources: packages/core/sdk/src/oauth-discovery.ts61-86 packages/core/sdk/src/oauth-discovery.ts109-123 packages/core/sdk/src/oauth-discovery.ts22
Tokens are stored using the OAUTH2_PROVIDER_KEY ("oauth2") in the configured CredentialProvider packages/core/sdk/src/oauth.ts34-36
Refresh is handled by the core ExecutionEngine and OAuthService, not by individual plugins packages/plugins/openapi/src/sdk/oauth-refresh.test.ts6-12
60,000ms before actual expiry to prevent mid-request failures packages/core/sdk/src/oauth-helpers.ts54-55invalid_grant errors from providers that rotate refresh tokens packages/plugins/openapi/src/sdk/oauth-refresh.test.ts4-6Sources: packages/core/sdk/src/oauth-helpers.ts54-55 packages/plugins/openapi/src/sdk/oauth-refresh.test.ts4-12
Executor supports multiple backends for storing the secrets minted during OAuth flows. These are implemented as plugins that satisfy the CredentialProvider interface packages/core/sdk/src/shared.ts48
| Provider | Implementation | Purpose |
|---|---|---|
| Keychain | packages/plugins/keychain | Uses OS-native secure storage (macOS Keychain, Windows Credential Manager) via NAPI-RS packages/plugins/keychain/src/keyring.ts1-10 |
| File Secrets | packages/plugins/file-secrets | XDG-compliant local file storage for CLI and local development environments packages/plugins/file-secrets/src/index.ts1-5 |
| WorkOS Vault | packages/plugins/workos-vault | Cloud-native encrypted storage using WorkOS Vault for multi-tenant SaaS deployments packages/plugins/workos-vault/src/sdk/secret-store.ts1-15 |
| 1Password | packages/plugins/secret-management | (Planned/Partial) Integration with 1Password SDK for enterprise secret management. |
Sources: packages/plugins/keychain/src/keyring.ts1-10 packages/plugins/file-secrets/src/index.ts1-5 packages/plugins/workos-vault/src/sdk/secret-store.ts1-15
Plugins use an Auth Template system to define how credentials (like OAuth tokens) are injected into requests.
AuthMethodOAuthDescriptor defines the required scopes and the placement of the token packages/core/sdk/src/shared.ts34ExecutionEngine resolves the connection, ensures the token is fresh, and then applies the template (e.g., injecting the token as a Bearer header) packages/plugins/openapi/src/sdk/oauth-refresh.test.ts9-12Sources: packages/core/sdk/src/shared.ts34 packages/plugins/openapi/src/sdk/oauth-refresh.test.ts9-12
Refresh this wiki