Where Is the Corsair Core Logic Located? A Deep Dive into `packages/corsair/core`

The Corsair core logic resides in packages/corsair/core, with core/index.ts serving as the primary entry point that exports the createCorsair factory function and orchestrates all internal subsystems.

If you're building integrations with the corsairdev/corsair open-source platform, understanding where the Corsair core logic lives is essential for debugging, extending, or contributing to the codebase. This guide maps every critical subsystem to its exact source file location.

---

The Main Entry Point: core/index.ts

All roads lead through packages/corsair/core/index.ts. This file defines the createCorsair factory function (lines 42–71 for overloads, lines 72–157 for implementation) and handles:

• Factory initialization for single-tenant and multi-tenant modes
• Plugin registration and namespace wiring
• Auto-start logic for development tunnels and connect loops (maybeStartConnectLoop, maybeStartTunnel, shouldStartTunnel)
• Subsystem coordination across database, permissions, and key management

When you import from corsair/core, you're consuming exports from this file.

---

Core Subsystem Breakdown

The Corsair core logic spans seven interconnected files. Each handles a distinct responsibility:

Factory & Public API

packages/corsair/core/index.ts exposes createCorsair, the sole constructor for Corsair instances. It validates configuration, initializes the database adapter, and returns an object with plugin namespaces, key management, permissions, and management utilities.

Client Construction

packages/corsair/core/client.ts builds the runtime client that implements plugin APIs. It handles:

• Plugin API surface generation
• Key handling and encryption context
• Error propagation across tenant boundaries

Permission Namespace

packages/corsair/core/permissions/index.ts supplies the permissions object that plugins use to query and modify access control. This namespace is available on every Corsair instance as corsair.permissions.

Management Namespace

packages/corsair/core/management.ts provides admin utilities via corsair.manage, including:

• Integration provisioning
• Tenant lifecycle operations
• OAuth flow orchestration

Configuration Resolution

packages/corsair/core/config/resolve-root-permissions.ts normalizes raw permission configuration into a canonical format consumed by the permission engine.

Auth Error Handling

packages/corsair/core/auth/errors.ts generates a helpful proxy that throws descriptive errors when required authentication configuration (KEK or database) is missing. This prevents silent failures during development.

Hub & Tunnel Integration

While tunnel code lives in packages/corsair/hub, the core auto-detects development environments and triggers maybeStartTunnel and maybeStartConnectLoop when a development API key is present in core/index.ts.

---

Practical Code Example: Creating a Corsair Instance

Here's how the Corsair core logic is consumed in practice. This TypeScript example creates a single-tenant instance with a custom plugin:

import { createCorsair } from 'corsair/core';
import type { CorsairPlugin } from 'corsair/core';

// ── Example plugin (normally lives in its own package) ─────────────────────
const demoPlugin: CorsairPlugin = {
  name: 'demo',
  client: (client) => ({
    hello: () => console.log('Hello from demo plugin!'),
  }),
};

// ── Create the Corsair integration ───────────────────────────────────────
const corsair = createCorsair({
  plugins: [demoPlugin],
});

// ── Use the plugin API directly (single-tenant mode) ───────────────────────
corsair.demo.hello(); // → prints: "Hello from demo plugin!"

// ── Multi-tenant mode requires withTenant() ────────────────────────────────
// const tenant = corsair.withTenant('tenant-123');
// tenant.demo.hello();

Key implementation details from the Corsair core logic:

• Import path: Always use corsair/core for the factory
• Plugin shape: Must implement CorsairPlugin with a name and client function
• Multi-tenancy: Enabled via multiTenancy: true in config, exposing withTenant(tenantId)

---

Supporting Infrastructure

The core logic depends on adjacent packages that are initialized during factory setup:

Dependency	Location	Purpose
Database adapter	packages/corsair/db/kysely/database.ts	Key storage and tenant data persistence
Hub types & tunneling	packages/corsair/hub/	Tunnel establishment and connect-loop management

These are not part of the core package but are called directly from core/index.ts during initialization.

---

Summary

• The Corsair core logic is centralized in packages/corsair/core.
• core/index.ts is the mandatory entry point exporting createCorsair.
• Seven files handle distinct responsibilities: factory, client, permissions, management, config resolution, auth errors, and hub integration.
• Higher-level packages import exclusively from corsair/core—never from internal subpaths.

---

Frequently Asked Questions

What file should I open first to understand how Corsair initializes?

Start with packages/corsair/core/index.ts. Lines 72–157 contain the complete createCorsair implementation that wires together every subsystem.

How does Corsair handle missing authentication configuration?

The packages/corsair/core/auth/errors.ts module generates a proxy object that throws clear, actionable errors when the KEK or database is undefined. This prevents cryptic failures downstream.

Where is multi-tenant logic implemented?

Multi-tenancy is implemented in core/index.ts through the withTenant(tenantId) method, available when multiTenancy: true is passed to createCorsair. The per-tenant client construction lives in core/client.ts.

Can I use Corsair core without the tunnel/auto-start features?

Yes. The tunnel and connect-loop auto-start only trigger when a development API key is detected. Production configurations with explicit database and KEK settings skip these code paths entirely in core/index.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}