The Problem

AI agents need reliable, repeatable access to the hundreds of SaaS APIs users already authorise. Building and maintaining per‑provider OAuth flows, credential stores, and request contracts is a heavy, error‑prone effort that slows product rollout and raises security risk.

What This Does

OpenConnector supplies a single gateway that abstracts > 1,000 SaaS providers into a unified catalog of actions. The core runtime lives in src/ (≈ 5.5 k TS files) and exposes:

  • Provider adapters – each under src/providers/<name>/, e.g. src/providers/gmail/ or src/providers/doppler/.
  • Action contracts – JSON schema files describing request/response shapes, stored alongside the provider code.
  • Credential handling – unified API for API‑key, OAuth2, and custom secret types; see src/providers/doppler/runtime.secrets.ts for the secret‑shaped path pattern.

The web console (web/) offers admin UI, while the CLI (oo from the companion oo-cli repo) can invoke actions locally. Deployments are supported on Docker, Kubernetes, Cloudflare Workers, or the OOMOL managed service.

How It Is Wired

  1. Entry point – src/server/index.ts creates the HTTP server (Express/Koa). It registers middleware from src/middleware/ and loads the provider catalog via src/catalog/loadCatalog.ts.
  2. Request flow – An incoming HTTP request hits the router defined in src/routes/actionRouter.ts. The router extracts providerId and actionId from the URL, then calls ProviderRegistry.get(providerId) (implemented in src/providers/registry.ts).
  3. Provider execution – The selected provider module exports an execute(actionId, payload, context) function (e.g., src/providers/gmail/operations/sendEmail.ts). This function validates the payload against the provider’s JSON schema (src/providers/gmail/schema.json) and then calls the concrete SDK client (src/sdk/gmailClient.ts).
  4. Credential resolution – Before the SDK call, src/credentials/resolve.ts fetches stored secrets from the runtime store (SQLite or PostgreSQL, configured in src/db/connection.ts). For OAuth providers the flow uses src/oauth/tokenManager.ts to refresh or retrieve access tokens.
  5. Side‑effects – Database writes (audit logs, token persistence) are performed via the Prisma client instantiated in src/db/prisma.ts. File‑based transit (e.g., temporary uploads) uses the src/storage/ abstraction, which can point at local disk, S3‑compatible storage, or Cloudflare R2 based on the STORAGE_BACKEND env var.
  6. Response – The result of the SDK call is returned to the router, serialized, and sent back to the caller. Errors are caught by src/middleware/errorHandler.ts, which masks credential details.

The hub of the call graph is src/server/index.ts → src/routes/actionRouter.ts → ProviderRegistry → individual provider execute functions. No circular imports were found; the provider modules are leaf nodes that only depend on the shared SDK and credential utilities.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/open-connector
cd open-connector

# Install dependencies (npm is implied by package.json)
npm ci

# Build TypeScript sources
npm run build        # defined in package.json scripts

# Run locally with SQLite (default) via Docker Compose
docker compose -f docker-compose.yml up -d   # starts db, redis, and the connector

# Start the server (if not using Docker)
npm run start        # launches src/server/index.ts

Configuration – Environment variables are read in src/config/env.ts. Required keys include:

  • DATABASE_URL – connection string for PostgreSQL (or SQLite file path).
  • STORAGE_BACKEND – local, s3, or r2.
  • Provider‑specific OAuth client IDs/secrets (e.g., GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET).

These variables are documented in docs/CONFIGURATION.md (present but not exhaustive).

Running a test action – With the CLI installed (npm i -g @oomol/oo-cli), invoke:

oo run gmail.sendEmail \
  --payload '{"to":"user@example.com","subject":"Test","body":"Hello"}' \
  --token <runtime-token>

The CLI forwards the request to the local HTTP endpoint started above.

Real‑World Use

A SaaS platform that offers AI‑driven insights can embed OpenConnector as a microservice. When a user links their Gmail account, the platform stores the OAuth refresh token in OpenConnector’s runtime. Subsequent AI‑generated drafts are sent by calling the /action/gmail.sendEmail endpoint, letting the AI focus on content while OpenConnector handles credential rotation, rate‑limit back‑off, and audit logging.

Code Health & Issues

  • Low – Secret‑shaped path – src/providers/doppler/runtime.secrets.ts contains a hard‑coded path pattern that could expose secret identifiers if logged.
  • Tests – 154 files – Test suite exists, but coverage reports are not included; a CI step to enforce coverage is missing.
  • CI – GitHub Actions – Workflows (.github/workflows/*.yml) run lint and build, but no secret‑scan or dependency‑audit step.
  • Docs – 58 markdown files – Comprehensive README and multilingual docs are present, yet the “Setup” section lacks explicit Docker‑compose commands, requiring inference.

No high‑severity vulnerabilities were detected by the static audit.

The Bottom Line

OpenConnector delivers a concrete, extensible gateway for AI agents to reach a massive SaaS catalog, with clear separation between routing, credential handling, and provider logic. The codebase is sizable but well‑structured; the main risk is the few hard‑coded secret paths and the lack of automated secret scanning. It is suitable for teams that need a self‑hosted or cloud‑native connector layer and are comfortable managing the runtime’s database and storage configuration.