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

> Find the Corsair core logic in packages/corsair/core. Discover the main entry point at core/index.ts and learn how it exports the createCorsair factory function.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: deep-dive
- Published: 2026-09-01

---

**The Corsair core logic resides in `packages/corsair/core`, with [`core/index.ts`](https://github.com/corsairdev/corsair/blob/main/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](https://github.com/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`](https://github.com/corsairdev/corsair/blob/main/core/index.ts)

All roads lead through **[`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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:

```typescript
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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/core/index.ts) during initialization.

---

## Summary

- The **Corsair core logic** is centralized in **`packages/corsair/core`**.
- **[`core/index.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/core/index.ts).