# Covara

> Your Drizzle schema is already a backend

This file contains all documentation content in a single document following the llmstxt.org standard.

## Account security flows


These flows are opt-in via [`useAuth`](./sessions.md) options. They build on the same `adapter` and add routes under the auth router's mount path (e.g. `/api/auth`).

## CSRF protection

```typescript
useAuth({ adapter, login, csrf: true });
// or: csrf: { headerName: "X-CSRF-Token", cookieName: "csrf_token", skip: (c) => false }
```

Uses the **double-submit-cookie** pattern: a non-`httpOnly` `csrf_token` cookie is issued on safe requests and refreshed on login, and unsafe methods (`POST`/`PUT`/`PATCH`/`DELETE`) must echo it back in the `X-CSRF-Token` header. Requests carrying an `Authorization` header (bearer/API-key clients) are exempt. A mismatch returns `403`. Also available standalone as `createCsrfMiddleware`.

## Login throttling

```typescript
useAuth({ adapter, login, throttle: true });
// or: throttle: { maxAttempts: 5, windowMs: 15 * 60 * 1000, store: myRateLimitStore }
```

Failed logins are counted **per email and per IP**; once `maxAttempts` (default 5) is exceeded within the window (default 15 min), `/login` returns `429` with `Retry-After`. A successful login resets the counters. Provide a distributed `RateLimitStore` (e.g. Redis-backed) for multi-instance deployments; the default is in-memory.

## Email verification

```typescript
import { InMemoryVerificationTokenStore } from "covara";

useAuth({
  adapter,
  login,
  verification: {
    store: new InMemoryVerificationTokenStore(),
    sendToken: async ({ identifier, token, expiresAt }) => sendEmail(identifier, token),
    markVerified: async (email) => db.update(users).set({ emailVerified: true }).where(eq(users.email, email)),
    ttlMs: 24 * 60 * 60 * 1000, // default 24h
    hashTokens: true,            // store SHA-256 of the token
  },
});
```

Adds `POST /verify/request` (issues a one-time token and calls `sendToken`) and `POST /verify/confirm` (`{ email, token }` → calls `markVerified`).

## Password reset

```typescript
useAuth({
  adapter,
  login,
  passwordReset: {
    store: new InMemoryVerificationTokenStore(),
    sendToken: async ({ identifier, token }) => sendEmail(identifier, token),
    resetPassword: async (email, passwordHash) =>
      db.update(users).set({ passwordHash }).where(eq(users.email, email)),
    findUserByEmail: async (email) => db.query.users.findFirst({ where: eq(users.email, email) }),
    ttlMs: 60 * 60 * 1000, // default 1h
    logoutEverywhere: true, // revoke all sessions after reset
  },
});
```

Adds:

- `POST /password/forgot` — `{ email }` → issues a token via `sendToken`; **always** returns `{ success: true }` (no email enumeration).
- `POST /password/reset` — `{ email, token, password }` → hashes the new password with the built-in [scrypt hasher](./passwords.md) and calls `resetPassword`. When `logoutEverywhere` is set and the adapter implements `invalidateUserSessions`, all of the user's sessions are revoked.

## Token stores

`verification`, `passwordReset`, and [`magicLink`](./magic-links.md) all use the `VerificationTokenStore` interface (`create`/`consume`/`deleteByIdentifier`). `InMemoryVerificationTokenStore` ships for development; back it with your own table for production. Set `hashTokens: true` to store only the SHA-256 of each token.

## Related

- [Sessions](./sessions.md) · [Passwords](./passwords.md) · [Magic links](./magic-links.md) · [Email](../platform/email.md)
- [Security headers](./security-headers.md) · [Rate limiting](../tooling/middleware.md#rate-limiting)

---

## API keys


Covara provides standalone helpers for issuing and verifying API keys. They are **not** wired into [`useAuth`](./sessions.md) routes — use them in your own endpoints (e.g. a settings page that creates keys, and an adapter's `validateApiKey` that verifies them).

A key is formatted `[prefix_]<id>.<secret>`. Only its **hash** is stored; the raw key is returned once at creation and never again.

```typescript
import {
  createApiKey, verifyApiKey, listApiKeys, revokeApiKey, rotateApiKey, InMemoryApiKeyStore,
} from "covara";

const store = new InMemoryApiKeyStore(); // or your own ApiKeyStore backed by a table

// Create — raw key shown once
const { key, metadata } = await createApiKey({
  store,
  userId: "user_123",
  label: "CI token",
  scopes: ["read"],
  prefix: "myapp",  // optional; prefixes the raw key
  expiresAt: null,  // or a Date / ttlMs
});

// Verify — touches lastUsedAt by default
const result = await verifyApiKey(key, { store });
if (result.valid) {
  // result.metadata: { id, userId, scopes, expiresAt, lastUsedAt, ... }
} else {
  // result.reason: "not_found" | "expired" | "mismatch"
}

await listApiKeys({ store, userId: "user_123" });
await rotateApiKey({ store, id: metadata.id }); // revoke + reissue, inheriting label/scopes/expiry
await revokeApiKey(metadata.id, { store });
```

## The store interface

```typescript
interface ApiKeyStore {
  create(...): Promise<...>;
  list(...): Promise<...>;
  findById(id: string): Promise<...>;
  delete(id: string): Promise<void>;
  touch(id: string): Promise<void>;
}
```

`InMemoryApiKeyStore` is a reference implementation for development; back it with your own table for production.

## Wiring into auth

To authenticate requests carrying a key, validate it in your adapter and return the user/scopes:

```typescript
const adapter = createPassportAdapter({
  getUserById: async (id) => { /* ... */ },
  validateApiKey: async (rawKey) => {
    const result = await verifyApiKey(rawKey, { store });
    return result.valid ? { userId: result.metadata.userId, scopes: result.metadata.scopes } : null;
  },
});
```

The client can send keys via the `X-API-Key` header (`useAuth({ strategy: "apiKey", apiKey })`). See [Client auth](../client/auth.md).

## Related

- [Sessions](./sessions.md) · [JWT](./jwt.md) · [Client auth](../client/auth.md)

---

## Federated login


The [OIDC provider](./oidc-provider.md) can delegate authentication to upstream identity providers (social login) via `backends.federated`. Users authenticate with Google/Microsoft/etc. and your provider issues its own tokens.

```typescript
import { createOIDCProvider, oidcProviders } from "covara";

const { router, middleware } = createOIDCProvider({
  issuer: "https://auth.myapp.com",
  keys: { algorithm: "RS256" },
  clients: [/* ... */],
  backends: {
    emailPassword: { enabled: true, validateUser: async () => { /* ... */ }, findUserById: async () => { /* ... */ } },
    federated: [
      oidcProviders.google({
        clientId: env.GOOGLE_CLIENT_ID,
        clientSecret: env.GOOGLE_CLIENT_SECRET,
      }),
      oidcProviders.microsoft({
        clientId: env.MS_CLIENT_ID,
        clientSecret: env.MS_CLIENT_SECRET,
        tenantId: "common", // or a specific tenant
      }),
      oidcProviders.generic({
        name: "custom",
        clientId: "...",
        clientSecret: "...",
        issuer: "https://custom-idp.example.com",
        scopes: ["openid", "email", "profile"],
      }),
    ],
  },
});
```

## Provider helpers

| Helper | Provider |
|--------|----------|
| `oidcProviders.google(...)` | Google |
| `oidcProviders.microsoft(...)` | Microsoft / Entra ID (`tenantId`) |
| `oidcProviders.okta(...)` | Okta |
| `oidcProviders.auth0(...)` | Auth0 |
| `oidcProviders.keycloak(...)` | Keycloak |
| `oidcProviders.generic(...)` | Any OIDC provider (`issuer`, `scopes`) |

## How id_token verification works

Federated `id_token`s are **signature-verified** against the provider's JWKS (fetched from its discovery document and cached), with issuer and audience checks. After verification:

1. the `nonce` is compared to the stored interaction nonce, and
2. the `id_token`'s `sub` is cross-checked against the `userinfo` `sub`.

Any mismatch aborts the login. This closes token-substitution and replay vectors.

## Non-OIDC providers (Passport.js)

`backends.federated` only works with **OIDC-compliant** identity providers (they expose a discovery document and an `id_token`). For OAuth-2-only providers — GitHub, Discord, Spotify, Twitch, … — use `backends.passport`, which drives any [Passport.js](https://www.passportjs.org/) OAuth2 strategy and resumes the same authorization interaction. Like everything in Covara, it runs on Node **and** Cloudflare Workers (see [Social login](./social.md#how-it-works-on-workers) for the mechanism).

```bash
npm install passport-github2
```

```typescript
import { Strategy as GitHubStrategy } from "passport-github2";
import { createOIDCProvider, fromPassport } from "covara";

createOIDCProvider({
  issuer: "https://auth.myapp.com",
  keys: { algorithm: "RS256" },
  clients: [/* ... */],
  backends: {
    emailPassword: { enabled: true, /* ... */ },
    passport: {
      providers: [
        fromPassport(
          new GitHubStrategy(
            {
              clientID: env.GITHUB_CLIENT_ID,
              clientSecret: env.GITHUB_CLIENT_SECRET,
              // All passport providers share ONE callback under the provider:
              callbackURL: "https://auth.myapp.com/auth/passport/callback",
            },
            (_a, _r, profile, done) => done(null, profile)
          )
        ),
      ],
      findUserByAccount: async (provider, providerAccountId) => /* existing user or null */,
      findUserById: async (id) => /* user by id — used by consent/token/userinfo */,
      createUser: async (account) => /* create user from account.profile */,
    },
  },
});
```

Each provider appears as a button on the login page, mounted under `/auth/passport/:provider` (start) and `/auth/passport/callback` (shared callback — the provider is recovered from signed state). On success the provider establishes its session and continues to consent / the authorization code exactly like an email/password login, so your relying parties receive normal OIDC tokens. `findUserById` is required here so consent, `/token`, and `/userinfo` can resolve the user when no email/password backend is configured.

The config mirrors [`useAuth({ social })`](./social.md) — same `fromPassport` wrapper and `SocialAccount` — the difference is the result: `backends.passport` issues **your provider's** OIDC tokens, while `useAuth` mints a local session.

:::note Scope
Covers OAuth 2.0 strategies (the bulk of the catalog). OAuth 1.0a strategies are Node-only and not supported on Workers — see [Social login](./social.md#how-it-works-on-workers).
:::

## Related

- [OIDC provider](./oidc-provider.md) · [Social login](./social.md) · [Client auth](../client/auth.md) · [Auth contract](../contracts/auth.md)

---

## Auth quickstart


This is the shortest path to working authentication: **email/password with email confirmation** and **GitHub social login**, on one session. By the end, users can sign up, confirm their email, log in, or click "Continue with GitHub".

## The one table you must create

Covara never owns your **users** table — you provide it and reach it through callbacks. Everything else auth needs (sessions, verification tokens) can live in the [KV store](../platform/kv.md) or memory, so for the fastest start **`users` is the only database table you create**.

See [Internal & system tables](./internal-tables.md) for the full picture — including the optional framework-owned SQL tables (`auth_sessions`, `auth_verification_tokens`, …) you'd switch to in production and exactly which columns they need.

```typescript
// src/schema.ts
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";

export const users = sqliteTable("users", {
  id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
  email: text("email").notNull().unique(),
  // null for social-only users who never set a password
  passwordHash: text("password_hash"),
  name: text("name"),
  image: text("image"),
  // null until the user confirms their email; gates email/password login
  emailVerified: integer("email_verified", { mode: "timestamp" }),
});
```

The shape Covara expects back from your lookups is just `{ id, email?, name?, image?, emailVerified? }` — documented under [App-supplied tables → Users](./internal-tables.md#users).

## Type-safe env

Define your config once with [`createEnv`](../deployment/environment-variables.md) — it's Zod-validated, fails fast on a missing var, and is **Workers-safe** (it reads through the runtime-safe primitive under the hood, never `process.env` directly). Reference `env.X` everywhere instead of reaching for `process.env`.

```typescript
// src/env.ts
import { createEnv } from "covara";
import { z } from "zod";

export const env = createEnv({
  APP_URL: z.string().default("http://localhost:3000"),
  PORT: z.string().default("3000").transform(Number),
  RESEND_API_KEY: z.string(),
  GITHUB_CLIENT_ID: z.string(),
  GITHUB_CLIENT_SECRET: z.string(),
});
```

## Configure auth

`useAuth` wires the adapter, the login/signup/logout routes, **email confirmation** (`verification`), and **social login** (`social`) in one call. Read config from the typed `env` above and send mail with the [email helpers](../platform/email.md).

```typescript
// src/auth.ts
import {
  useAuth,
  cookieSession,
  hashPassword,
  verifyPassword,
  fromPassport,
  InMemoryVerificationTokenStore,
} from "covara";
import { setGlobalEmail, createResendAdapter, sendEmail } from "covara/email";
import { Strategy as GitHubStrategy } from "passport-github2";
import { eq } from "drizzle-orm";
import { db } from "./db";
import { users } from "./schema";
import { env } from "./env";

// Configure email once (for local dev you can skip this and console.log the link).
setGlobalEmail(createResendAdapter({ apiKey: env.RESEND_API_KEY }));

export const auth = useAuth({
  // Server-side sessions. Swap for jwtSession({ secret: env.JWT_SECRET }) to issue
  // JWTs instead — every provider below works unchanged. See Sessions › strategies.
  session: cookieSession({
    getUserById: (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
  }),

  // --- Email / password ---
  login: {
    validateCredentials: async (email, password) => {
      const user = await db.query.users.findFirst({ where: eq(users.email, email) });
      if (!user?.passwordHash) return null;                 // social-only or no such user
      if (!(await verifyPassword(password, user.passwordHash))) return null;
      if (!user.emailVerified) return null;                 // block until confirmed
      return { id: user.id, email: user.email, name: user.name };
    },
  },
  signup: {
    createUser: async ({ email, password, name }) => {
      const [u] = await db
        .insert(users)
        .values({ email, name, passwordHash: await hashPassword(password) })
        .returning();
      return { id: u.id, email: u.email, name: u.name };
    },
  },

  // --- Email confirmation ---
  verification: {
    store: new InMemoryVerificationTokenStore(), // prod: createKVVerificationTokenStore(kv)
    sendToken: async ({ identifier, token }) => {
      const link = `${env.APP_URL}/verify?email=${encodeURIComponent(identifier)}&token=${token}`;
      await sendEmail({
        from: "Acme <noreply@acme.com>",
        to: identifier,
        subject: "Confirm your email",
        html: `Confirm your email: Verify`,
        text: `Confirm your email: ${link}`,
      });
    },
    markVerified: async (email) => {
      await db.update(users).set({ emailVerified: new Date() }).where(eq(users.email, email));
    },
  },

  // --- Social login (any Passport.js OAuth2 strategy) ---
  social: {
    providers: [
      fromPassport(
        new GitHubStrategy(
          {
            clientID: env.GITHUB_CLIENT_ID,
            clientSecret: env.GITHUB_CLIENT_SECRET,
            callbackURL: `${env.APP_URL}/api/auth/social/github/callback`,
          },
          (_accessToken, _refreshToken, profile, done) => done(null, profile)
        )
      ),
    ],
    findOrCreateUser: async ({ profile }) => {
      if (profile.email) {
        const existing = await db.query.users.findFirst({ where: eq(users.email, profile.email) });
        if (existing) return existing;
      }
      const [u] = await db
        .insert(users)
        .values({
          email: profile.email ?? `${profile.username}@github.local`,
          name: profile.name,
          image: profile.image,
          emailVerified: new Date(), // the provider already verified the address
        })
        .returning();
      return u;
    },
    successRedirect: "/",
  },
});
```

```bash
npm install passport-github2   # whichever Passport strategies you use
```

## Mount it

```typescript
// src/index.ts
import { createCovara } from "covara";
import { startServer } from "covara/node";
import { auth } from "./auth";
import { env } from "./env";

const app = createCovara({ auth }); // mounts the auth routes under /api/auth
await startServer(app, { port: env.PORT });
```

This gives you, under `/api/auth`:

| Route | Purpose |
|-------|---------|
| `POST /signup` · `POST /login` · `POST /logout` | email/password |
| `POST /verify/request` · `POST /verify/confirm` | email confirmation |
| `GET /social/github` · `GET /social/github/callback` | GitHub social login |
| `GET /me` | the current user |

## The email-confirmation flow

1. **Sign up** → creates the user with `emailVerified = null`.
2. **Request a token** → `POST /api/auth/verify/request` issues a token and calls your `sendToken` (the email above).
3. **User clicks the link** → your `/verify` page reads `email` + `token` from the URL and calls `POST /api/auth/verify/confirm`.
4. **`markVerified`** stamps `emailVerified` → the `login` check now passes.

```typescript
import { getOrCreateClient } from "covara/client";

const client = getOrCreateClient({ baseUrl: location.origin, credentials: "include" });

// after signup, ask the server to email a confirmation link
await client.session.signup({ email, password, name });
await client.session.requestEmailVerification(email);

// on your /verify page (link target from the email)
const params = new URLSearchParams(location.search);
await client.session.confirmEmail(params.get("email")!, params.get("token")!);
```

## From the client

Every auth flow is a first-class client method — no hand-written `fetch`.

```typescript
import { getOrCreateClient } from "covara/client";

const client = getOrCreateClient({ baseUrl: location.origin, credentials: "include" });

await client.session.login(email, password); // email/password
client.loginWithSocial("github");            // redirects to GitHub, returns with a session
const user = await client.session.me();       // current user, or null
await client.session.logout();
```

In React the `useAuth` hook exposes the same flows and tracks `user`/`status` for you:

```tsx
import { useAuth } from "covara/client/react";

function SignIn() {
  const { user, isAuthenticated, login, signup, signInWith } = useAuth();
  if (isAuthenticated) return Hi {user?.name};
  return (
    <>
      <button onClick={() => login("a@b.com", "secret")}>Log in</button>
      <button onClick={() => signup({ email: "a@b.com", password: "secret" })}>Sign up</button>
      <button onClick={() => signInWith("github")}>Continue with GitHub</button>
    </>
  );
}
```

## Going to production

The dev setup above keeps sessions and verification tokens in memory. For real deployments, swap the in-memory pieces for shared stores — no code change beyond the store you pass:

- **Sessions:** pass a `sessionStore` to `createPassportAdapter` — [`createKVSessionStore({ kv })`](./sessions.md) (Redis / Durable Object, no SQL table) or [`createDrizzleSessionStore({ db, resolver })`](./internal-tables.md) (which needs the `auth_sessions` table).
- **Verification tokens:** `createKVVerificationTokenStore(kv)` instead of `InMemoryVerificationTokenStore`.
- **Harden login:** layer on [account security](./account-security.md) (CSRF, login throttling, password policy) and [authorization scopes](./scopes.md) to lock down your resources.

## Related

- [Internal & system tables](./internal-tables.md) · [Sessions](./sessions.md) · [Social login](./social.md) · [Account security](./account-security.md) · [Email](../platform/email.md)

---

## Internal & system tables


Covara's auth and system features touch a handful of tables. This page lists **every one of them**, what columns each requires, who reads/writes it, and how to point Covara at your own schema — including renaming tables and **remapping column names**.

There are three categories:

- **Framework-owned SQL tables** — `auth_sessions`, `auth_accounts`, `auth_api_keys`, `auth_verification_tokens`. Covara ships their schema and (optionally) migrates them. You can rename them and remap their columns.
- **App-supplied tables** — your **users** table and (if you use file uploads) a **files** table. Covara never owns these; it reaches them through callbacks/resources you provide. You only need to satisfy a required shape.
- **Not database tables** — the **changelog** and **rate limits** are backed by the [KV store](../platform/kv.md) (or memory), *not* DB tables. The example app defines `changelog`/`rate_limits` tables for illustration, but the framework does not read them.

## Framework-owned SQL tables

Built-in definitions live in `internal-schema.ts` (exported as `authSessions`, `authAccounts`, `authApiKeys`, `authVerificationTokens`, and the dialect-specific `…Sqlite`/`…Pg` variants). Only **`auth_sessions`** is read column-by-column at runtime today (by the Drizzle session store); the others are reached through stores/adapters or only created by migration.

### `auth_sessions`

Session storage. Read/written by the [Drizzle session store](./sessions.md) — the one table queried by column directly.

| Logical key | Required | Purpose |
|---|---|---|
| `id` | ✅ | session id (primary key) |
| `userId` | ✅ | owning user |
| `createdAt` | ✅ | creation time |
| `expiresAt` | ✅ | expiry (indexed) |
| `data` | optional | JSON blob (e.g. `lastActiveAt`) |

### `auth_accounts`

OAuth/OIDC linked accounts. Persisted by your OIDC/Auth.js **adapter callbacks** — Covara has no direct store for it; the schema exists for migration + reference. Compound primary key on `(provider, providerAccountId)`.

Required: `userId`, `type`, `provider`, `providerAccountId`. Optional token columns: `refresh_token`, `access_token`, `expires_at`, `token_type`, `scope`, `id_token`, `session_state`.

### `auth_api_keys`

API keys. Reached through the [`ApiKeyStore`](./api-keys.md) interface.

Required: `id`, `userId`, `name`, `keyHash`, `keyPrefix`, `createdAt`. Optional: `scopes` (JSON), `expiresAt`, `lastUsedAt`, `revokedAt`.

### `auth_verification_tokens`

Email-verification / password-reset / magic-link tokens. Reached through the `VerificationTokenStore` interface. Compound primary key on `(identifier, token)`.

Required: `identifier`, `token`, `expires`.

## Bringing your own tables (and remapping columns)

Use `defineInternalSchema(...)` to point Covara at your own Drizzle tables. Each table accepts a `fieldMap` that maps Covara's **logical keys** to your columns — so a schema with Auth.js-style or snake_case columns works unchanged. Each value can be either the **Drizzle column object** (type-safe and refactor-safe — recommended) or the **property name** as a string.

```typescript
import { defineInternalSchema, createDrizzleSessionStore, createPassportAdapter } from "covara";
import { mySessions } from "./schema";

const internal = defineInternalSchema({
  dialect: "sqlite",
  sessions: {
    table: mySessions,           // any table name
    fieldMap: {                  // logical key -> your column (object or property name)
      userId: mySessions.ownerId,   // pass the Drizzle column directly
      createdAt: mySessions.created, // (or a string: createdAt: "created")
      expiresAt: mySessions.expires,
      data: mySessions.blob,
    },
  },
});

// Build the session store with the resolved table, then pass the bundle to
// createCovara for migration/introspection.
const adapter = createPassportAdapter({
  getUserById,
  sessionStore: createDrizzleSessionStore({ db, resolver: internal.sessions }),
});

const app = createCovara({ internalSchema: internal, auth: useAuth({ adapter }) });
```

- `defineInternalSchema` **validates required keys at startup** and throws a precise error (e.g. `internalSchema.sessions.expiresAt: required column not found…`) if a required column is missing — fail-fast, never at query time. Passing a column object that belongs to a different table is also rejected at startup.
- Omitting a table override falls back to the built-in table, so today's behavior is unchanged when you pass nothing.
- `createCovara({ internalSchema })` records the bundle for migration + introspection. It does **not** rewire already-constructed stores — build `createDrizzleSessionStore({ resolver })` yourself (as above).
- The `SessionData` shape your app sees stays in logical keys (`id`/`userId`/`createdAt`/`expiresAt`/`data`); remapping happens only at the SQL boundary.

### The KV session store works with any backend

`createKVSessionStore({ kv })` is backed by the [KV abstraction](../platform/kv.md), so sessions can live in Redis, the Cloudflare Durable Object store, or in-memory for tests — its internal hash fields are a private serialization and are **not** subject to `fieldMap`. (`createRedisSessionStore` remains as a deprecated alias.)

## Migrations

`migrateInternal(db, { schema?, dialect? })` has three modes:

1. **No `schema`** → creates the built-in tables with the canonical DDL (indexes + compound PKs). This is the default and is byte-for-byte unchanged.
2. **`schema.managedExternally = true`** → **no-op**. Recommended whenever you customize tables: create them with your own tool (e.g. `drizzle-kit`), which handles indexes and compound primary keys correctly.
3. **`schema` without `managedExternally`** → generates `CREATE TABLE IF NOT EXISTS` for overridden tables from the Drizzle table objects. Single-primary-key tables only — it **throws** for compound-PK tables (`auth_accounts`, `auth_verification_tokens`), directing you to mode 2. Indexes are not regenerated in this mode.

## App-supplied tables

### Users

Covara **never owns a users table**. Auth adapters reach the user through a `getUserById(id)` callback you implement, so you can store users however you like (a Drizzle table, an external service, anything). The object you return must include:

| Field | Required | Notes |
|---|---|---|
| `id` | ✅ | string |
| `email` | optional | |
| `name` | optional | |
| `image` | optional | |
| `emailVerified` | optional | `Date \| null` |
| `metadata` | optional | arbitrary record |

### Files

If you use [file uploads](../platform/storage.md) via `fileResource`, you supply the files table. Required columns: `id`, `filename`, `mimeType`, `size`, `storagePath`, `status` (`"pending" | "completed"`), `createdAt`. Optional: `userId` (for access control), `url`.

## Changelog & rate limits are not DB tables

The [changelog](../realtime/changelog.md) is stored in the [KV store](../platform/kv.md) (sorted set) with an in-memory fallback. [Rate limiting](../tooling/middleware.md) uses the KV store or an in-memory map. **Neither reads a database table.** 

# Related

- [Sessions](./sessions.md) · [API keys](./api-keys.md) · [KV store](../platform/kv.md)
- [Auth contract](../contracts/auth.md)

---

## JWT authentication


JWT auth uses signed bearer tokens instead of cookie sessions — a good fit for mobile apps, third-party API clients, and stateless services. Covara provides a server-side JWT adapter and a client `JWTClient` + `useJWTAuth` hook with pluggable token storage.

## Server

Use the `jwtSession` [session strategy](./sessions.md#session-strategies) so the middleware validates `Authorization: Bearer <token>` and populates the [request user](./overview.md#the-request-user). It's decoupled from how the user logs in — so the **same credential providers** (`login`, `signup`, [`social`](./social.md), …) issue JWTs instead of cookies just by swapping the strategy.

```typescript
import { jwtSession, useAuth } from "covara";

const { router, middleware } = useAuth({
  session: jwtSession({
    secret: env.JWT_SECRET,         // HMAC, or a key pair for RS256/ES256
    getUserById: async (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
    refreshStore: kvStore,          // optional: revocable refresh tokens
  }),
  login: { validateCredentials: async (email, password) => { /* ... */ } },
  signup: { createUser: async (data) => { /* ... */ } },
});
```

`/login` and `/signup` return `{ accessToken, expiresIn, tokenType: "Bearer" }` and set an `httpOnly` refresh cookie (instead of a session cookie); `POST /api/auth/refresh` mints a fresh access token. Protected routes read the bearer token.

> **Migrating from `createJWTAdapter`:** the standalone `createJWTAdapter` (mounted via its own `getRoutes()` + `middleware`) still works but is deprecated in favor of `jwtSession`, which integrates with `useAuth` (and its social/MFA/magic-link providers). Its options map 1:1.

## Client

With `jwtSession`, the standard [`useAuth()` hook](../client/auth.md) handles JWTs uniformly — `login`/`signup` capture the returned access token and send it as a bearer on subsequent requests (and `client.session.login` does the same outside React):

```tsx
import { useAuth } from "covara/client/react";

function SignIn() {
  const { login, signup, signInWith } = useAuth<User>();
  // login(email, password) -> stores the JWT and authenticates; same code as a cookie session
}
```

For finer control (manual token storage, refresh scheduling, React Native), use the dedicated `useJWTAuth` hook / `JWTClient`:

### `useJWTAuth`

```tsx
import { initJWTClient, useJWTAuth } from "covara/client/react";

initJWTClient({ baseUrl: location.origin, authPath: "/api/auth" });

function App() {
  const { user, accessToken, isAuthenticated, login, signup, logout, refresh } = useJWTAuth<User>();

  const onLogin = () => login("user@example.com", "password");
  const onSignup = () => signup("user@example.com", "password", "Jane Doe");

  if (!isAuthenticated) return <button onClick={onLogin}>Sign in</button>;
  return <button onClick={logout}>Sign out {user?.name}</button>;
}
```

Alternatively configure JWT on the main client and let the generic [`useAuth`](../client/auth.md) hook auto-detect the strategy:

```typescript
import { getOrCreateClient } from "covara/client";

const client = getOrCreateClient({ baseUrl: location.origin, jwt: { authPath: "/api/auth" } });
```

```tsx
const { user, isAuthenticated, accessToken } = useAuth<User>(); // auto-detects JWT
```

The client refreshes the access token automatically before expiry and retries a request once after a `401` by refreshing. See [Client auth](../client/auth.md).

## Token storage

The client stores tokens through a pluggable `TokenStorage`, so the same code runs in the browser and React Native:

| Storage | Behavior |
|---------|----------|
| `MemoryStorage` | Most secure; tokens lost on refresh. |
| `LocalStorageAdapter("prefix_")` | Persists across tabs/sessions. |
| `SessionStorageAdapter("prefix_")` | Persists until the tab closes. |
| AsyncStorage-compatible | Provide your own for React Native. |

See [React Native](../client/react-native.md) for native token storage.

## Setting a token manually

```typescript
client.setAuthToken("your-jwt-token");
client.clearAuthToken();
```

## Related

- [Sessions](./sessions.md) · [OIDC provider](./oidc-provider.md) · [API keys](./api-keys.md)
- [Client auth](../client/auth.md) · [React Native](../client/react-native.md)

---

## Magic links


Passwordless login via emailed single-use tokens. Enable it by passing a `magicLink` config to [`useAuth`](./sessions.md).

```typescript
import { InMemoryVerificationTokenStore } from "covara";

useAuth({
  adapter,
  magicLink: {
    store: new InMemoryVerificationTokenStore(),
    sendLink: async ({ identifier, token }) =>
      sendEmail(identifier, `https://app.com/magic?token=${token}`),
    findUserByEmail: async (email) => db.query.users.findFirst({ where: eq(users.email, email) }),
    ttlMs: 15 * 60 * 1000, // default 15m
    hashTokens: true,      // store SHA-256 instead of the raw token
  },
});
```

## Routes

| Route | Method | Description |
|-------|--------|-------------|
| `/magic-link/request` | POST | `{ email }` — issues a single-use token and calls `sendLink` **only if the user exists**, but always returns `{ success: true }` (no email enumeration). |
| `/magic-link/verify` | POST | `{ email, token }` — consumes the token and creates the session, returning `{ user, sessionId }`; invalid/expired returns `401`. |

## Low-level helpers

```typescript
import { issueMagicLinkToken, consumeMagicLinkToken } from "covara";
```

Use these for custom flows (e.g. issuing a link from a different channel).

## Token store

`magicLink.store` implements the `VerificationTokenStore` interface (`create`/`consume`/`deleteByIdentifier`), shared with [email verification and password reset](./account-security.md). `InMemoryVerificationTokenStore` ships for development; back it with your own table for production.

## Related

- [Account security](./account-security.md) · [Sessions](./sessions.md) · [Email](../platform/email.md)

---

## Multi-factor auth (TOTP)


Enable TOTP-based MFA (authenticator apps) with backup codes by passing an `mfa` config to [`useAuth`](./sessions.md).

```typescript
useAuth({
  adapter,
  login,
  mfa: {
    issuer: "My App",
    requireOnLogin: true,
    getUserByEmail: async (email) => db.query.users.findFirst({ where: eq(users.email, email) }),
    getEnrollment: async (userId) => db.query.mfa.findFirst({ where: eq(mfa.userId, userId) }),
    saveEnrollment: async (userId, enrollment) =>
      db.insert(mfa).values({ userId, ...enrollment }).onConflictDoUpdate({ target: mfa.userId, set: enrollment }),
    consumeBackupCode: async (userId, index) => { /* mark backup code `index` used */ },
  },
});
```

Required callbacks: `getUserByEmail`, `getEnrollment`, `saveEnrollment`. The stored `MfaEnrollment` is `{ secret: string; enabled: boolean; backupCodeHashes?: string[] }`.

## Routes

| Route | Method | Description |
|-------|--------|-------------|
| `/mfa/enroll` | POST | Generate a TOTP secret + backup codes for the current user (saved as `enabled: false`). Returns `{ secret, otpauthUri, backupCodes }` — codes shown once. |
| `/mfa/enroll/confirm` | POST | `{ code }` — verify the first TOTP and flip the enrollment to `enabled: true`. |
| `/mfa/verify` | POST | `{ email, code }` — second-factor login step; on success creates the session. Accepts a TOTP **or** a backup code. |

## Login flow

When `requireOnLogin` is true and the user has an enabled enrollment, `POST /login` returns `{ mfaRequired: true }` with `401` if no `mfaCode` is supplied. The client then either resubmits `/login` with `mfaCode`, or calls `/mfa/verify`. A matched backup code triggers `consumeBackupCode`.

```mermaid
sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: POST /login (email, password)
  S-->>C: 401 { mfaRequired: true }
  C->>S: POST /mfa/verify (email, code)
  S-->>C: 200 { user, sessionId }
```

## Config

```typescript
mfa?: {
  issuer?: string;
  totp?: { step?: number; digits?: number; window?: number };
  backupCodeCount?: number;     // default 10
  requireOnLogin?: boolean;
  getUserByEmail(email): Promise<(AuthUser & { mfa?: MfaEnrollment | null }) | null>;
  getEnrollment(userId): Promise<MfaEnrollment | null>;
  saveEnrollment(userId, enrollment): void | Promise<void>;
  saveBackupCodeHashes?(userId, hashes): void | Promise<void>;
  consumeBackupCode?(userId, index): void | Promise<void>;
}
```

## Low-level primitives

For custom flows:

```typescript
import {
  generateTotpSecret, generateTotp, verifyTotp, getTotpUri, generateBackupCodes, verifyBackupCode,
} from "covara";
```

## Related

- [Sessions](./sessions.md) · [Passwords](./passwords.md) · [Account security](./account-security.md)

---

## OIDC provider


`createOIDCProvider` turns Covara into a standards-based **OpenID Connect identity server**: authorization-code flow with PKCE, JWT access/ID tokens, refresh-token rotation, federated login, token revocation (RFC 7009) and introspection (RFC 7662), and a login/consent UI — with hardening on by default.

```typescript
import { Hono } from "hono";
import { createOIDCProvider } from "covara";
import { eq } from "drizzle-orm";

const app = new Hono();

const { router, middleware, stores, tokenService } = createOIDCProvider({
  issuer: "https://auth.myapp.com",
  keys: { algorithm: "RS256" },
  tokens: {
    accessToken: { ttlSeconds: 3600 },
    refreshToken: { ttlSeconds: 30 * 24 * 3600, rotateOnUse: true },
  },
  clients: [
    {
      id: "web-app",
      name: "My Web App",
      redirectUris: ["https://myapp.com/callback"],
      postLogoutRedirectUris: ["https://myapp.com"],
      grantTypes: ["authorization_code", "refresh_token"],
      responseTypes: ["code"],
      tokenEndpointAuthMethod: "none", // public client — PKCE required
      scopes: ["openid", "profile", "email", "offline_access"],
    },
  ],
  backends: {
    emailPassword: {
      enabled: true,
      validateUser: async (email, password) => {
        const u = await db.query.users.findFirst({ where: eq(users.email, email) });
        return u && (await verifyPassword(password, u.passwordHash))
          ? { id: u.id, email: u.email, name: u.name } : null;
      },
      findUserById: async (id) => {
        const u = await db.query.users.findFirst({ where: eq(users.id, id) });
        return u ? { id: u.id, email: u.email, name: u.name } : null;
      },
    },
  },
});

app.route("/oidc", router);   // OIDC endpoints
app.use("/api/*", middleware); // validates bearer tokens → c.get("user")
```

The return value: `router` (a `Hono` instance), `middleware` (validates bearer tokens and populates the [request user](./overview.md#the-request-user)), `stores`, and `tokenService`.

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/.well-known/openid-configuration` | GET | Discovery document |
| `/authorize` | GET | Authorization code flow with PKCE |
| `/token` | POST | Token exchange & refresh |
| `/userinfo` | GET/POST | User claims |
| `/jwks` | GET | Public keys for verification |
| `/logout` | GET | End session with redirect |
| `/revoke` | POST | Token revocation (RFC 7009) |
| `/introspect` | POST | Token introspection (RFC 7662) |
| `/login` | GET/POST | Login UI (customizable) |
| `/consent` | GET/POST | Consent UI |
| `/consent/revoke` | POST/DELETE | Revoke a user's consent (one client or all) |
| `/register` | POST | Dynamic client registration (opt-in) |

`/revoke` and `/introspect` require client authentication and are advertised in discovery as `revocation_endpoint`/`introspection_endpoint`. Revoking a refresh token invalidates it; introspection returns `{ active, scope, sub, client_id, exp, ... }` for access and refresh tokens.

**Confidential client secrets** may be stored hashed: a secret beginning with `scrypt$` is verified with [`verifyPassword`](./passwords.md); a plaintext secret is compared in constant time. Generate one with `await hashPassword(secret)`.

## Configuration

```typescript
interface OIDCProviderConfig {
  issuer: string;                       // HTTPS in production
  keys: { algorithm?: "RS256" | "ES256"; privateKey?: string | Buffer; rotationIntervalMs?: number };
  tokens?: {
    accessToken?: { ttlSeconds?: number };  // default 3600
    idToken?: { ttlSeconds?: number };      // default 3600
    refreshToken?: { enabled?: boolean; ttlSeconds?: number; rotateOnUse?: boolean }; // 30d, rotate
  };
  clients: OIDCClient[];
  backends: { emailPassword?: EmailPasswordBackendConfig; federated?: FederatedProvider[] };
  stores?: {
    type?: "memory" | "redis" | "drizzle"; // KV-backed by default when a global KV exists
    kv?: KVAdapter; sessionStore?: SessionStore; prefix?: string; db?: unknown;
  };
  ui?: { loginPath?: string; consentPath?: string; templates?: { login?; consent?; error? } };
  security?: {
    pkce?: { required?: boolean; methods?: ("S256")[] };
    consent?: { ttlSeconds?: number };     // default 1 year
    rateLimiting?: { token?; jwks?; introspect? }; // { windowMs, max }
  };
  registration?: { enabled?: boolean; defaultScopes?: string[]; initialAccessToken?: string };
  hooks?: {
    onUserAuthenticated?(user, method): Promise<void>;
    onTokenIssued?(userId, clientId, scopes): Promise<void>;
    onConsentGranted?(userId, clientId, scopes): Promise<void>;
    getAccessTokenClaims?(user, client, scopes): Promise<Record<string, unknown>>;
  };
}
```

## Hardening (on by default)

- **Redirect URI validation** — matched component-by-component (protocol, host, port, normalized path, registered query/fragment), not by prefix. An unregistered URI is rejected with `400` **before** any redirect, so an attacker never receives a redirect.
- **PKCE** — `code_challenge_method=plain` is always rejected (only `S256` is supported/advertised). PKCE is **required for public clients** (`tokenEndpointAuthMethod: "none"`). Set `security.pkce.required: true` to require it for all clients.
- **`at_hash`** — computed correctly (left-half of the hash matching the signing algorithm) whenever an access token is issued.
- **Nonce** — `validateIdTokenNonce(idToken, expectedNonce)` is exported for relying parties.
- **Rate limiting** — `/token`, `/jwks`, `/introspect` can be limited per client or IP via `security.rateLimiting` (uses the global [KV](../platform/kv.md) when present, else an in-memory bucket; emits `X-RateLimit-*` and `429` + `Retry-After`). No limit unless configured.
- **Persistent stores by default** — with a global KV registered, clients, codes, refresh tokens, consents, interactions, and state are KV-backed with expiry-derived TTLs. Pass `stores.type: "memory"` to force in-memory.
- **`login_hint` escaping** — all dynamic values are HTML-escaped in the default login template.

## Dynamic client registration

Enable RFC 7591-style registration:

```typescript
registration: {
  enabled: true,
  defaultScopes: ["openid", "profile", "email"],
  initialAccessToken: env.OIDC_REGISTRATION_TOKEN, // optional gate
}
```

`POST /register` accepts a JSON/form body with at least `redirect_uris` (each validated as a URL), defaults `token_endpoint_auth_method` to `client_secret_basic` (use `none` for public clients), `grant_types` to `["authorization_code"]`, `response_types` to `["code"]`, and returns `201` with a generated `client_id` (+ `client_secret` for confidential clients). Returns `404` when disabled; requires `Authorization: Bearer <initialAccessToken>` when configured. The `registration_endpoint` is added to discovery only when enabled.

## Consent revocation

`POST /consent/revoke` (or `DELETE`) revokes a logged-in user's consent — with `client_id` in the body for one client, without it for all. Requires a valid `oidc_session` cookie (else `401`). Stored consents also expire after `security.consent.ttlSeconds` (default 1 year), after which the user re-consents.

## Federated login

Add Google, Microsoft, Okta, Auth0, Keycloak, or a generic OIDC provider via `backends.federated`. See [Federated login](./federated.md).

## Client side

The Covara client handles the OIDC PKCE flow, token refresh, and 401 retry. See [Client auth](../client/auth.md).

## Related

- [Federated login](./federated.md) · [JWT](./jwt.md) · [Client auth](../client/auth.md)
- [KV store](../platform/kv.md) · [Auth contract](../contracts/auth.md)

---

## Authentication overview


Covara ships a complete authentication and authorization stack. There are two ways to authenticate users, and one consistent way to authorize them.

:::tip Just want it working?
Follow the [**Auth quickstart**](./getting-started.md) — the fastest path to email/password (with email confirmation) plus GitHub social login, and the one table you actually need to create.
:::

## Two authentication approaches

| Approach | Use when | Page |
|----------|----------|------|
| **OIDC provider** | You want a standards-based identity server (OAuth2/OIDC, PKCE, federated login, JWT access tokens) for one or many apps. | [OIDC provider](./oidc-provider.md) |
| **Session-based `useAuth`** | You want classic email/password sessions with cookies, the fastest path to login/signup/logout. | [Sessions](./sessions.md) |

Both populate the same request context, so [authorization scopes](./scopes.md), [subscriptions](../realtime/subscriptions.md), and the [client `useAuth` hook](#client-side-useauth) work identically regardless of which you choose.

On top of either approach you can layer: [social login](./social.md) (sign in with GitHub/Discord/Google/… via any Passport.js strategy), [JWT tokens](./jwt.md), [federated login](./federated.md), [API keys](./api-keys.md), [MFA/TOTP](./mfa.md), [magic links](./magic-links.md), a [password policy](./passwords.md), and [account-security flows](./account-security.md) (CSRF, login throttling, email verification, password reset).

## The request user

After auth middleware runs, the authenticated user is available in any Hono handler:

```typescript
import { getUser, requireUser, getSession } from "covara";

app.get("/api/profile", (c) => {
  const user = requireUser(c); // throws 401 if absent
  return c.json(user);
});
```

`getUser(c)` returns the user or `null`; `requireUser(c)` throws an [`UnauthorizedError`](../tooling/error-handling.md); `getSession(c)` returns the session. These read from Hono's typed `ContextVariableMap` (`user`, `session`, `requestId`, `apiVersion`).

## Quick session setup

`useAuth` decouples **how** the identity is persisted (a [session strategy](./sessions.md#session-strategies) — `cookieSession` or `jwtSession`) from **who** the user is (credential providers — `login`, `signup`, [`social`](./social.md), …), so any provider composes with any session type.

```typescript
import { createCovara, cookieSession, useAuth, hashPassword, verifyPassword } from "covara";
import { eq } from "drizzle-orm";

const auth = useAuth({
  // swap for jwtSession({ secret, getUserById }) to issue JWTs instead
  session: cookieSession({
    getUserById: async (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
  }),
  login: {
    validateCredentials: async (email, password) => {
      const user = await db.query.users.findFirst({ where: eq(users.email, email) });
      return user && (await verifyPassword(password, user.passwordHash))
        ? { id: user.id, email: user.email, name: user.name }
        : null;
    },
  },
  signup: {
    createUser: async ({ email, password, name }) => {
      const [u] = await db.insert(users)
        .values({ id: crypto.randomUUID(), email, name, passwordHash: await hashPassword(password) })
        .returning();
      return { id: u.id, email: u.email, name: u.name };
    },
  },
});

const app = createCovara({ auth }); // mounts /api/auth/* and the middleware
```

This creates four routes:

| Route | Method | Description |
|-------|--------|-------------|
| `/api/auth/me` | GET | Current user, or `{ user: null }` |
| `/api/auth/login` | POST | Email/password login |
| `/api/auth/signup` | POST | Create account |
| `/api/auth/logout` | POST | Clear session |

Full options and adapters: **[Sessions](./sessions.md)**.

## Route guards

```typescript
import { requireAuth, requireRole, requirePermission, getUser } from "covara";

app.get("/profile", requireAuth(), (c) => c.json(getUser(c)));
app.get("/admin", requireRole("admin"), (c) => c.json({ ok: true }));
app.post("/posts", requirePermission("posts:create"), async (c) => { /* ... */ });
```

## Authorization

Authentication answers *who is this*; **authorization** answers *what can they touch*. Covara enforces row-level access with [RSQL scopes](./scopes.md) on every read, write, subscription, and search — combined with the request filter and impossible to bypass from the client. See [Authorization scopes](./scopes.md) and [Secure queries](./secure-queries.md).

## Client-side `useAuth`

The React [`useAuth`](../client/auth.md) hook exposes the auth state and supports several strategies — cookie sessions, JWT, bearer token, API key, or auto-detect:

```tsx
import { useAuth } from "covara/client/react";

function App() {
  const { user, isAuthenticated, isLoading, logout } = useAuth<User>();
  if (isLoading) return Loading…;
  if (!isAuthenticated) return <LoginPage />;
  return <button onClick={logout}>Sign out {user?.name}</button>;
}
```

See [Client auth](../client/auth.md) for every strategy and the OIDC PKCE flow.

## Related

- [Quickstart](./getting-started.md) · [Sessions](./sessions.md) · [Social login](./social.md) · [JWT](./jwt.md) · [OIDC provider](./oidc-provider.md) · [Federated login](./federated.md)
- [Scopes](./scopes.md) · [Secure queries](./secure-queries.md) · [Passwords](./passwords.md)
- [Auth contract](../contracts/auth.md) — the threat model and guarantees

---

## Passwords


Covara ships a **Workers-safe scrypt** password hasher, so you don't need `bcrypt` or any native dependency. Hashes are self-describing strings (`scrypt$N=...,r=...,p=...$salt$hash`), so parameters can evolve without a schema change.

## Hashing

```typescript
import { hashPassword, verifyPassword, needsRehash } from "covara";

// On signup
const passwordHash = await hashPassword(plaintext);

// On login
if (!(await verifyPassword(plaintext, user.passwordHash))) {
  throw new Error("Invalid credentials");
}

// Upgrade old hashes to stronger params after a successful login
if (needsRehash(user.passwordHash)) {
  await db.update(users).set({ passwordHash: await hashPassword(plaintext) }).where(eq(users.id, user.id));
}
```

- `hashPassword(password, options?)` accepts scrypt cost parameters (`N`, `r`, `p`, `keylen`, `saltlen`).
- `needsRehash(stored, options?)` returns `true` when the stored hash is weaker than the target parameters (or unparseable).
- `verifyPassword` is constant-time.

These power the [session](./sessions.md), [OIDC](./oidc-provider.md) (confidential client secrets), and [password reset](./account-security.md) paths.

## Password policy

Enforce strength rules on signup and password reset by passing `passwordPolicy` to [`useAuth`](./sessions.md):

```typescript
useAuth({
  adapter,
  login,
  signup,
  passwordPolicy: {
    minLength: 12,
    maxLength: undefined,
    requireUppercase: true,
    requireLowercase: false,
    requireNumber: true,
    requireSymbol: true,
    denylist: ["mycompany"],
    useBuiltInDenylist: true, // default: blocks ~20 common passwords
  },
});
```

When set, the policy is enforced (before your own `signup.validatePassword`) on `POST /signup` and again on `POST /password/reset`. A weak password fails with a `422` listing the violations. The built-in denylist (on by default) blocks ~20 of the most common passwords (`password`, `123456`, `qwerty`, …); disable with `useBuiltInDenylist: false` or extend via `denylist`.

### Standalone helpers

```typescript
import { validatePasswordStrength, enforcePasswordStrength, builtInPasswordDenylist } from "covara";

const { valid, errors } = validatePasswordStrength(password, { minLength: 12 });
enforcePasswordStrength(password, { minLength: 12 }); // throws ValidationError if invalid
```

## Related

- [Sessions](./sessions.md) · [Account security](./account-security.md) · [OIDC provider](./oidc-provider.md)

---

## Authorization scopes


A **scope** is an [RSQL filter](../core/filtering.md), derived from the current user, that Covara `AND`-combines with every query for a resource. Scopes are enforced on reads, writes, subscriptions, count, aggregate, and search — server-side, so a client can never widen its own access.

```typescript
import { useResource, rsql } from "covara";

useResource(postsTable, {
  id: postsTable.id,
  db,
  auth: {
    public: { read: true },                                  // anonymous read
    update: async (user) => rsql`authorId==${user.id}`,    // own posts only
    delete: async (user) =>
      user.metadata?.role === "admin" ? rsql`*` : rsql`authorId==${user.id}`,
    subscribe: async (user) => rsql`authorId==${user.id}`, // live stream scope
  },
});
```

| Return | Meaning |
|--------|---------|
| `` rsql`*` `` | Allow all rows for this operation. |
| `` rsql`<expr>` `` | Allow only rows matching the expression. |
| ``` rsql`` ``` (empty) | Deny — no rows. |

Operations: `read`, `create`, `update`, `delete`, `subscribe`. Omit one to deny it (unless `public` grants it).

**Anonymous access — `public`.** `public: true` makes **read and subscribe** public (writes still require auth — a safe default). The object form opts each operation in explicitly and can open **writes** too: `public: { read: true, subscribe: true, create: true, update: true, delete: true }` for a fully-public resource (e.g. a prototype or a genuinely open collection). With the object form, `subscribe` is **not** implied by `read` — grant it explicitly or anonymous SSE subscriptions return `401`. An operation not granted by `public` and reached without a user returns `401`.

```mermaid
flowchart LR
  Req[Client request\n?filter=...] --> Combine
  Scope[auth scope\nrsql for user] --> Combine
  Combine[AND-combine] --> SQL[Drizzle WHERE]
  SQL --> DB[(Database)]
```

## Scope patterns

Common cases are presets:

```typescript
import { scopePatterns } from "covara";

auth: scopePatterns.ownerOnly("userId"),
auth: scopePatterns.publicReadOwnerWrite("userId"),
auth: scopePatterns.ownerOrAdmin("userId", (user) => user.metadata?.role === "admin"),
auth: scopePatterns.orgBased("organizationId"),
auth: scopePatterns.authenticatedFullAccess(),        // any signed-in user, full access
auth: scopePatterns.fullyPublic(),                    // every op public, incl. anonymous writes — demos only
```

> `fullyPublic()` opts **every** operation in (read, subscribe, create, update, delete) for unauthenticated callers — it's the `covara create` starter default so the app works end-to-end; lock it down before production. For public reads with authenticated writes, use `publicReadOwnerWrite`.

## Building scopes programmatically

The `rsql` template helper interpolates values safely. Or compose with builders. See [**RSQL**](../core/rsql.md#building-rsql-in-typescript) for the full builder reference (escaping rules, every helper, sub-scope composition, and the special `allScope()`/`emptyScope()`).

```typescript
import { rsql, eq, ne, gt, gte, lt, lte, inList, notIn, like, notLike, isNull, isNotNull, and, or } from "covara";

const a = eq("userId", user.id);
const b = and(eq("status", "active"), eq("organizationId", user.orgId));
const c = or(eq("userId", user.id), eq("public", true));
const d = like("email", "%@example.com");  // emits %=
const e = notLike("email", "%@spam.com");  // emits !%=

// equivalent template form:
const scope = rsql`userId==${user.id};status=="active"`;
```

:::note No NOT combinator
The filter grammar has no `NOT` combinator, so there is no `not()` helper. Use the negated operators instead: `ne` (`!=`), `notIn` (`=out=`), `notLike` (`!%=`), `isNotNull` (`=isnull=false`).
:::

## RSQL template helper

```typescript
import { rsql } from "covara";

auth: {
  update: async (user) => rsql`userId==${user.id}`,
  delete: async (user) => rsql`userId==${user.id}`,
}
```

Interpolated values are escaped, so user IDs and other dynamic values are injected safely.

## How enforcement works

Every resource endpoint routes through the [secure query builder](./secure-queries.md), which resolves the scope for the operation and combines it with the request filter before touching the database. Subscriptions resolve the `subscribe` scope at connect and match it in-memory against the changelog, so the live stream never leaks rows outside scope. See the [auth contract](../contracts/auth.md) for the guarantee.

## Related

- [RSQL](../core/rsql.md) · [Secure queries](./secure-queries.md) · [Filtering](../core/filtering.md) · [Fields & masking](../core/fields.md)
- [Subscriptions](../realtime/subscriptions.md) · [Auth contract](../contracts/auth.md)

---

## Secure query builder


The secure query builder is the layer `useResource` uses to enforce [authorization scopes](./scopes.md) on every read, count, aggregate, and mutation. You can also use it directly in custom routes when you need scope-safe database access.

`createScopeResolver` and `createResourceFilter` are exported from `covara`; the builder factory lives in `src/resource/secure-query.ts`.

```typescript
import { createScopeResolver, createResourceFilter, getUser } from "covara";
import { createSecureQueryBuilder } from "@/resource/secure-query";

const scopeResolver = createScopeResolver(config.auth);
const filterer = createResourceFilter(postsTable);

app.get("/api/my-posts", async (c) => {
  const builder = createSecureQueryBuilder(postsTable, db, scopeResolver, filterer, { user: getUser(c) });
  const posts = await builder.executeSelect("published==true", { limit: 10 });
  return c.json(posts);
});
```

## Methods

| Method | Description |
|--------|-------------|
| `executeSelect(filter?, opts?)` | Scoped select. `opts`: `limit`, `offset`, `orderBy`, `cursorCondition`. |
| `executeCount(filter?)` | Scoped count. |
| `executeAggregate(params, filter?)` | Scoped [aggregation](../core/aggregations.md). |
| `select(filter?)` | Build the scoped Drizzle `SQL` WHERE without executing. |
| `selectWithScope(op, filter?)` | Resolve the scope for a specific operation (`"read"`/`"update"`/`"delete"`). |

```typescript
const results = await builder.executeSelect('status=="active";createdAt>"2024-01-01"', { limit: 20 });
const count = await builder.executeCount('status=="published"');
const stats = await builder.executeAggregate({ groupBy: ["category"], count: true, avg: ["views"] });
```

The user's scope is always applied, so a query can only narrow within it:

```typescript
// auth.read scope: rsql`userId==${user.id}`
await builder.executeSelect('status=="draft"');
// → SELECT * FROM posts WHERE status = 'draft' AND userId = 'user123'
```

## Scoped mutations

```typescript
import { createSecureMutationBuilder } from "@/resource/secure-query";

const mutations = createSecureMutationBuilder(postsTable, db, scopeResolver, filterer, { user: getUser(c) });

const updateFilter = await builder.selectWithScope("update", 'category=="draft"');
await mutations.update(updateFilter, { status: "published" });

const deleteFilter = await builder.selectWithScope("delete", 'createdAt<"2023-01-01"');
await mutations.delete(deleteFilter);
```

## Admin bypass with audit logging

```typescript
const adminBuilder = builder.asAdmin("Admin data export");
const everything = await adminBuilder.executeSelect();
// logs: { level: "warn", type: "admin_scope_bypass", reason: "Admin data export", ... }

import { getAdminAuditLog, clearAdminAuditLog } from "@/resource/secure-query";
const entries = getAdminAuditLog(); // [{ reason, timestamp, userId }]
```

## Field-level write enforcement

Separately from scope filters, [`fields.writable`](../core/fields.md) is an enforced allowlist of columns a client may set, stripping protected columns (e.g. `ownerId`, `role`) from inbound bodies before hooks or the database see them — mass-assignment protection. See [Fields](../core/fields.md#write-enforcement-fieldswritable-mass-assignment-protection).

## Type safety

```typescript
const posts = await builder.executeSelect<Post>();
posts[0].title; // string
```

## Related

- [Authorization scopes](./scopes.md) · [Fields & masking](../core/fields.md) · [Filtering](../core/filtering.md)
- [Auth contract](../contracts/auth.md)

---

## Security headers


`createCovara` auto-mounts a security-headers middleware that sets sensible defaults on every response. You can tune it, and opt into a Content-Security-Policy (off by default so it never silently blocks your frontend).

## Defaults

| Header | Default value |
|--------|---------------|
| `X-Content-Type-Options` | `nosniff` |
| `X-Frame-Options` | `DENY` |
| `Referrer-Policy` | `strict-origin-when-cross-origin` |
| `X-DNS-Prefetch-Control` | `off` |
| `Cross-Origin-Opener-Policy` | `same-origin` |
| `Strict-Transport-Security` | `max-age=15552000; includeSubDomains` (on HTTPS or in production) |
| `Content-Security-Policy` | **not set** (opt-in) |

Each header is set only if absent, so your own routes can override any of them. HSTS is emitted only for HTTPS requests or when `isProduction()` is true.

## Configuring

Pass `securityHeaders` options (the same shape as the standalone middleware):

```typescript
import { createSecurityHeaders, STRICT_API_CSP } from "covara/middleware/securityHeaders";

const headers = createSecurityHeaders({
  contentSecurityPolicy: STRICT_API_CSP, // or your own policy string, or false
  contentTypeOptions: true,
  frameOptions: "DENY",                  // "DENY" | "SAMEORIGIN" | false
  referrerPolicy: "strict-origin-when-cross-origin", // or false
  dnsPrefetchControl: "off",             // or false
  crossOriginOpenerPolicy: "same-origin",// or false
  hsts: { maxAge: 15552000, includeSubDomains: true, preload: false }, // or false
});

app.use("*", headers);
```

## Content-Security-Policy

CSP is **off by default** because it is application-specific — a strict policy right for a JSON-only API will break an app that serves its own frontend. Enable it by passing a policy string.

For a pure JSON API, `STRICT_API_CSP` is a good starting point:

```typescript
import { STRICT_API_CSP } from "covara/middleware/securityHeaders";
// STRICT_API_CSP === "default-src 'none'; frame-ancestors 'none'"

createSecurityHeaders({ contentSecurityPolicy: STRICT_API_CSP });
```

For an app that serves a frontend, write a policy that allows your scripts/styles/connect sources.

## Disabling a header

Set any option to `false` to omit that header (e.g. `frameOptions: false` if you embed the app in an iframe, `hsts: false` to never send HSTS).

## Related

- [Middleware](../tooling/middleware.md) · [Account security](./account-security.md) · [CORS](../core/resources-and-app.md#createcovara)

---

## Session-based auth


`useAuth` wires up authentication: `/login`, `/signup`, `/logout`, and `/me` routes plus the middleware that populates the request [user](./overview.md#the-request-user). Two concerns are **decoupled**:

- **A session strategy** (`session:`) — *how* the authenticated identity is persisted, validated per request, and issued at login. Pick [`cookieSession`](#session-strategies) (server-side sessions) or [`jwtSession`](#session-strategies) (stateless JWTs).
- **Credential providers** — *who* the user is at login: `login`, `signup`, [`social`](./social.md), [`verification`](./account-security.md), [`mfa`](./mfa.md), [`magicLink`](./magic-links.md).

They compose freely: **any provider works with any session strategy** (e.g. [Passport social login that issues JWTs](#session-strategies)).

```typescript
import { cookieSession, useAuth, hashPassword, verifyPassword } from "covara";
import { eq } from "drizzle-orm";

const { router, middleware } = useAuth({
  session: cookieSession({
    getUserById: async (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
  }),
  login: {
    validateCredentials: async (email, password) => {
      const user = await db.query.users.findFirst({ where: eq(users.email, email) });
      return user && (await verifyPassword(password, user.passwordHash))
        ? { id: user.id, email: user.email, name: user.name }
        : null;
    },
  },
  signup: {
    createUser: async ({ email, password, name }) => {
      const [u] = await db.insert(users)
        .values({ id: crypto.randomUUID(), email, name, passwordHash: await hashPassword(password) })
        .returning();
      return { id: u.id, email: u.email, name: u.name };
    },
  },
});

app.route("/api/auth", router);
app.use("*", middleware);
```

With the factory, pass the result directly: `createCovara({ auth: { router, middleware } })` mounts the router at `<basePath>/auth` and applies the middleware (override with `auth: { router, middleware, path: "/auth" }`).

:::tip Session rotation
On a successful `/login`, the prior session cookie (if any) is invalidated before a new session is created — sessions are rotated on every login, mitigating session fixation.
:::

## `useAuth` options

```typescript
interface UseAuthOptions {
  session: SessionStrategy;        // cookieSession(...) | jwtSession(...)
  adapter?: AuthAdapter;           // deprecated: legacy adapter (mapped to a session internally)

  cookieName?: string;             // default "session"
  cookieOptions?: {
    httpOnly?: boolean;            // default true
    secure?: boolean;              // default true in production
    sameSite?: "strict" | "lax" | "none"; // default "lax"
    maxAge?: number;               // default 7 days
  };

  login?: { validateCredentials: (email, password) => Promise<AuthUser | null> };
  signup?: {
    createUser: (data: { email; password; name? }) => Promise<AuthUser>;
    validateEmail?: (email) => boolean | Promise<boolean>;
    validatePassword?: (password) => boolean | Promise<boolean>;
  };

  serializeUser?: (user) => Record<string, unknown>;

  onLogin?: (user, c) => void | Promise<void>;
  onLogout?: (user, c) => void | Promise<void>;
  onSignup?: (user, c) => void | Promise<void>;

  // Opt-in flows — see linked pages
  csrf?: boolean | CsrfOptions;             // → Account security
  throttle?: boolean | LoginThrottleOptions; // → Account security
  verification?: VerificationConfig;         // → Account security
  passwordReset?: PasswordResetConfig;       // → Account security
  passwordPolicy?: PasswordPolicy;           // → Passwords
  mfa?: MfaConfig;                           // → MFA
  magicLink?: MagicLinkConfig;               // → Magic links
}
```

## Routes & shapes

```jsonc
// POST /api/auth/login   { "email": "...", "password": "..." }
// → { "user": { "id", "email", "name" }, "sessionId": "sess_..." }

// POST /api/auth/signup  { "email": "...", "password": "...", "name": "..." }
// → { "user": { "id", "email", "name" } }

// GET  /api/auth/me      → { "user": {...}, "expiresAt": "..." }  or  { "user": null }

// POST /api/auth/logout  → { "success": true }
```

## Session strategies

The `session` strategy decides how the identity is persisted and validated — independent of how the user logged in. Both take `getUserById` (to hydrate the user from a session/token).

### `cookieSession` — server-side sessions

An opaque id in an `httpOnly` cookie, backed by a [session store](#session-stores). Revocable; rotates on login.

```typescript
import { cookieSession } from "covara";

cookieSession({
  getUserById: async (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
  store: myStore,                 // default: in-memory; use KV/Drizzle in prod
  cookieName: "session",          // default
  ttlMs: 24 * 60 * 60 * 1000,     // default
});
```

### `jwtSession` — stateless JWTs

Issues a short-lived access token (returned from `/login` as `{ accessToken }`) plus a refresh token (in an `httpOnly` cookie); validates the `Authorization: Bearer` header. Mounts `/refresh`.

```typescript
import { jwtSession } from "covara";

jwtSession({
  getUserById,
  secret: env.JWT_SECRET,
  accessTokenTtl: 15 * 60,            // seconds
  refreshTokenTtl: 7 * 24 * 60 * 60,
  refreshStore: kvStore,             // optional: makes refresh tokens revocable
});
```

### Any provider × any session

Because the strategy is decoupled from the credential providers, you can, for example, log in with **a Passport.js provider and issue JWTs** — previously impossible:

```typescript
import { useAuth, jwtSession, fromPassport } from "covara";
import { Strategy as GitHubStrategy } from "passport-github2";

useAuth({
  session: jwtSession({ getUserById, secret: env.JWT_SECRET, refreshStore }),
  social: {
    providers: [fromPassport(new GitHubStrategy({ /* ... */ }, (_a, _r, p, done) => done(null, p)))],
    findOrCreateUser: async ({ profile }) => upsertUser(profile),
  },
});
// GitHub login → refresh cookie set → POST /api/auth/refresh → bearer access token
```

### Legacy adapters (deprecated)

`createPassportAdapter` / `createAuthJsAdapter` / `createJWTAdapter` still work — pass one as `adapter` and `useAuth` maps it to a session strategy internally. Prefer `session` for new code.

```typescript
import { createPassportAdapter } from "covara";
useAuth({ adapter: createPassportAdapter({ getUserById }), login: { /* ... */ } });
```

## Session stores

`cookieSession` (and the legacy adapters) take a session store. Implement the interface or use a built-in.

```typescript
interface SessionStore {
  get(sessionId: string): Promise<SessionData | null>;
  set(sessionId: string, data: SessionData, ttlMs: number): Promise<void>;
  delete(sessionId: string): Promise<void>;
  touch(sessionId: string, ttlMs: number): Promise<void>;
  getAll?(): Promise<SessionData[]>; // optional, used by the admin UI
}
```

| Store | Import | Use |
|-------|--------|-----|
| In-memory | `InMemorySessionStore` | Development; lost on restart |
| KV (Redis / Durable Object / memory) | `createKVSessionStore` (from `covara/auth` stores) | Production, multi-instance |
| Drizzle | Drizzle session store (`covara/auth` stores) | DB-backed sessions |

```typescript
import { cookieSession, InMemorySessionStore } from "covara";
cookieSession({ getUserById, store: new InMemorySessionStore() });
```

`createKVSessionStore({ kv })` is backed by the [KV abstraction](../platform/kv.md), so it works with **any** KV adapter — Redis, the Cloudflare Durable Object store, or the in-memory store for tests — not only Redis:

```typescript
import { cookieSession } from "covara";
import { createKVSessionStore } from "covara/auth";
cookieSession({ getUserById, store: createKVSessionStore({ kv }) });
```

> `createRedisSessionStore` / `RedisSessionStore` remain as deprecated aliases of `createKVSessionStore` / `KVSessionStore`.

For Redis and Drizzle stores see [`src/auth/stores`]; provide a distributed store so sessions and [login throttling](./account-security.md) work across instances.

## Custom routes

A strategy's `issue(c, userId)` mints + transmits a session/token (sets the cookie for `cookieSession`, returns tokens for `jwtSession`) — reuse it in your own routes:

```typescript
import { cookieSession, readJsonBody } from "covara";

const session = cookieSession({ getUserById });

app.post("/custom-login", async (c) => {
  const { email, password } = await readJsonBody(c);
  const user = await validate(email, password);
  if (!user) return c.json({ error: "invalid" }, 401);
  const issued = await session.issue(c, user.id); // sets the session cookie
  return c.json({ user: issued.user });
});
```

## Related

- [Passwords](./passwords.md) · [Account security](./account-security.md) · [MFA](./mfa.md) · [Magic links](./magic-links.md)
- [JWT](./jwt.md) · [Scopes](./scopes.md) · [Client auth](../client/auth.md)

---

## Social login (Passport.js)


Covara can drive **any [Passport.js](https://www.passportjs.org/) OAuth2 strategy** as a social login — GitHub, Discord, Google, Facebook, Spotify, Twitch, GitLab, Slack, and the hundreds of others in the Passport catalog. You construct the strategy exactly as its docs show, wrap it with `fromPassport`, and hand it to [`useAuth`](./sessions.md). A successful login mints the **same session cookie** as a password login, so the rest of your app — `getUser(c)`, scopes, the client — works unchanged.

It runs on **Node and Cloudflare Workers**. See [How it works on Workers](#how-it-works-on-workers).

## Quick start

```bash
npm install passport-github2   # or any passport-* OAuth2 strategy
```

```typescript
import { Strategy as GitHubStrategy } from "passport-github2";
import { useAuth, fromPassport, cookieSession } from "covara";

const { router, middleware } = useAuth({
  // Social login works with ANY session strategy — swap for
  // jwtSession({ secret, getUserById }) to have GitHub login issue JWTs.
  session: cookieSession({
    getUserById: async (id) => db.query.users.findFirst({ where: eq(users.id, id) }),
  }),
  social: {
    providers: [
      fromPassport(
        new GitHubStrategy(
          {
            clientID: env.GITHUB_CLIENT_ID,
            clientSecret: env.GITHUB_CLIENT_SECRET,
            // Point this at the mounted callback route (see below).
            callbackURL: "https://myapp.com/api/auth/social/github/callback",
          },
          // The value you pass to done() becomes the SocialAccount; the bridge
          // normalizes it. Pass the profile straight through.
          (_accessToken, _refreshToken, profile, done) => done(null, profile)
        )
      ),
    ],
    findOrCreateUser: async ({ provider, providerAccountId, profile }) => {
      // Look up or create your app user from the provider account.
      const existing = await db.query.accounts.findFirst({
        where: and(eq(accounts.provider, provider), eq(accounts.providerAccountId, providerAccountId)),
      });
      if (existing) return db.query.users.findFirst({ where: eq(users.id, existing.userId) });

      const user = await createUser({ email: profile.email, name: profile.name, image: profile.image });
      await linkAccount(user.id, provider, providerAccountId);
      return user;
    },
    successRedirect: "/",
  },
});

app.route("/api/auth", router);
app.use("*", middleware);
```

That mounts two routes under the auth router:

| Route | Purpose |
|-------|---------|
| `GET /api/auth/social/:provider` | Start login — redirects the browser to the provider |
| `GET /api/auth/social/:provider/callback` | Provider callback — exchanges the code, resolves the user, sets the session cookie |

`:provider` is the strategy's name (`github`, `discord`, …). Point each strategy's `callbackURL` at its `/callback` route.

## From the client

Both client libraries start a login with a single call. After the server completes the OAuth flow it sets the session cookie and redirects back to `successRedirect`.

**TypeScript:**

```typescript
import { createClient } from "covara/client";

const client = createClient({ baseUrl: location.origin, credentials: "include" });

client.loginWithSocial("github");        // navigates the browser to the provider
// or build the URL yourself (e.g. for an  or React Native):
const url = client.socialLoginUrl("github");
```

**React:**

```tsx
import { useAuth } from "covara/client/react";

function SignIn() {
  const { signInWith, user, isAuthenticated } = useAuth();
  if (isAuthenticated) return Hi {user?.name};
  return (
    <>
      <button onClick={() => signInWith("github")}>Continue with GitHub</button>
      <button onClick={() => signInWith("discord")}>Continue with Discord</button>
    </>
  );
}
```

If the client is configured with a custom social mount, set it once:

```typescript
createClient({ baseUrl, social: { basePath: "/auth/social" } });
// React, without a client: useAuth({ socialBasePath: "/auth/social" })
```

## `findOrCreateUser`

Called after the provider verifies the user. It receives a `SocialAccount` and must return your app user (`{ id, email?, name?, image? }`):

```typescript
interface SocialAccount {
  provider: string;            // "github"
  providerAccountId: string;   // normalized profile.id — the account link key
  profile: NormalizedProfile;  // { id, email, name, image, username, raw }
  raw: unknown;                // exactly what your strategy's done() returned
}
```

`profile` is normalized from the standard Passport `Profile` shape (`displayName`, `emails`, `photos`, …). For non-standard providers, pass `mapProfile` to `fromPassport` or read `account.raw` directly. If you need the OAuth `accessToken`/`refreshToken`, have your strategy's verify return them (e.g. `done(null, { profile, accessToken })`) with a matching `mapProfile`, then read them off `account.raw`.

## CSRF & state

The bridge persists the strategy's OAuth `state`/PKCE handle between the redirect and the callback using a short-lived, `httpOnly` cookie (`covara_oauth_state`, default 10 min) plus a state store. A callback with a missing, expired, or mismatched state is rejected **before** any code exchange — this is the standard OAuth CSRF protection, enforced by the strategy itself.

- **Single Node process:** the default in-memory state store is fine.
- **Multiple instances / Cloudflare Workers:** the authorize and callback requests can hit different isolates, so use a shared store. If a [global KV](../platform/kv.md) is configured (`setGlobalKV`), the KV-backed store is selected **automatically**. To set it explicitly:

```typescript
import { createKvSocialStateStore } from "covara";

social: {
  providers: [/* ... */],
  findOrCreateUser: async () => { /* ... */ },
  stateStore: createKvSocialStateStore(),   // uses the global KV
}
```

## Configuration

```typescript
social: {
  providers: SocialProvider[];   // from fromPassport(...)
  findOrCreateUser: (account, c) => Promise<AuthUser>;
  basePath?: string;             // default "/social" (under the auth router)
  successRedirect?: string;      // default "/"
  failureRedirect?: string;      // default: 401 JSON problem
  stateStore?: SocialStateStore; // default: KV if configured, else in-memory
  stateCookieName?: string;      // default "covara_oauth_state"
  stateTtlMs?: number;           // default 600000
}
```

`fromPassport(strategy, options?)`:

```typescript
fromPassport(strategy, {
  name?: string;                 // defaults to strategy.name; required if it's the generic "oauth2"
  scope?: string | string[];     // override the requested scopes
  mapProfile?: (raw) => NormalizedProfile,
});
```

## How it works on Workers

Passport strategies don't actually need Express. `Strategy.authenticate(req)` only reads `req.query` / `req.headers` / `req.session` and signals its result through `this.success / fail / redirect / error` — methods Passport core injects, not Express. Covara injects them and synthesizes `req` from the Web request.

The one runtime-specific piece is that OAuth2 strategies do their HTTP through the legacy `node-oauth` package (`node:https`). All of its requests funnel through a single method, which the bridge swaps for `fetch`. After that, token exchange and profile fetch run over `fetch` — so the whole `passport-oauth2` family works on Workers with no `node:http`.

:::note Scope
The bridge covers **OAuth 2.0** strategies (the bulk of the catalog). OAuth 1.0a strategies (e.g. the legacy `passport-twitter`) sign requests with `node-oauth`'s OAuth1 client and are not supported on Workers. Strategies that pull in heavy Node-only crypto (some SAML/enterprise strategies) are Node-only.
:::

## Social login vs the OIDC provider

These solve different problems — see also [Federated login](./federated.md):

| | **Social login (`social` + Passport)** | **[Federated login](./federated.md)** (OIDC provider) |
|---|---|---|
| Use case | *Your* app lets users sign in with GitHub/Discord/Google/… | You run an [OIDC provider](./oidc-provider.md) that delegates to upstream IdPs |
| Provider requirement | Any OAuth 2.0 provider (Passport catalog) | OIDC-compliant IdP (discovery + `id_token`) |
| Covers GitHub/Discord/Spotify/… | ✅ | ❌ (no OIDC discovery document) |
| Result | A Covara **session** for your app | Your provider issues **its own OIDC tokens** |

Reach for **social login** when you just want "sign in with GitHub." Reach for the **OIDC provider** when you're building an identity provider for other apps — and note you can use the *same* Passport strategies there too, via [`backends.passport`](./federated.md#non-oidc-providers-passportjs), which lets your OIDC provider offer GitHub/Discord/… as upstreams and issue its own tokens.

---

## Client authentication


The client supports several auth strategies and a full OIDC PKCE flow. The React [`useAuth`](#useauth) hook exposes the current state; the underlying [transport](./overview.md#resilient-transport) refreshes tokens and retries `401`s automatically.

## `useAuth`

```tsx
import { useAuth } from "covara/client/react";

function App() {
  const { user, status, isAuthenticated, isLoading, logout, refetch, accessToken } = useAuth<User>();
  if (isLoading) return Loading…;
  if (!isAuthenticated) return <LoginPage />;
  return <button onClick={logout}>Sign out {user?.name}</button>;
}
```

### Strategies

| Strategy | Description |
|----------|-------------|
| `cookie` | Session cookies (default). |
| `jwt` | JWT bearer (auto-used when the client has `jwt` configured). |
| `bearer` | Manual bearer token (`token`). |
| `apiKey` | API key via `X-API-Key` (`apiKey`). |
| `auto` | Auto-detect from client configuration (default). |

```tsx
useAuth<User>();                                        // cookie (default)
useAuth<User>({ strategy: "jwt" });
useAuth<User>({ strategy: "bearer", token });
useAuth<User>({ strategy: "apiKey", apiKey: "..." });
useAuth<User>({ checkUrl: "/api/auth/session" });       // Passport/NextAuth
```

### Options & result

```typescript
interface UseAuthOptions {
  checkUrl?: string;   // default /api/auth/me
  logoutUrl?: string;  // default /api/auth/logout
  strategy?: "cookie" | "jwt" | "bearer" | "apiKey" | "auto";
  token?: string;      // bearer
  apiKey?: string;     // apiKey
  baseUrl?: string;
  authBasePath?: string;   // default /api/auth (login/signup/verify)
  socialBasePath?: string; // default /api/auth/social
}

interface UseAuthResult<TUser> {
  user: TUser | null;
  status: "loading" | "authenticated" | "unauthenticated";
  isAuthenticated: boolean;
  isLoading: boolean;
  logout: () => Promise<void>;
  refetch: () => Promise<void>;
  accessToken: string | null;
  // Email/password (refresh `user` on success)
  login: (email: string, password: string) => Promise<void>;
  signup: (input: { email: string; password: string; name?: string }) => Promise<void>;
  // Email confirmation
  requestEmailVerification: (email: string) => Promise<void>;
  confirmEmail: (email: string, token: string) => Promise<void>;
  // Social (Passport) — redirects to the provider
  signInWith: (provider: string) => void;
}
```

Set a global 401 handler to redirect on auth loss:

```tsx
useEffect(() => { client.setAuthErrorHandler(logout); }, [logout]);
```

### Email/password & social flows

The hook drives the [`useAuth` server routes](../auth/getting-started.md) directly — no hand-written `fetch`:

```tsx
const { login, signup, logout, signInWith, requestEmailVerification, confirmEmail } = useAuth<User>();

await login("a@b.com", "secret");        // refreshes `user`
await signup({ email, password, name }); // refreshes `user`
signInWith("github");                    // redirect to a social provider
```

This is the same code whether the server uses a [cookie or JWT session](../auth/sessions.md#session-strategies): with `jwtSession`, `login`/`signup` capture the returned access token and send it as a bearer automatically (cleared on `logout`).

Outside React, the same flows are first-class methods on the client:

```typescript
await client.session.signup({ email, password, name });
await client.session.requestEmailVerification(email);
await client.session.confirmEmail(email, token);
await client.session.login(email, password);
const user = await client.session.me<User>();
await client.session.logout();
client.loginWithSocial("github");
```

Both default to the `/api/auth` mount; override with `useAuth({ authBasePath })` or `createClient({ session: { basePath } })`.

For JWT login/signup/refresh control, use [`useJWTAuth`](../auth/jwt.md).

## OIDC PKCE flow

Configure `auth` on the client to talk to an [OIDC provider](../auth/oidc-provider.md). The client handles PKCE, token refresh, and 401 retry.

```typescript
import { createClient } from "covara/client";

const client = createClient({
  baseUrl: "https://api.myapp.com",
  auth: {
    issuer: "https://auth.myapp.com/oidc",
    clientId: "web-app",
    redirectUri: window.location.origin + "/callback",
  },
});

await client.auth.login();          // redirect to the provider
await client.auth.handleCallback(); // on /callback
client.auth.isAuthenticated();
client.auth.getUser();
await client.auth.logout();

const unsubscribe = client.auth.subscribe((state) => console.log(state.status, state.user));
```

### Config

```typescript
interface OIDCClientConfig {
  issuer: string;
  clientId: string;
  redirectUri: string;
  postLogoutRedirectUri?: string;
  scopes?: string[];               // default ["openid","profile","email"]
  autoRefresh?: boolean;           // default true
  refreshBufferSeconds?: number;   // default 60
  storage?: TokenStorage;          // default MemoryStorage
  flowType?: "redirect" | "popup"; // default "redirect"
}
```

### Callback page

```tsx
function CallbackPage() {
  const [error, setError] = useState<string | null>(null);
  useEffect(() => {
    client.auth.handleCallback().then(() => location.assign("/")).catch((e) => setError(e.message));
  }, []);
  return error ? Error: {error} : Completing sign in…;
}
```

### Token storage

```typescript
import { MemoryStorage, LocalStorageAdapter, SessionStorageAdapter } from "covara/client";

auth: { storage: new MemoryStorage() }                  // default, most secure
auth: { storage: new LocalStorageAdapter("myapp_") }    // persists across tabs
auth: { storage: new SessionStorageAdapter("myapp_") }  // until tab close
```

For React Native, provide an AsyncStorage-compatible `TokenStorage` — see [React Native](./react-native.md).

## Related

- [Auth overview](../auth/overview.md) · [OIDC provider](../auth/oidc-provider.md) · [JWT](../auth/jwt.md)
- [React Native](./react-native.md)

---

## Billing (client)


Configure `billing` on the client to talk to a mounted [billing router](../platform/billing.md), then use `client.billing.*` or the React hooks.

```typescript
import { getOrCreateClient } from "covara/client";

const client = getOrCreateClient({
  baseUrl: location.origin,
  billing: { basePath: "/api/billing" },
});

await client.billing.redirectToCheckout({
  plan: "pro_monthly",
  successUrl: location.origin + "/welcome",
});
```

## React hooks

```tsx
import { useCredits, useSubscription, useCheckout } from "covara/client/react";

function Billing() {
  const { balance, refresh } = useCredits();
  const { activeSubscription } = useSubscription();
  const { redirectToCheckout, loading } = useCheckout();

  return (
    
      Credits: {balance}
      Plan: {activeSubscription?.status ?? "none"}
      <button disabled={loading} onClick={() => redirectToCheckout({ plan: "pro_monthly", successUrl: location.origin + "/welcome" })}>
        Upgrade
      </button>
    
  );
}
```

- `useCredits` — `{ balance, refresh }` from the credits ledger.
- `useSubscription` — `{ activeSubscription }` (normalized across providers).
- `useCheckout` — `{ redirectToCheckout, loading }`.

These map to the [billing router](../platform/billing.md#server-router) endpoints (`/credits`, `/subscription`, `/checkout`, `/portal`). The router resolves the current user as the credits account, so the hooks operate on the signed-in user.

## Related

- [Billing (server)](../platform/billing.md) · [Client auth](./auth.md)

---

## File uploads (client)


The client talks to a [file resource](../platform/storage.md) for uploads, downloads, listing, and deletion — with upload progress and optional presigned direct-to-bucket transfers.

## Imperative client

```typescript
import { createFileClient } from "covara/client";

const files = createFileClient({ transport: client.transport, resourcePath: "/api/files" });

const result = await files.upload(file, { onProgress: ({ percent }) => console.log(`${percent}%`) });
const result2 = await files.uploadWithPresignedUrl(file, { onProgress: ({ percent }) => {} }); // S3/R2
const { data } = await files.list({ limit: 20 });
await files.delete(fileId);
```

`uploadWithPresignedUrl` requests a presigned URL, uploads the bytes directly to the bucket, then confirms — offloading the transfer from your server (S3/R2 only).

## React hooks

```tsx
import { useFileUpload, useFile, useFiles } from "covara/client/react";

function UploadButton() {
  const { upload, isUploading, progress, error } = useFileUpload({
    resourcePath: "/api/files",
    onSuccess: (file) => console.log("uploaded", file.id),
  });
  return (
    <input type="file" disabled={isUploading}
      onChange={(e) => e.target.files?.[0] && upload(e.target.files[0])} />
  );
}

function FileList() {
  const { files, isLoading, deleteFile, getDownloadUrl } = useFiles({ resourcePath: "/api/files" });
  return (
    
      {files.map((f) => (
        
          {f.filename}
          <button onClick={() => deleteFile(f.id)}>Delete</button>
        
      ))}
    
  );
}
```

- `useFileUpload` — `{ upload, isUploading, progress, error }`, with `onSuccess`.
- `useFile` — load a single file's metadata/URL.
- `useFiles` — `{ files, isLoading, deleteFile, getDownloadUrl }`.

`getDownloadUrl(id)` returns a URL suitable for ``/``; on React Native use it to fetch bytes — see [React Native](./react-native.md).

## Relating files

Upload returns a file record whose `id` you can store on another resource (e.g. `todo.imageId`) and load via [`?include=`](../core/relations.md). See [Storage → relating files](../platform/storage.md#relating-files-to-resources).

## Related

- [Storage](../platform/storage.md) · [Relations](../core/relations.md) · [React Native](./react-native.md)

---

## Live queries


A **LiveQuery** is the reactive store that powers [`useLiveList`](./react-hooks.md). It does the hybrid [fetch + subscribe](../realtime/subscriptions.md#hybrid-fetch--subscribe) dance, applies optimistic mutations, tracks connection status, and exposes a stable snapshot for `useSyncExternalStore`. Use it directly in non-React apps or for custom integrations.

```typescript
import { createLiveQuery, statusLabel } from "covara/client";

const todos = client.resource<Todo>("/api/todos");

const liveQuery = createLiveQuery(todos, {
  filter: 'userId=="123"',
  orderBy: "position",
  limit: 100,
}, {
  onAuthError: () => redirectToLogin(),
  getPendingCount: () => client.getPendingCount(),
  onIdRemapped: (optimisticId, serverId) => console.log(`${optimisticId} -> ${serverId}`),
});

const state = liveQuery.getSnapshot(); // stable reference
// { items, status, error, pendingCount, lastSeq }

const unsubscribe = liveQuery.subscribe(() => render(liveQuery.getSnapshot()));

liveQuery.mutate.create({ title: "New" });
liveQuery.mutate.update("123", { completed: true });
liveQuery.mutate.delete("123");

await liveQuery.refresh();
statusLabel(state.status, state.pendingCount); // "Live", "Loading…", "Offline (3 pending)"
liveQuery.destroy();
```

## State

```typescript
interface LiveQueryState<T> {
  items: T[];
  status: "loading" | "live" | "reconnecting" | "offline" | "error";
  error: Error | null;
  pendingCount: number;
  lastSeq: number;
}
```

## How it stays live

1. Fetch the initial page via `GET`.
2. Subscribe with `skipExisting=true`, passing the known IDs.
3. Apply `added`/`changed`/`removed` events to the in-memory list, honoring the [subscription mode](../realtime/subscriptions.md#subscription-modes-paginated-views).
4. Apply optimistic mutations immediately; reconcile against server responses (and remap temporary IDs).
5. On `invalidate` (sequence gap, auth change, backpressure), refetch.

The store is cached per `(path, options)` by the client, so multiple components reading the same query share one subscription. `client.invalidate(...)` and `client.prefetch(...)` operate on these caches — see [Overview](./overview.md#client-methods).

## Low-level subscriptions

For full control without the store, subscribe directly — see [Subscriptions → low-level API](../realtime/subscriptions.md#low-level-client-api).

## Related

- [React hooks](./react-hooks.md) · [Subscriptions](../realtime/subscriptions.md) · [Offline](./offline.md)

---

## Offline support


The client supports offline-first apps: mutations apply optimistically, queue locally while offline, and sync automatically when the connection returns. [`useLiveList`](./live-queries.md) wires all of this up for you.

## Enable it

```typescript
import { getOrCreateClient } from "covara/client";

const client = getOrCreateClient({
  baseUrl: location.origin,
  credentials: "include",
  offline: true, // LocalStorage with sensible defaults
});
```

```tsx
import { useLiveList } from "covara/client/react";

function TodoApp() {
  const { items, statusLabel, mutate, pendingCount } = useLiveList<Todo>("/api/todos", { orderBy: "position" });
  return (
    <>
      {items.map((t) => {t.title})}
      <button onClick={() => mutate.create({ title: "New" })}>Add</button>
      <footer>{statusLabel}{pendingCount > 0 && ` • ${pendingCount} pending`}</footer>
    </>
  );
}
```

Mutations update the UI instantly, queue when offline, sync on reconnect, and remap temporary IDs to server IDs — automatically.

## Advanced configuration

```typescript
import { createClient, LocalStorageOfflineStorage } from "covara/client";

const client = createClient({
  baseUrl: "/api",
  offline: {
    enabled: true,
    storage: new LocalStorageOfflineStorage("my-app-offline"),
    maxRetries: 5,
    retryDelay: 2000,
    onIdRemapped: (optimisticId, serverId) => console.log(`${optimisticId} -> ${serverId}`),
  },
  onError: (error) => console.error("Sync error:", error),
  onSyncComplete: () => console.log("All changes synced"),
});
```

### Storage backends

| Backend | Notes |
|---------|-------|
| `LocalStorageOfflineStorage("prefix")` | Default with `offline: true`. |
| `IndexedDB` | Higher capacity; provide via the `OfflineStorage` interface or the built-in IndexedDB storage. |
| `InMemoryOfflineStorage` | Tests. |

Implement your own by satisfying `OfflineStorage` (`getMutations`/`addMutation`/`updateMutation`/`removeMutation`/`clear`).

## Optimistic mutations (imperative)

```typescript
const users = client.resource<User>("/users");

const created = await users.create({ name: "Alice" }, { optimistic: true }); // temp id like "optimistic_..."
await users.update("123", { name: "Alice Smith" }, { optimistic: true });
await users.delete("123", { optimistic: true });
```

## Mutation queue

```typescript
await client.offline?.getPendingMutations();   // [{ id, type, resource, data, status, retryCount }]
await client.offline?.syncPendingMutations();  // trigger sync
await client.offline?.clearMutations();         // clear (use with care)
client.offline?.getIsOnline();                  // current status
```

The client listens to browser `online`/`offline` events and syncs when reconnecting.

### Mutation states

| State | Meaning |
|-------|---------|
| `pending` | Waiting to sync |
| `processing` | Syncing now |
| `failed` | Sync failed; will retry |

## Conflict resolution

When syncing, use the `OfflineManager` to resolve conflicts (server-wins / client-wins / merge):

```typescript
import { createOfflineManager, InMemoryOfflineStorage } from "covara/client";

const offlineManager = createOfflineManager({
  config: { enabled: true, maxRetries: 5, storage: new InMemoryOfflineStorage() },
  onMutationSync: async (mutation) => {
    if (mutation.type === "update") {
      const current = await resource.get(mutation.objectId!);
      if (current.updatedAt > mutation.timestamp) {
        return; // server wins — or merge / client wins
      }
      await resource.update(mutation.objectId!, mutation.data);
    }
  },
  onMutationFailed: (mutation, error) => console.error(mutation, error),
  onSyncComplete: () => console.log("done"),
});
```

[Optimistic locking (ETags)](../core/optimistic-locking.md) surfaces server-side conflicts as `412`s you can reconcile.

## Without React

```typescript
import { createLiveQuery } from "covara/client";

const liveQuery = createLiveQuery(client.resource<Todo>("/todos"), { orderBy: "createdAt:desc" });
liveQuery.subscribe(() => render(liveQuery.getSnapshot()));
liveQuery.mutate.create({ text: "x", completed: false });
liveQuery.destroy();
```

## Limitations

- Read operations require the network (cache separately if needed).
- Batch operations are not queued (single-item mutations only).
- Subscription events are lost while offline (a full sync runs on reconnect).
- Optimistic IDs are temporary and change after sync (handle via `onIdRemapped`).

## Related

- [Live queries](./live-queries.md) · [Optimistic locking](../core/optimistic-locking.md) · [React hooks](./react-hooks.md)
- [Offline-sync contract](../contracts/offline-sync.md)

---

## Client library overview


The Covara client is a type-safe, real-time client for your API: typed CRUD, a fluent query builder, live subscriptions, optimistic updates, an offline queue, and React hooks. It's included with the main package.

```typescript
import { createClient, getOrCreateClient } from "covara/client";
import { useLiveList, useAuth } from "covara/client/react";
```

## Setup

Use `getOrCreateClient` for HMR-safe initialization (returns the existing instance if one exists):

```typescript
import { getOrCreateClient } from "covara/client";

export const client = getOrCreateClient({
  baseUrl: location.origin,
  credentials: "include",
  offline: true,
});
```

`createClient` always makes a fresh instance.

### Configuration

| Option | Type | Description |
|--------|------|-------------|
| `baseUrl` | `string` | API server base URL. |
| `credentials` | `RequestCredentials` | `"include"` / `"same-origin"` / `"omit"`. |
| `headers` | `Record<string,string>` | Default headers. |
| `timeout` | `number` | Default request timeout (ms); aborts when exceeded. |
| `offline` | `boolean \| OfflineConfig` | [Offline support](./offline.md). |
| `auth` | `OIDCClientConfig` | [OIDC](./auth.md) flow. |
| `jwt` | `{ authPath }` | [JWT](./auth.md) auth. |
| `billing` | `{ basePath }` | [Billing](./billing.md) client. |
| `onError` | `(error) => void` | A mutation failed to sync. |
| `onSyncComplete` | `() => void` | Offline sync finished. |
| `authCheckUrl` | `string` | Auth status URL (default `/api/auth/me`). |
| `parseDates` | `boolean \| DateFieldRegistry` | Convert ISO date strings to `Date` ([dates](#working-with-dates)). |

## Resilient transport

Built for unreliable networks:

- **Timeouts & cancellation** — a default `timeout` aborts each request via an internal `AbortController`; the low-level transport also accepts a per-request `signal` and `timeoutMs`, combined so either cancels.
- **Automatic 401 refresh-and-retry** — with [`auth`](./auth.md) (OIDC) or `jwt` configured, a `401` triggers one token refresh and a transparent retry; if refresh fails, the original `401` surfaces.
- **SSE reconnect with jitter** — [subscriptions](../realtime/subscriptions.md) reconnect with exponential backoff + randomized jitter (no stampede on server restart) and resume from the last sequence.

## Client methods

```typescript
const todos = client.resource<Todo>("/api/todos");      // typed resource client

client.setAuthToken("jwt");                              // bearer auth
client.clearAuthToken();
client.setAuthErrorHandler(() => location.assign("/login")); // global 401 handler
await client.getPendingCount();                          // queued offline mutations
const { user } = await client.checkAuth();

await client.session.login(email, password);             // email/password session auth
client.loginWithSocial("github");                        // social (Passport) login
// also: session.signup / logout / requestEmailVerification / confirmEmail / me — see Client auth

client.invalidate("/api/todos");                         // mark cached LiveQueries stale → refetch
client.invalidate((path, opts) => opts.filter === "completed==true");
await client.prefetch("/api/todos", { orderBy: "createdAt:desc", limit: 20 }); // warm the cache
```

`invalidate` accepts a path/prefix or a predicate and returns how many cached queries refreshed (propagates across tabs when [`offline.tabSync`](./offline.md) is on). `prefetch` warms the [LiveQuery](./live-queries.md) cache so a later `useLiveList` reads instantly.

## Working with dates

Responses carry dates as ISO 8601 **strings** by default (JSON-safe). Get `Date` objects two ways:

```typescript
import { toDate, toDateOrNull } from "covara/client";

const created = toDate(todo.createdAt);     // Date
const due = toDateOrNull(todo.dueAt);       // Date | null

// or convert on the transport:
const client = createClient({ baseUrl: "/api", parseDates: true });
// scoped: parseDates: { "/api/todos": ["createdAt", "dueAt"] }
```

[Generated types](./typegen.md) mark date columns as the branded `ISODateString` (a `string` subtype) so the compiler steers you toward `toDate(...)`.

## Error handling

```typescript
import { TransportError } from "covara/client";

try {
  await todos.get("nope");
} catch (error) {
  if (error instanceof TransportError) {
    if (error.isNotFound()) {/* 404 */}
    else if (error.isUnauthorized()) {/* 401 */}
    else if (error.isForbidden()) {/* 403 */}
    else if (error.isRateLimited()) console.log("retry after", error.retryAfter);
    else if (error.isValidationError()) console.log(error.details);
  }
}
```

## Where to go next

- **[Queries & repository](./queries.md)** — CRUD, the fluent query builder, filter helpers.
- **[React hooks](./react-hooks.md)** — `useLiveList`, `useMutation`, `useInfiniteList`, and more.
- **[Live queries](./live-queries.md)** — the reactive store under the hooks.
- **[Offline](./offline.md)** · **[Auth](./auth.md)** · **[File uploads](./files.md)** · **[Type generation](./typegen.md)** · **[React Native](./react-native.md)**

---

## Queries & repository


`client.resource<T>(path)` returns a typed repository for one endpoint. It exposes direct CRUD methods plus a fluent, type-narrowing `query()` builder.

```typescript
interface Todo { id: string; title: string; completed: boolean }
const todos = client.resource<Todo>("/api/todos");
```

## CRUD

```typescript
const { items, hasMore, nextCursor } = await todos.list({
  filter: "completed==false",
  orderBy: "createdAt:desc",
  limit: 20,
  cursor: nextCursor,
  select: ["id", "title"],
  include: "category,tags",
  totalCount: true,
});

const todo = await todos.get("todo-123", { select: ["id", "title"] });
const created = await todos.create({ title: "Buy groceries", completed: false });
const updated = await todos.update("todo-123", { completed: true });
await todos.delete("todo-123");
```

For offline/optimistic mutations pass `{ optimistic: true }` or `{ optimisticId }` — see [Offline](./offline.md).

## Batch & RPC

```typescript
await todos.batchCreate([{ title: "A" }, { title: "B" }]);
const { count } = await todos.batchUpdate("completed==false", { completed: true });
await todos.batchDelete("completed==true");

const result = await todos.rpc<{ ids: string[] }, { archived: number }>("archive", { ids: ["1", "2"] });
```

See [Batch operations](../core/batch.md) and [Procedures](../core/procedures.md).

## Aggregations

```typescript
const stats = await todos.aggregate({ groupBy: ["completed"], count: true });
// { groups: [{ key: { completed: true }, count: 5 }, ...] }
```

## The query builder

`query()` is an **immutable**, chainable builder with full type inference. `select` narrows the return type to exactly the chosen fields.

```typescript
const { items } = await users.query().select("id", "name").list();
items[0].name;  // ✓
items[0].email; // ✗ type error — not selected
```

```typescript
const activeUsers = await users
  .query()
  .select("id", "name", "email")
  .filter("age>=18")
  .filter('role=="user"')   // filters AND together
  .orderBy("name:asc")
  .limit(10)
  .list();

const user = await users.query().select("id", "name").get("user-123");
const newest = await users.query().orderBy("createdAt:desc").first();   // T | null
const adultCount = await users.query().filter("age>=18").count();       // number
```

Each method returns a **new** builder, so a base query can branch:

```typescript
const base = users.query().filter("age>=18");
const admins = base.filter('role=="admin"');
const regular = base.filter('role=="user"'); // base unchanged
```

### Builder methods

| Method | Description |
|--------|-------------|
| `select(...fields)` | Narrow returned fields (and type). |
| `filter(f)` / `where(f)` | Add a filter (AND). |
| `orderBy(s)` · `limit(n)` · `cursor(c)` · `include(s)` | List options. |
| `withTotalCount()` | Request the total count. |
| `groupBy(...)` · `withCount()` · `sum/avg/min/max(...)` | Aggregation. |
| `list()` · `get(id)` · `first()` · `count()` · `aggregate()` | Execute. |

### Type-safe aggregations

```typescript
const stats = await users
  .query()
  .groupBy("role")
  .withCount()
  .avg("age")        // numeric fields only
  .sum("score")
  .min("name")       // comparable fields
  .max("createdAt")
  .aggregate();
// typed: { groups: [{ key: { role }, count, avg: { age }, sum: { score }, min: { name }, max: { createdAt } }] }
```

## Filter helpers

Instead of hand-writing [RSQL](../core/filtering.md), build it with `q` (values escaped automatically):

```typescript
import { q } from "covara/client";

const filter = q.and(
  q.gte("age", 18),
  q.or(q.eq("role", "user"), q.eq("role", "admin")),
  q.contains("name", "jo"),
);
const adults = await users.query().filter(filter).list();
```

Builders: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `notLike`, `ilike`, `in`, `out`, `isNull`, `isNotNull`, `startsWith`, `endsWith`, `contains`, `icontains`, `between`, `and`, `or`, `raw`. There is no `q.not` — use the negated operators.

### Typed filter builder `f<T>()`

For compile-time field/value checking:

```typescript
import { f } from "covara/client";

const filter = f<Todo>().and(
  f<Todo>().eq("completed", false),   // must be a boolean field of Todo
  f<Todo>().gte("createdAt", since),
);
// f<Todo>().eq("complted", false)    // ✗ type error: not a key of Todo
```

It emits the same RSQL as `q`, so it drops straight into `.filter(...)`.

## Generated field-metadata types

[Type generation](./typegen.md) emits helpers for type-safe field references:

```typescript
export type UserFields = "id" | "name" | "email" | "age" | "role";
export type UserNumericFields = "age" | "score";
export type UserComparableFields = "id" | "name" | "email" | "age" | "createdAt";
```

## Related

- [React hooks](./react-hooks.md) · [Type generation](./typegen.md) · [Filtering](../core/filtering.md)
- [Pagination](../core/pagination.md) · [Aggregations](../core/aggregations.md)

---

## React hooks


Import hooks from `covara/client/react`. They build on the [LiveQuery store](./live-queries.md) and the typed [repository](./queries.md).

## `useLiveList`

The primary hook for real-time lists with optimistic mutations.

```tsx
import { useLiveList } from "covara/client/react";

function TodoList() {
  const {
    items, status, statusLabel, error, pendingCount,
    isLoading, isLive, isOffline, isReconnecting,
    hasMore, totalCount, isLoadingMore,
    mutate, refresh, loadMore,
  } = useLiveList<Todo>("/api/todos", {
    filter: 'userId=="123"',
    orderBy: "position",
    limit: 100,
    include: "category,tags",
    subscriptionMode: "strict",
    enabled: true,
    select: ["id", "title", "completed"],
  });

  return (
    
      {items.map((t) => (
        
          <input type="checkbox" checked={t.completed}
            onChange={() => mutate.update(t.id, { completed: !t.completed })} />
          {t.title}
          <button onClick={() => mutate.delete(t.id)}>×</button>
        
      ))}
    
  );
}
```

`status`: `"loading" | "live" | "reconnecting" | "offline" | "error"`. `mutate.create/update/delete` apply [optimistically](./offline.md). Pass a [typed `ResourceClient`](./typegen.md) instead of a path to infer `T`:

```tsx
const { items } = useLiveList(client.resources.todos, { orderBy: "position" });
```

### Pagination

With a `limit`, the hook exposes `hasMore`, `totalCount`, `isLoadingMore`, and `loadMore()`:

```tsx
const { items, hasMore, loadMore, isLoadingMore } = useLiveList<Todo>("/api/todos", { limit: 20 });
{hasMore && <button onClick={loadMore} disabled={isLoadingMore}>Load more</button>}
```

### Subscription modes

Control how other clients' changes affect a paginated view — `strict` (default with `limit`), `sorted`, `append`, `prepend`, or `live` (default without `limit`). See [Subscriptions → modes](../realtime/subscriptions.md#subscription-modes-paginated-views).

### Type-safe projections

```tsx
const { items } = useLiveList<User, "id" | "name" | "avatar">("/api/users", { select: ["id", "name", "avatar"] });
// items: { id; name; avatar }[]
```

### Relations & optimistic updates

With `include`, changing a foreign key clears the stale relation immediately and refills it from the server response. For instant UX, look it up from local cache (`todo.category ?? categories.find(c => c.id === todo.categoryId)`). See [Subscriptions → relations](../realtime/subscriptions.md#relations-in-events).

## `useInfiniteList`

Cursor-paginated live list; pages accumulate into `items` and stay realtime-aware.

```tsx
const { items, fetchNextPage, hasNextPage, isFetchingNextPage } =
  useInfiniteList<Todo>("/api/todos", { limit: 20, orderBy: "createdAt:desc" });
```

## `useLiveAggregate`

Live [aggregation](./live-queries.md) that recomputes on every change. See [Aggregate subscriptions](../realtime/aggregate-subscriptions.md).

```tsx
const { groups, isLive } = useLiveAggregate("/api/todos", { groupBy: ["completed"], count: true });
```

## `useMutation`

Standalone mutation hook usable outside a list; integrates with optimistic updates, the offline queue, and invalidation.

```tsx
const { mutate, mutateAsync, status, error, reset } = useMutation<Todo>("/api/todos", {
  invalidates: ["/api/todos"],
  onSuccess: (todo) => toast(`Created ${todo.id}`),
});

mutate({ kind: "create", data: { title: "New" } });
mutate({ kind: "update", id: "1", data: { completed: true } });
mutate({ kind: "delete", id: "2" });

// custom function form
const remove = useMutation(async ({ id }: { id: string }, ctx) => {
  await ctx.resource.delete(id);
  ctx.invalidate("/api/todos");
}, { resource: "/api/todos" });
```

## `useSearch`

Debounced [full-text search](../core/search.md):

```tsx
const { items, isSearching, search, clear } = useSearch(client.resources.todos, { enabled: true });
search("important");
```

## Invalidation & prefetch

```tsx
import { useInvalidate } from "covara/client/react";

const invalidate = useInvalidate();
await save();
invalidate("/api/todos"); // same semantics as client.invalidate
```

`client.prefetch(path, options)` warms the cache so a later `useLiveList` skips the loading flash. See [Overview](./overview.md#client-methods).

## Other hooks

| Hook | Purpose | Page |
|------|---------|------|
| `useAuth` | Auth state (cookie/JWT/bearer/apiKey/auto) | [Client auth](./auth.md) |
| `useJWTAuth` | JWT login/signup/refresh | [JWT](../auth/jwt.md) |
| `usePublicEnv` | Public env vars | [Environment variables](../deployment/environment-variables.md) |
| `useFileUpload` / `useFile` / `useFiles` | File uploads | [File uploads](./files.md) |
| `useCredits` / `useSubscription` / `useCheckout` | Billing | [Billing hooks](./billing.md) |

## Related

- [Live queries](./live-queries.md) · [Queries & repository](./queries.md) · [Offline](./offline.md)
- [Subscriptions](../realtime/subscriptions.md) · [Type generation](./typegen.md)

---

## React Native


The Covara client makes no DOM assumptions, so the same client, [repository](./queries.md), [hooks](./react-hooks.md), and [subscriptions](../realtime/subscriptions.md) run in React Native. A few integration points differ from the browser.

## Token storage

OIDC/JWT tokens are stored through a pluggable `TokenStorage`. In the browser the default is `MemoryStorage` (or `LocalStorageAdapter`); in React Native, provide an [AsyncStorage](https://react-native-async-storage.github.io/async-storage/)-compatible adapter:

```typescript
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createClient } from "covara/client";

const asyncStorageAdapter = {
  getItem: (key: string) => AsyncStorage.getItem(key),
  setItem: (key: string, value: string) => AsyncStorage.setItem(key, value),
  removeItem: (key: string) => AsyncStorage.removeItem(key),
};

const client = createClient({
  baseUrl: "https://api.myapp.com",
  auth: {
    issuer: "https://auth.myapp.com/oidc",
    clientId: "mobile-app",
    redirectUri: "myapp://callback",
    storage: asyncStorageAdapter, // satisfies TokenStorage
  },
});
```

The same applies to [`useJWTAuth`](../auth/jwt.md) — pass an AsyncStorage-compatible storage.

## Transport & offline backends

The [transport](./overview.md#resilient-transport) and [offline](./offline.md) layers are environment-aware:

- `fetch` and SSE work over React Native's networking.
- For the offline queue, use `InMemoryOfflineStorage` or supply an AsyncStorage/SQLite-backed `OfflineStorage` implementation (the browser-only `LocalStorageOfflineStorage`/`IndexedDBOfflineStorage` aren't available natively).
- [`offline.tabSync`](./offline.md) (BroadcastChannel) is a no-op outside the browser — leave it off.

```typescript
import { createClient, InMemoryOfflineStorage } from "covara/client";

const client = createClient({
  baseUrl: "https://api.myapp.com",
  offline: { enabled: true, storage: new InMemoryOfflineStorage() }, // or your AsyncStorage-backed store
});
```

## Files

There's no ``/`` — use `getDownloadUrl(id)` from [`useFiles`](./files.md) (or the file client) to obtain a URL, then fetch the bytes with React Native's `fetch`/`Image` source:

```tsx
const { getDownloadUrl } = useFiles({ resourcePath: "/api/files" });
<Image source={{ uri: getDownloadUrl(file.id) }} />;
```

## Hooks

[`useLiveList`](./react-hooks.md), `useMutation`, `useAuth`, `useJWTAuth`, `useFileUpload`, and the billing hooks all work unchanged — they depend only on React, not the DOM.

## Related

- [Client overview](./overview.md) · [Auth](./auth.md) · [Offline](./offline.md) · [File uploads](./files.md)

---

## Type generation


Covara generates TypeScript types from your running API, giving you end-to-end type safety: resource interfaces, input/update types, field-metadata helpers for the [query builder](./queries.md), [public env](../deployment/environment-variables.md) types, and a typed client factory.

## CLI

```bash
npx covara types --url http://localhost:3000 --out src/generated/api-types.ts
```

Or a script entry point:

```typescript
// scripts/typegen.ts
import { createTypegenCLI } from "covara/client";
await createTypegenCLI(process.argv.slice(2));
```

```bash
tsx scripts/typegen.ts http://localhost:3000 typescript > src/generated/api-types.ts
```

## Programmatic

```typescript
import { generateTypes } from "covara/client";
import { writeFileSync } from "fs";

const result = await generateTypes({
  serverUrl: "http://localhost:3000",
  output: "typescript",
  includeClient: true,
  includeEnv: true,   // default true
  envPath: "/api/env",
});
writeFileSync("./src/generated/api-types.ts", result.code);
```

## What's generated

```typescript
// Resource interfaces
export interface Todo { id: string; title: string; completed: boolean; /* ... */ }

// Input / update types (auto-increment excluded; PKs, nullable, and default fields optional)
export type TodoInput = { title: string; note?: string | null };
export type TodoUpdate = Partial<TodoInput>;

// Field metadata (for type-safe queries)
export type TodoFields = "id" | "title" | "completed";
export type TodoNumericFields = "position";
export type TodoComparableFields = "id" | "title" | "createdAt";

// Path constants
export const ResourcePaths = { todo: "/api/todos", user: "/api/users" } as const;

// Public env type
export type PublicEnv = { PUBLIC_API_URL: string; PUBLIC_VERSION: string };

// Typed client factory
export function createTypedClient(baseClient): TypedCovaraClient;
```

Date columns are emitted as the branded `ISODateString` so the compiler nudges you toward [`toDate(...)`](./overview.md#working-with-dates).

## Typed client factory

```typescript
import { getOrCreateClient } from "covara/client";
import { createTypedClient } from "./generated/api-types";

const client = createTypedClient(getOrCreateClient({ baseUrl: location.origin, credentials: "include" }));

const todos = await client.resources.todos.list();      // Todo[] — no type parameter needed
const result = await client.resources.todos.query().select("id", "title").filter("completed==false").list();
const stats = await client.resources.users.query().groupBy("role").withCount().avg("age").aggregate();
```

With React hooks, types are inferred from the typed resource:

```tsx
import { useLiveList } from "covara/client/react";
const { items, mutate } = useLiveList(client.resources.todos, { orderBy: "position" }); // items: Todo[]
```

## Related

- [Queries & repository](./queries.md) · [Client overview](./overview.md) · [Environment variables](../deployment/environment-variables.md)
- [CLI](../tooling/cli.md) · [OpenAPI](../tooling/openapi.md)

---

## Authentication Contracts


## Guarantees

### Session strategy decoupling
- **Orthogonal to credentials**: `useAuth`'s `session` strategy (how the identity is persisted/validated/issued) is independent of the credential providers (`login`/`signup`/`social`/`verification`/`mfa`/`magicLink`). Any provider composes with any strategy — e.g. a Passport social provider issuing JWTs.
- **Single issuance path**: every successful login (password, social, magic link, signup) goes through `strategy.issue(c, userId)`; the auth middleware authenticates every request through `strategy.authenticate(c)`. `cookieSession` mints a server-side session + cookie; `jwtSession` mints a bearer access token + refresh cookie and exposes `/refresh`.
- **Back-compat**: a legacy `adapter` passed to `useAuth` is mapped to a session strategy internally, preserving its prior behavior.

### Token Validation
- **Required claims checked**: `iss`, `aud`, `exp` are always validated
- **Algorithm enforcement**: Only configured algorithms accepted; `none` always rejected
- **Clock skew tolerance**: Configurable tolerance for `exp`, `nbf`, `iat` checks
- **Signature verification**: All tokens are cryptographically verified

### OIDC Compliance
- **Discovery support**: `/.well-known/openid-configuration` endpoint provided
- **PKCE required**: Public clients must use PKCE (code_challenge); `security.pkce.required` extends this to all clients
- **PKCE plain rejected**: `code_challenge_method=plain` is always rejected; only `S256` is supported and advertised
- **State validation**: `state` parameter validated on callback
- **Revocation (RFC 7009)**: `POST /revoke` invalidates a refresh token after client authentication
- **Introspection (RFC 7662)**: `POST /introspect` reports `{ active }` and claims for access/refresh tokens after client authentication
- **Client secret hashing**: Stored secrets prefixed `scrypt$` are verified with scrypt; plaintext secrets are compared in constant time

### OIDC Hardening
- **Redirect URI component validation**: `redirect_uri` is matched component-by-component (protocol, host, port, normalized path, and query/fragment when registered), never by prefix; an unregistered URI is rejected with `400` before any redirect is issued
- **Federated id_token verification**: external `id_token`s are signature-verified against the provider's JWKS (issuer + audience checked), the nonce is compared to the stored interaction nonce, and the `id_token` `sub` is cross-checked against the `userinfo` `sub`
- **External login resumes the interaction**: a successful external callback (federated OIDC or `backends.passport`) establishes the provider session and continues the pending `/authorize` interaction to consent or the authorization-code redirect — the same completion path as email/password login; it never returns the user as a bare JSON body
- **Passport backend state binding**: `backends.passport` carries the OAuth `state`/PKCE handle across the redirect→callback in a signed, `httpOnly`, short-lived cookie + state store; a callback with missing/expired/mismatched state is rejected before any token exchange
- **Correct at_hash**: the `id_token` `at_hash` claim is the left-half of the hash matching the signing algorithm, computed whenever an access token is issued
- **Endpoint rate limiting**: `/token`, `/jwks`, `/introspect` rate-limited per client/IP when `security.rateLimiting` is configured (KV-backed when a global KV exists)
- **Persistent stores by default**: clients, codes, refresh tokens, consents, interactions, and state are KV-backed (with expiry-derived TTLs) whenever a global KV is registered; `stores.type: "memory"` forces in-memory
- **Dynamic registration is opt-in**: `POST /register` returns `404` unless `registration.enabled` is true; an `initialAccessToken`, when set, is required as a Bearer token
- **Consent revocation + TTL**: `POST /consent/revoke` clears a user's consent (one client or all) for an authenticated session; stored consents expire after `security.consent.ttlSeconds` (default 1 year)
- **login_hint escaping**: dynamic values in the default login template are HTML-escaped

### Account Security Flows (opt-in via `useAuth`)
- **Password policy**: when `passwordPolicy` is set, weak passwords are rejected with `422` on `POST /signup` and `POST /password/reset`; a built-in denylist of common passwords is enabled by default
- **MFA/TOTP**: `mfa` adds `/mfa/enroll`, `/mfa/enroll/confirm`, and `/mfa/verify`; enrollment is two-step (created disabled, then confirmed). With `requireOnLogin`, `/login` returns `{ mfaRequired: true }` (`401`) for enrolled users until a valid TOTP or single-use backup code is supplied; a used backup code triggers `consumeBackupCode`
- **Magic links**: `magicLink` adds `/magic-link/request` (always returns `{ success: true }`, anti-enumeration) and `/magic-link/verify` (single-use token, creates the session)
- **API keys**: `createApiKey`/`verifyApiKey`/`rotateApiKey`/`revokeApiKey` store only a hash of the key; the raw key (`[prefix_]<id>.<secret>`) is returned once; verification returns a typed `reason` (`not_found`/`expired`/`mismatch`) on failure

### Field-Level Write Enforcement (mass-assignment protection)
- **Enforced allowlist**: when `fields.writable` is configured, any table column not in the list is stripped from create/update bodies (single, batch, and `POST /batch/upsert`) before hooks and the database see it
- **Exemptions**: the primary key and `generatedFields` are never stripped; non-column keys (relation payloads) pass through
- **Hook precedence**: stripping happens before lifecycle hooks, so a server-side hook can still set protected fields
- **strictInput**: with `strictInput: true`, unknown fields are rejected with `422` instead of being silently ignored

### Password Storage
- **Scrypt hashing**: `hashPassword` derives a self-describing `scrypt$N=..,r=..,p=..$salt$hash` string with a per-hash random salt
- **Constant-time verification**: `verifyPassword` compares using `timingSafeEqual` and returns `false` for any unparseable input
- **Rehash signalling**: `needsRehash` returns `true` when stored parameters are weaker than the target (or the hash is unparseable)

### Session Security
- **Session rotation**: Session ID rotated on login (prior session invalidated, prevents fixation)
- **Logout invalidation**: All session tokens invalidated on logout
- **Bulk invalidation**: Adapters may implement `invalidateUserSessions(userId, exceptSessionId?)`; password reset uses it when `logoutEverywhere` is set
- **Indexed bulk invalidation**: When the session store implements the per-user index (`getByUser`/`deleteByUser` — the Redis, Drizzle, and in-memory stores all do), bulk invalidation touches only that user's sessions; the scan-all `getAll()` path is a fallback for stores without the index
- **Session activity metadata**: Login/signup store the client IP and user agent in `session.data` (`ipAddress`, `userAgent`); session use stamps `session.data.lastActiveAt`, throttled to at most one persisted write per minute per session and fire-and-forget (activity tracking never blocks or fails auth)
- **Cookie security**: HttpOnly, Secure (in production), SameSite attributes set

### Multi-Tenant
- **Issuer isolation**: Same `sub` from different `iss` = different users
- **Issuer whitelist**: Only configured issuers accepted

### Field-Level Read Masking
- **Allowlist semantics**: When `fields.readable` is configured on a resource, only the listed table columns may appear in any response
- **Universal application**: Masking applies to list, get, create, update, batch, and search responses, plus every subscription event (`existing`, `added`, `changed`) and the initial subscription snapshot
- **No client bypass**: A hidden column cannot be recovered via `?select=` or by subscribing — masking is enforced server-side after projection
- **Column-only**: Only table columns are stripped; relation keys, computed values, and internal markers (`_etag`, `_optimisticId`) pass through

### Relation Scope Enforcement
- **Included relations respect target scope**: On the read path (`GET /` and `GET /:id` with `?include=`), each included relation AND-s the target resource's `read` scope (resolved for the effective/impersonated user) into its query — a relation cannot return rows the user could not read directly
- **Deny semantics**: A user denied read on the target resource yields `null` (`belongsTo`/`hasOne`) or an empty array (`hasMany`/`manyToMany`) for that relation; out-of-scope rows are filtered, not just hidden
- **Applies to discovered relations**: Auto-discovered (`autoRelations`) relations use the same enforced loader as explicit ones
- **Unregistered targets**: Relations to tables not registered as resources have no scope to enforce (no resolver) — these are an explicit author choice
- **Applies to subscriptions**: Relations embedded in subscription events (`existing`, `added`, `changed`) are scope-filtered **per subscriber** — the subscriber's user is captured at subscribe time, and on every push the target resource's `read` scope is resolved for that user and AND-ed into the included relation, with the same deny semantics as the read path. A subscriber can never receive related rows it could not read directly. Relations are loaded per subscriber rather than shared across them (cost scales with subscriber count; loads are deduplicated per subscriber within a single push)

### Internal Schema & Stores
- **Logical contract is stable**: `SessionData` (`id`/`userId`/`createdAt`/`expiresAt`/`data`) is always exposed in logical keys regardless of the underlying column names; remapping (`defineInternalSchema` `fieldMap`) applies only at the SQL persistence boundary — see [Internal tables](../auth/internal-tables.md)
- **Fail-fast validation**: `defineInternalSchema` validates that every required logical key resolves to a column on the supplied table at construction time, never at query time
- **Defaults are unchanged**: with no `internalSchema`, the built-in tables and the byte-for-byte original migration DDL are used; `createCovara({ internalSchema })` is for migration/introspection and never silently rewires a pre-built store
- **Migration safety**: generated DDL (`migrateInternal` mode c) covers single-primary-key tables only and throws for compound-PK tables (`auth_accounts`, `auth_verification_tokens`) rather than emitting an incorrect schema; `managedExternally: true` makes migration a no-op
- **KV session store is backend-agnostic**: `createKVSessionStore` works over any KV adapter; its hash field names are a private serialization, never user-facing, and are not remappable
- **Users/files are app-owned**: the framework never owns a users table (reached via `getUserById`) or a files table (supplied to `fileResource`); the changelog and rate limits are KV/memory-backed, not database tables

### Observability Storage
- **Defaults preserve behavior**: the audit log, request/error logs, and metrics are append-only logs backed by an in-memory ring buffer when no KV is configured — identical to before; with a global KV they persist automatically
- **`append` never throws**: a failing storage backend can never break the audited/served action; the in-memory mirror always records the entry even if a KV write fails
- **`setAdminAuditSink` is write-only**: it runs alongside the adapter and is for forwarding only; durable read/query/export requires an `ObservabilityLogAdapter`
- **Cross-process reads**: in KV mode synchronous reads reflect only the local process mirror; authoritative cross-instance reads use the async `query()`/`export()` path

### Admin Scope Bypass (Admin UI)
- **Identity re-verification, no secret**: The resource layer skips per-resource auth scopes only when the request carries the `x-covara-admin-bypass` marker **and** its authenticated user (or forwarded admin `apiKey`) passes the registered admin predicate. The marker is not a secret and grants nothing on its own
- **Leaked marker is inert**: A non-admin presenting the marker is served under normal scope enforcement (fail-closed); the marker value is constant and confers no authority
- **Disabled by default**: Bypass is inert unless an admin predicate is registered, which happens only when the [admin UI](../tooling/admin-ui.md) is mounted via `createCovara`; standalone `useResource` never bypasses
- **Gated on admin auth**: The admin predicate is derived from the UI's `security` config — locking down the UI's auth locks down bypass
- **Audited**: Every bypassed API-explorer request is recorded in the admin audit log (`api_explorer_execute`)

### Admin Impersonation (Admin UI)
- **Runs as the target, under their scope**: A request carrying the `x-covara-impersonate: <userId>` marker resolves the impersonated user's per-operation scope and attributes writes to them — it does NOT grant `allScope()`
- **Identity re-verification, no secret**: The marker is honored only when the forwarded request's real authenticated user passes the admin predicate (same test as bypass) and a `userManager`-backed resolver yields the target user; a forged/leaked marker from a non-admin is inert
- **Replaces bypass, never stacks**: When impersonation is active the scope layer uses the impersonated user's scope and skips the bypass branch entirely — impersonating an admin yields only that admin's scope, never full bypass (no escalation)
- **Single effective-user swap**: A middleware swaps `c.get("user")` to the impersonated user once, so scope, write attribution, and hooks all observe the same identity; admin-UI routes (`/__covara/*`) are exempt so admin authorization is unaffected
- **Audited with both ids**: Every impersonated action records the real admin id and the impersonated user id (`impersonate_execute`, `data_explorer_list`)

## Non-Guarantees

### Token Lifetime (What We Don't Promise)
- ❌ **Minimum lifetime**: Tokens may be revoked at any time
- ❌ **Refresh success**: Refresh tokens may be revoked or expired
- ❌ **Grace period**: No grace period after token expiration

### Availability (What We Don't Promise)
- ❌ **JWKS availability**: JWKS endpoint may be temporarily unavailable
- ❌ **Session persistence**: Sessions may be cleared (e.g., server restart with memory store)

## Threat Model

### In Scope (Protected Against)
- Token forgery
- Token replay (with nonce)
- Session fixation
- CSRF (with state parameter)
- Algorithm confusion attacks
- JWT injection via `none` algorithm
- Mass assignment (via enforced `fields.writable`)
- Open redirect via `redirect_uri` (component-wise validation)
- PKCE downgrade (plain rejected, required for public clients)
- Federated id_token forgery (signature + nonce + sub cross-check)
- Stored-XSS via login_hint (HTML-escaped)

### Out of Scope (Not Protected Against)
- Compromised signing keys (operational security)
- Client-side token theft (XSS)
- Phishing attacks
- Brute force (rate limiting helps but doesn't eliminate)
- Side-channel attacks

## Rate Limiting

### Auth Endpoints
- Login: 5 attempts per 15 minutes per IP
- Token refresh: 10 per minute per user
- Password reset: 3 per hour per email

### Rate Limit Bypass Protection
- Header normalization (case-insensitive)
- IP normalization (IPv4/IPv6)
- X-Forwarded-For only from trusted proxies

## Failure Modes

### Invalid Token
- Returns 401 Unauthorized
- Clear error message (without leaking info)
- No retry (client must re-authenticate)

### JWKS Unavailable
- Use cached keys if available
- Return 503 if no cached keys
- Automatic retry with backoff

### Session Expired
- Returns 401 Unauthorized
- Client should redirect to login
- Refresh token may still be valid

## Test Coverage

- `tests/invariants/auth-hardening.test.ts` - Security edge cases
- `tests/auth.test.ts` - Basic authentication
- `tests/auth-routes.test.ts` - Auth endpoints
- `tests/oidc/provider.test.ts` - OIDC provider

---

## Billing Contracts


Scope: `src/billing/` — the `BillingAdapter` interface, the Stripe / Lemon
Squeezy / Paddle / Polar adapters, the `createBilling` facade, the credits
ledger, the webhook handling, and the server router.

## Guarantees

- **Unified interface.** All four providers implement the same `BillingAdapter`
  and return normalized models (`BillingCustomer`, `BillingSubscription` with a
  canonical `SubscriptionStatus`, `CheckoutSession`, `BillingEvent`).
- **Webhook signature verification.** When a `webhookSecret` is configured,
  `handleWebhook` rejects any payload whose signature does not verify, using the
  provider's scheme (Stripe `t.payload` HMAC, Lemon Squeezy body HMAC, Paddle
  `ts:payload` HMAC, Polar Standard-Webhooks), with constant-time comparison and
  timestamp-skew rejection where the scheme includes a timestamp.
- **Idempotent webhook processing.** Deliveries are de-duplicated by event id via
  the KV (24h window); a retried delivery is parsed and returned but its side
  effects (credit grant, `onEvent`) run at most once.
- **At-least-once credit granting tied to payment.** On `payment.succeeded`, the
  matched plan's `credits` are granted to the resolved account exactly once per
  event id (subject to the dedupe window). Granting requires a configured KV.
- **Credits-ledger atomicity.** `grant`/`consume` mutate the balance with the
  KV's atomic `incrBy`, so concurrent operations across instances stay
  consistent. `consume` refuses to overdraw unless `allowNegative` is set.
- **404 → null.** `getCustomer`/`getSubscription` return `null` for not-found
  rather than throwing; other non-OK responses throw `BillingError` with status.

## Non-guarantees

- **No provider-API drift protection.** Adapters target the providers' current
  REST APIs; a breaking provider change requires an adapter update.
- **Capability gaps are explicit, not emulated.** Where a provider lacks a
  portable capability (e.g. Paddle `reportUsage` / hosted portal), the adapter
  throws a clear `BillingError` or omits the optional method rather than faking it.
- **Dedupe/credit-grant require a global KV.** Without a KV, webhooks are still
  verified and parsed, but dedupe and auto-grant are skipped.
- **No reconciliation/polling.** State is event-driven; if a webhook is never
  delivered, Covara does not poll the provider to reconcile (handle critical
  flows in `onEvent` and consider a periodic reconcile task).
- **Account resolution is best-effort.** Auto-grant resolves the account from
  `metadata.accountId`/`userId` (set this at checkout) or the customer id; if
  neither is present, no credits are granted.

---

## Email Contracts


Scope: `src/email/` — the `EmailAdapter` interface, the Resend and Cloudflare
Email Service adapters, and the template builder.

## Guarantees

- **Adapter uniformity.** Every adapter implements the same `EmailAdapter`
  (`send`, optional `sendBatch`) and accepts the same `EmailMessage`. Address
  inputs (`string`, `{ email, name }`, or arrays) normalize identically via the
  shared helpers.
- **Builder output is escaped.** All caller-supplied content passed to the
  template builder is HTML-escaped before rendering; the only unescaped path is
  the explicit `.raw(html, text)` block, which is the caller's responsibility.
- **Builder produces both representations.** `.build()` always returns both
  `html` and a plaintext `text` fallback.
- **Workers-safe.** Resend uses `fetch`; the Cloudflare adapter uses the Email
  Service binding via structural types (no `@cloudflare/workers-types` import).
- **Errors are explicit.** A non-2xx provider response (Resend) or a rejected
  binding send (Cloudflare) throws an error naming the provider and status; it is
  never silently swallowed.

## Non-guarantees

- **No delivery guarantee / no built-in retry or queue.** `send` resolves when
  the provider accepts the request; downstream delivery is the provider's
  concern. For at-least-once delivery, send from a background task (retries +
  DLQ) rather than inline.
- **No idempotency.** Calling `send` twice sends twice. De-duplicate upstream if
  needed (e.g. an idempotency key on the triggering mutation).
- **No template storage/versioning.** The builder renders at call time; it does
  not persist or version templates.
- **Provider feature parity is not normalized** beyond the common `EmailMessage`
  fields (e.g. scheduling, provider-specific analytics are not abstracted).

---

## Environment Variables Contracts


## Guarantees

### Parsing
- **Validation at startup**: All environment variables are validated when `createEnv` is called
- **Fail-fast behavior**: Invalid or missing required variables throw immediately with clear error messages
- **Zod integration**: Full Zod schema support including transforms, defaults, enums, and coercion
- **Key path joining**: Nested schema keys are joined with underscores (e.g., `SERVER.PORT` reads `SERVER_PORT`)

### Public/Private Separation
- **Private by default**: Variables without `PUBLIC_` prefix or `{ public: true }` are never exposed
- **PUBLIC_ prefix detection**: Top-level variables starting with `PUBLIC_` are automatically public
- **Explicit override**: `envVariable(val, schema, { public: false })` prevents exposure even with `PUBLIC_` prefix
- **No server secrets in client**: `getPublicEnvironmentVariables()` and HTTP endpoints never return private variables

### HTTP Endpoint
- **Consistent responses**: `GET /` returns the same JSON for a given server deployment
- **ETag support**: Response includes ETag header; `If-None-Match` returns 304 when unchanged
- **Cache-Control header**: Default `public, max-age=3600` (configurable)
- **Schema endpoint**: `GET /schema` returns field paths and inferred types

### ETag Behavior
- **Computed once**: ETag is computed at router creation from hash of public env values
- **304 response**: Matching `If-None-Match` returns 304 Not Modified with empty body
- **Cache invalidation**: ETag changes when server restarts with different values
- **Deterministic**: Same values always produce the same ETag

## Non-Guarantees

### Parsing (What We Don't Promise)
- ❌ **Import-time validation**: Variables are only validated when `createEnv` is called
- ❌ **Partial success**: If any variable fails, the entire `createEnv` call fails
- ❌ **Live reload**: Changes to `process.env` after `createEnv` are not reflected

### Schema Endpoint (What We Don't Promise)
- ❌ **Zod schema introspection**: Types are inferred from runtime values, not Zod schemas
- ❌ **Transform accuracy**: Complex transforms may not reflect the final type accurately
- ❌ **Union types**: Union types are represented as the runtime type

### Client (What We Don't Promise)
- ❌ **Automatic refresh**: Client must explicitly refetch or use polling
- ❌ **Offline support**: Fetching requires network connectivity
- ❌ **Type validation**: Client trusts the JSON matches the expected type

## Failure Modes

### Missing Required Variable
- Application fails to start with error: `Environment variable validation error for KEY: Required`
- Clear error message identifies the missing variable

### Invalid Variable Value
- Application fails to start with Zod validation error
- Error message indicates the validation failure and expected type

### Schema Endpoint Disabled
- `GET /schema` returns 404
- Typegen skips env types (no error, just omitted)

### Client Fetch Error
- Network errors propagate as exceptions
- React hook sets `error` state; `env` remains `null`

## Test Coverage

- `tests/env/env.test.ts` - Server-side parsing, public/private separation, ETag
- `tests/env/client-env.test.ts` - Client fetching, schema endpoint, type generation

---

## ETag / Optimistic Concurrency Contracts


These guarantees apply to resources configured with `etag` in `useResource(table, { etag: {...} })`. Without the config, no ETag headers are emitted and conditional headers are ignored.

## Guarantees

### ETag Emission
- **Mutating and single-item responses carry ETags**: `POST /`, `GET /:id`, `PATCH /:id`, and `PUT /:id` responses include an `ETag` header reflecting the returned representation
- **Tag derivation precedence**: `versionField` (if set and present on the item) → `updatedAtField` + `idField` (timestamp-id pair) → MD5 hash of the serialized item
- **Weak by default**: Tags are weak (`W/"..."`) unless `algorithm: "strong"` is configured
- **Deterministic**: The same item state always produces the same ETag

### Conditional Writes (If-Match)
- **Enforcement on mutation**: `If-Match` is checked against the *current* stored item on `PATCH /:id`, `PUT /:id`, and `DELETE /:id` before the mutation executes
- **412 on mismatch**: A non-matching `If-Match` fails with `412 Precondition Failed` (`PRECONDITION_FAILED`, RFC 7807 body including `currentETag` in details) and the mutation is not applied
- **Compare-and-swap**: When `If-Match` is present, the `PATCH`/`PUT`/`DELETE` statement carries a CAS predicate on the version/updated-at field, so the validated version must still match at write time. If a concurrent writer changed the row between the read and the write, zero rows match and the request fails with `412` instead of silently losing the update — exactly one of N concurrent `If-Match` writers wins, the rest get `412`
- **Wildcard**: `If-Match: *` matches any current state (the write proceeds if the item exists)
- **Multiple tags**: `If-Match` may contain a comma-separated list; the check passes if any tag matches
- **Strong comparison (RFC 7232 §3.1)**: `If-Match` uses the strong comparison function
- **No header, no check**: Requests without `If-Match` are unconditional (last write wins, no CAS predicate)

### Conditional Reads (If-None-Match)
- **304 on match**: `GET /:id` with a matching `If-None-Match` returns `304 Not Modified` with an empty body and the current `ETag` header
- **Fresh data otherwise**: A non-matching tag returns `200` with the full representation and current `ETag`

### Version Auto-Increment (Optimistic Locking)
- **Increment on every update**: When `versionField` is configured, the field is incremented by 1 on every `PATCH /:id` and `PUT /:id`, starting from the current stored value (missing/non-numeric values are left untouched)
- **Client override**: If the request body explicitly sets the version field, that value is used instead of auto-increment
- **Lost-update protection**: Two clients that read version N and both write with `If-Match` — the CAS predicate guarantees exactly one write lands; the other matches zero rows and receives 412 and must refetch

## Non-Guarantees

- ❌ **List ETags**: `GET /` (list) responses do not carry per-item ETags
- ❌ **Batch conditional writes**: `If-Match` is not enforced on `/batch` operations, and batch updates do not auto-increment the version field
- ❌ **CAS without a comparison field**: The compare-and-swap predicate requires a `versionField` or `updatedAtField`. With neither configured (hash-only ETags), the If-Match check is still enforced before the write but is not atomic with it, so an interleaving writer could theoretically slip between check and write
- ❌ **Hash stability across versions**: The fallback (hash-based) tag format may change between minor versions; treat ETags as opaque
- ❌ **Strong validator semantics**: Weak tags (default) do not guarantee byte-for-byte identity of representations

## Failure Modes

### If-Match Mismatch
- Returns `412` with problem details: `code: "PRECONDITION_FAILED"`, `details.currentETag` set to the item's current tag, and a suggestion to refetch
- The stored item is unchanged

### Malformed ETag in Header
- Tags that are not `"value"` or `W/"value"` never match → conditional writes fail with 412, conditional reads return 200

### Item Not Found
- Conditional requests against a missing id return `404` (the conditional check is not reached)

## Test Coverage

- `tests/concurrency/etag-race.test.ts` - ETag emission, If-Match enforcement, `*` wildcard, concurrent optimistic locking, delete

---

## Server-Rendered htmx Pages Conctracts


> **Beta.** The htmx page layer is newer than the rest of Covara; these invariants may evolve while it stabilizes.

Invariants for `app.page(...)` and the `covara/htmx` layer. See [Overview](../htmx/overview.md) and [Building pages](../htmx/pages.md) for usage.

## Region identity

- A page registered at `path` with regions in source order assigns each region a deterministic id: `regionId = slug(path) + "-" + index`, where `slug` lowercases and replaces non-alphanumerics with `-` (`/` → `root`).
- `regionId` is stable across requests and deploys **as long as region order is unchanged**. Reordering regions changes ids; an in-flight client reconnect then refetches rather than mis-targets.

## DOM ids

- Container: `cv-<regionId>-list`. Row: `cv-<regionId>-<domSafeId(id)>`. Template: `cv-<regionId>-tmpl`.
- `domSafeId` preserves `[A-Za-z0-9_-]` and hex-escapes other characters, collision-free.

## Generated endpoints (under `/__covara/live`)

- `GET /__covara/live/<regionId>` — list/pagination fragment (rows only, no shell). Honors `?cursor=`.
- `POST /__covara/live/<regionId>` — create; on success returns the rendered row (HTTP 201).
- `PATCH /__covara/live/<regionId>/<id>` — update; returns the rendered row, **or an empty body** when the updated row no longer matches the region's display filter (so an `outerHTML` swap removes it).
- `DELETE /__covara/live/<regionId>/<id>` — delete; returns an empty body.
- `GET /__covara/live/<regionId>/subscribe` — SSE stream.
- `GET /__covara/live/_runtime.js` — the client bundle (htmx core + Covara runtime).
- Aggregate regions reject create/update/delete (404) and their list endpoint returns the aggregate fragment.

All generated endpoints run through the resource engine, inheriting its scope/validation/etag/masking. Auth is forwarded from the inbound request (cookie/authorization) on the in-process dispatch.

## SSE wire format

The live stream reuses the resource's own `/subscribe` endpoint with a one-shot HTML renderer injected via the internal `__cvRenderer` token; the resource's scope/resume/heartbeat/backpressure logic is unchanged. Named events:

| Event | `data` | Client action |
| --- | --- | --- |
| `added`, `changed` | rendered row HTML | upsert by row id |
| `removed` | the row's DOM id | remove that element |
| `aggregate`-region change | `invalidate` (no payload) | refetch the aggregate fragment |
| `invalidate` | optional reason | refetch the list |

The JSON wire format of `/subscribe` is unchanged when no `__cvRenderer` token is present (the per-handler renderer defaults to JSON).

## Optimistic / offline

- **Create is inserted once, by the region's live SSE `added` event.** The create form posts with `hx-swap="none"` (its HTML response is not swapped in), so the new row is never inserted twice — it appears via the same SSE path in every connected client, including the acting one. No optimistic placeholder is used for create (an earlier placeholder caused a duplicate/phantom row).
- **Delete** is optimistic: the row is hidden immediately and restored if the request fails; on success it is removed by the response swap / SSE `removed` event.
- Per-request optimistic state is correlated across the `htmx:beforeRequest`/`htmx:afterRequest` events via the shared `xhr` (their `event.detail` objects are NOT shared).
- The SSE `added`/`changed` handlers upsert by row id, so a row already present is replaced rather than duplicated.
- Each page also ships a `<template id="cv-<regionId>-tmpl">` whose contents are the row markup with `{{field}}` slots (derived by rendering the row closure against a field-recording proxy; the sentinel uses only `[A-Za-z0-9_]` so it survives HTML text, `domSafeId`, and URL-encoding, normalized to `{{field}}`) — available for custom client rendering.
- Offline create mutations are queued in `localStorage` (`cv-offline-queue`) and replayed on `online`, after which affected regions resync.

## Rendering rules

- Page shells render synchronously; data fetching is per-region. Async page shells throw.
- Page components must be pure functions of their context (re-run to resolve regions for the generated endpoints).
- `query.filter` is a display refinement, not a security boundary; row-level access is enforced by the resource's `auth` scope.

---

## Offline Sync Contracts


## Guarantees

### Optimistic Updates
- **Immediate UI update**: Mutations are applied to local state immediately
- **Optimistic ID generation**: Created items get client-generated IDs until server confirms
- **ID remapping**: When server assigns real ID, all local references are updated

### Mutation Queue
- **Persistence**: Queued mutations survive page refresh (with persistent storage)
- **Ordering**: Mutations are synced in queue order (FIFO)
- **Deduplication**: Duplicate mutations (same idempotency key) are merged

### Sync Behavior
- **Automatic sync**: Mutations sync automatically when online
- **Retry with backoff**: Failed syncs retry with exponential backoff
- **Conflict detection**: Server conflicts are detected and reported

### ID Remapping
- **Recursive remapping**: All references to optimistic IDs in mutation data are remapped
- **Cross-resource support**: Foreign key references to optimistic IDs are remapped
- **Notification**: `onIdRemapped` callback fired when mapping established

### Reconnection
- **Pending state preservation**: Pending deletes/updates survive reconnection
- **No ghost items**: Deleted items don't reappear on reconnection
- **Pending updates applied**: Local updates applied to server state on reconnect

## Non-Guarantees

### Ordering (What We Don't Promise)
- ❌ **Server-side ordering**: Server may process mutations in different order than sent
- ❌ **Cross-client ordering**: Mutations from different clients are not globally ordered

### Consistency (What We Don't Promise)
- ❌ **Strong consistency**: Eventual consistency between client and server
- ❌ **Conflict resolution**: Automatic conflict resolution only with configured strategy

### Durability (What We Don't Promise)
- ❌ **Guaranteed persistence**: In-memory storage loses data on refresh
- ❌ **Unlimited queue**: Queue has max size; oldest mutations may be dropped

## Conflict Resolution Strategies

### Server Wins (Default)
- Conflict detected → discard client mutation
- Server state is authoritative
- Simple but may lose client work

### Client Wins
- Conflict detected → retry with client data
- May overwrite concurrent server changes
- Use for last-write-wins semantics

### Merge (Field-Level)
- Conflict detected → field-level three-way merge, then retry as update
- Server wins **only** on fields that BOTH the client and server changed
- Client edits to fields the server did not touch are preserved
- Requires `ConflictError.serverState`; when `ConflictError.baseState` is present
  it is used to detect which fields each side actually changed (otherwise every
  field in the mutation data is treated as a client change)
- Only applies to `update` mutations; `create`/`delete` conflicts fall back to discard

### Manual Resolution
- Conflict detected → call `onConflict` handler
- Application decides resolution
- Most flexible but requires implementation

## Multi-Tab Coherence (opt-in: `offline.tabSync`)
- Coordinated across browser tabs via `BroadcastChannel` (feature-detected;
  a no-op in React Native / Node where `BroadcastChannel` is unavailable)
- **Single flusher**: only the elected leader tab flushes the shared mutation
  queue, so a mutation is not sent once per open tab. Leadership uses a
  `localStorage` lock with a heartbeat/TTL; if `localStorage` is unavailable
  every tab acts independently (best effort)
- **Mirrored state**: id-remaps and invalidations broadcast to other tabs;
  receiving tabs apply the id mapping and refetch matching live queries
- After a leader finishes flushing it broadcasts `sync-complete`; followers
  refresh their live queries to catch up

## Durable Storage Backends
- `InMemoryOfflineStorage` — non-durable (default when no DOM APIs)
- `LocalStorageOfflineStorage` — browser, small queues
- `IndexedDBOfflineStorage` — browser, larger queues (feature-detected)
- `createOfflineStorage()` picks the best available backend (IndexedDB →
  LocalStorage → in-memory)

## Failure Modes

### Network Failure During Sync
- Mutation stays in queue (status: failed)
- Retried on next sync attempt
- After max retries, mutation marked permanently failed

### Optimistic ID Never Confirmed
- Optimistic item remains in local state
- Referenced mutations may fail due to invalid ID
- `onMutationFailed` callback fired

### Conflict on Create
- Server rejects create (e.g., unique constraint)
- Client notified via `onConflict` or `onMutationFailed`
- Optimistic item remains until resolution

### Subscription Reconnect with Pending Mutations
- Server sends `existing` events with server IDs
- Client checks `pendingDeletes` and `pendingUpdates`
- Pending state is preserved until server confirmation

## Best Practices

### Idempotency Keys
- Always include idempotency keys for create/update operations
- Use deterministic keys (e.g., `${resource}-${optimisticId}-${timestamp}`)
- Keys are used for deduplication and replay safety

### Optimistic IDs
- Use recognizable prefix (e.g., `optimistic_`)
- Include timestamp and random component
- Never rely on optimistic IDs for persistence

### Conflict Handling
- Implement `onConflict` handler for important operations
- Log conflicts for debugging
- Consider user notification for manual resolution

## Test Coverage

- `tests/sync/offline-sync-edge-cases.test.ts` - Comprehensive sync scenarios
- `tests/client/offline.test.ts` - Basic offline functionality
- `tests/client/offline-advanced.test.ts` - Merge strategy, IndexedDB backend, multi-tab sync
- `tests/client/live-store.test.ts` - LiveQuery + offline integration

---

## Covara Contracts


This folder contains the formal contracts (guarantees and non-guarantees) for the Covara framework. These contracts are:

1. **Testable** - Each guarantee has corresponding tests that enforce it
2. **Versioned** - Breaking changes to contracts require major version bumps
3. **Explicit** - We document what we DON'T promise as clearly as what we DO

## Documents

- [subscriptions.md](./subscriptions.md) - Subscription ordering, resume, and delivery guarantees
- [tasks.md](./tasks.md) - Task execution semantics, retry, and delivery guarantees
- [pagination.md](./pagination.md) - Cursor integrity and consistency guarantees
- [auth.md](./auth.md) - Authentication and authorization threat model
- [billing.md](./billing.md) - Billing and metering guarantees
- [email.md](./email.md) - Email delivery and formatting guarantees
- [etag.md](./etag.md) - ETag emission, conditional requests, and optimistic locking guarantees
- [offline-sync.md](./offline-sync.md) - Offline mutation and sync guarantees
- [environment-variables.md](./environment-variables.md) - Environment variable parsing and public exposure guarantees
- [search.md](./search.md) - Search endpoint and auto-indexing guarantees
- [storage.md](./storage.md) - File upload and storage adapter guarantees
- [track-mutations.md](./track-mutations.md) - Mutation tracking and changelog recording guarantees

## How to Read These Contracts

Each contract document has the following structure:

### Guarantees (What We Promise)
Behaviors you can rely on. We test these. Breaking them is a bug.

### Non-Guarantees (What We Explicitly Do Not Promise)
Behaviors that might work today but could change. Don't depend on these.

### Failure Modes
What happens when things go wrong. We aim for fail-safe behavior.

### Test Coverage
Links to tests that verify these contracts.

---

## Pagination Contracts


## Guarantees

### Cursor Integrity
- **Structural validation (always)**: malformed cursors, a version mismatch, or a cursor replayed under a different `orderBy` are rejected with a clear `400` (`CURSOR_INVALID`). Optional `cursorMaxAgeMs` rejects stale cursors.
- **Signature verification (when a secret is configured)**: with a `cursorSigningSecret` (per-resource or global via `setGlobalCursorSigningSecret`), each cursor is suffixed with `.<hmac-sha256(payload, secret)>` and the signature is verified on decode (constant-time). A forged or altered payload — or one signed with a different secret, or unsigned — is rejected as `reason: "tampered"`. A resource secret overrides the global; an explicit `null` opts a resource out; unset inherits the global.
- **Not a security boundary either way**: a cursor encodes only a keyset position and its values are bound as parameterized SQL; every query still applies the resource's auth scope + filter, so even an unsigned/forged cursor cannot widen access or inject SQL. Signing adds integrity/anti-forgery on top.
- **Encoding stability**: Cursor format is stable within major version
- **Opaque to client**: Cursors are treated as opaque strings; clients should not parse them

### Result Set Properties
- **No duplicates**: Paginating through a static dataset returns each item exactly once
- **No gaps**: Paginating through a static dataset returns all items
- **Stable ordering**: Items are returned in consistent order based on `orderBy` fields

### Ordering
- **Multi-field support**: Can order by multiple fields (e.g., `orderBy=score:desc,id`)
- **Tie-breaking**: Always includes unique field (usually `id`) for deterministic ordering
- **Null handling**: Null values sort last (configurable)

### Limits
- **Server-enforced max**: Requests cannot exceed server's max page size
- **Default applied**: If no limit specified, server applies default

## Non-Guarantees

### Consistency (What We Don't Promise)
- ❌ **Snapshot isolation**: Dataset may change between page fetches
- ❌ **Repeatable reads**: Same cursor may return different results after mutations
- ❌ **Insert visibility**: New items may appear in "already fetched" pages

### Behavior Under Mutation (What We Don't Promise)
- ❌ **Insert ordering**: Items inserted between fetches may appear in unexpected positions
- ❌ **Delete handling**: Deleted items may cause apparent "skips"
- ❌ **Update consistency**: Updated items may move between pages

### Performance (What We Don't Promise)
- ❌ **Constant time**: Pagination performance may vary with dataset size
- ❌ **Cursor validity duration**: Cursors may become invalid after extended periods

## Cursor Behavior Under Mutations

### Item Inserted
- If inserted BEFORE cursor position: May cause duplicate in next page
- If inserted AFTER cursor position: Will appear normally
- If inserted AT cursor position: Behavior depends on tie-breaking

### Item Deleted
- If deleted item was cursor: Next fetch continues from next item
- If deleted BEFORE cursor: May cause item to be skipped
- If deleted AFTER cursor: No effect on pagination

### Item Updated (Affecting Sort Order)
- Item may move to different page
- May cause apparent duplicate or skip
- This is expected behavior, not a bug

## Mitigation Strategies

For applications requiring consistency:
1. **Timestamp filtering**: Add `createdAt < snapshot_time` filter
2. **Optimistic locking**: Use ETags to detect concurrent modifications (see [etag.md](./etag.md))
3. **Sequence numbers**: Track changelog sequence for consistent views

## Test Coverage

- `tests/invariants/pagination-invariants.test.ts` - Core invariants
- `tests/pagination.test.ts` - Basic functionality
- `tests/smoke/pagination-cursor-hardening.test.ts` - Edge cases

---

## Search Contracts


## Guarantees

### Search Endpoint
- **Automatic availability**: `/search` endpoint is available on all resources when a global search adapter is configured
- **Zero-config default**: All fields are searchable by default without explicit configuration
- **Query required**: Search endpoint requires a `q` parameter and returns 400 if missing
- **Graceful degradation**: Returns 404 if no search adapter configured (search simply isn't available; not an error in production)

### Auto-Indexing
- **Create → index**: New documents are indexed immediately after successful database insert
- **Update → re-index**: Modified documents are re-indexed after successful database update
- **Delete → remove**: Documents are removed from index after successful database delete
- **Index errors don't fail mutations**: If indexing fails, the database mutation still succeeds (logged as error)

### Transactional Outbox (opt-in via `search.outbox: true`)
- **At-least-once convergence**: When the outbox is enabled, every index/delete op is persisted to a durable KV queue at mutation time and retried until it succeeds or is parked, guaranteeing the index eventually converges with the database (no silent drops on transient backend failure)
- **Exponential backoff**: Failed ops are retried with `base * 2^attempts` backoff, capped at 5 minutes (default base 1s)
- **Dead set**: Ops that exceed `maxAttempts` (default 10) are moved to a dead set and logged, never silently discarded; inspect via `getSearchOutboxStats()`
- **Requires a global KV**: With no global KV registered, enabling `outbox` is a no-op
- **Drainer**: On Node a background `setInterval` drains the queue automatically; on Workers the application must call `drainSearchOutbox()` from a scheduled/queue handler (no long-lived process)

### Field Configuration
- **Array fields**: When `fields` is an array, only those fields are searched
- **Weight support**: Field weights are passed to the search adapter for boosting
- **Searchable flag**: `searchable: false` excludes a field from search queries

### Filter Integration
- **Post-filter**: RSQL filters are applied after search results are returned
- **Full operator support**: All standard RSQL operators work with search results

## Non-Guarantees

### Search Behavior (What We Don't Promise)
- ❌ **Exact matching**: Search is fuzzy by default; exact match not guaranteed
- ❌ **Consistent scoring**: Search scores may vary between adapter implementations
- ❌ **Instant indexing**: Index updates may have slight delay (OpenSearch refresh)
- ❌ **Offline search**: Memory adapter data is lost on restart

### Data Consistency (What We Don't Promise)
- ❌ **Index-database sync**: Index may briefly be out of sync with database. With `search.outbox` enabled, the index converges at-least-once; without it, a failed inline index op is dropped (one immediate retry) and the index can stay stale until the row is touched again
- ❌ **Transactional indexing**: Index updates are not part of the database transaction even with the outbox — the outbox provides eventual at-least-once convergence, not atomic index+DB commits
- ❌ **Automatic reindexing**: Existing data is not automatically indexed on startup

### Performance (What We Don't Promise)
- ❌ **Bounded latency**: Search latency depends on adapter and index size
- ❌ **Unlimited results**: Results are capped at 100 per request

## Failure Modes

### No Search Adapter
- Endpoint returns 404 Not Found (search not available)
- Auto-indexing does nothing (silent)
- Resource CRUD operations work normally

### Index Error
- Index/delete errors are logged but don't fail mutations
- Search continues to work with potentially stale data
- No automatic retry of failed index operations

### Search Error
- Endpoint returns 500 with `SearchError` (RFC 7807 Problem Details format)
- Includes `index` name and `originalError` message in details
- RSQL filter errors return 400 with `ValidationError`

### Missing Query Parameter
- Endpoint returns 400 with `ValidationError`
- Message: "Missing query parameter 'q'"

## Test Coverage

- `tests/search/adapter.test.ts` - Global adapter registration
- `tests/search/memory-adapter.test.ts` - Memory adapter behavior
- `tests/search/endpoint.test.ts` - Search endpoint functionality
- `tests/search/auto-index.test.ts` - Auto-indexing hooks

---

## Storage (File Upload) Contracts


## Guarantees

### Storage Adapters
- **Adapter interface consistency**: All adapters implement the same `StorageAdapter` interface
- **Global singleton**: Only one storage adapter can be active at a time via `setGlobalStorage()`
- **Upload atomicity**: Uploads either fully succeed or fail; no partial files left behind
- **Stream support**: All adapters support both `Buffer` and `Readable` stream inputs

### Local Storage Adapter
- **Directory creation**: Nested directories are created automatically when `createDirectories: true`
- **Metadata persistence**: File metadata stored in sidecar `.meta.json` files
- **URL generation**: Returns URLs when `baseUrl` is configured; null otherwise
- **CreatedAt preservation**: Updating a file preserves its original `createdAt` timestamp

### S3 Storage Adapter
- **Presigned URL support**: Always returns presigned URLs for upload/download operations
- **AWS SDK compatibility**: Works with any S3-compatible service (MinIO, DigitalOcean Spaces, etc.)
- **Lazy initialization**: AWS SDK is loaded only when first operation is performed
- **Configurable expiry**: Presigned URL expiration is configurable via `presignedUrlExpiry`

### R2 Storage Adapter
- **Two modes**: Bindings mode (Workers R2 binding) or S3 mode (account credentials); `binding` presence selects the mode
- **S3-mode presigned URLs**: S3 mode supports presigned upload/download; bindings mode streams through the Worker
- **Workers-friendly**: The recommended object store on Cloudflare Workers, where local filesystem storage is unavailable

### Memory Storage Adapter
- **In-memory only**: Data is not persisted between restarts
- **No presigned URLs**: Returns null for presigned URL methods
- **Complete isolation**: Each instance has its own isolated storage

### File Resource
- **Superset of a regular resource**: A file resource is a `useResource` resource (full CRUD, list pagination, subscriptions, procedures, relations, field policies, full auth scopes) plus the upload/`upload-url`/`confirm`/`download` routes; responses use the standard resource shapes (no `{ data }` envelope)
- **Multipart parsing**: Accepts multipart/form-data uploads with a single `file` field
- **MIME type validation**: Rejects files with disallowed MIME types (400 error)
- **Size validation**: Rejects files exceeding `maxFileSize` (400 error)
- **Validation option**: The `validation` option (`maxSize`/`allowedTypes`/`blockedTypes`) is enforced on both direct uploads and presigned-URL requests, before any bytes are persisted
- **Upload is a tracked create**: A successful upload runs `onBeforeCreate`/`onAfterCreate` hooks and pushes an `added` subscription event, like any resource create
- **Orphan cleanup on delete**: deleting a record removes the stored blob via an internal `onAfterDelete` hook (composed with the user's), so no orphaned objects remain; `DELETE /batch` removes blobs then rows
- **Auth scope enforcement**: All operations respect configured auth scopes
- **Database + storage consistency**: Files are only created in database after successful storage upload

### Presigned Upload Flow (S3)
- **Pending status**: Files created with `status: "pending"` until confirmed
- **Confirmation required**: `/confirm` endpoint must be called after direct S3 upload
- **Metadata sync**: Confirmation fetches actual size and MIME type from S3

## Non-Guarantees

### Storage Behavior (What We Don't Promise)
- ❌ **Cross-adapter compatibility**: Files stored with one adapter cannot be accessed by another
- ❌ **Virus scanning**: No automatic malware detection on uploaded files
- ❌ **Image processing**: No automatic thumbnail generation or image optimization
- ❌ **Deduplication**: Same file uploaded twice creates two storage entries
- ❌ **Encryption at rest**: Depends on underlying storage configuration

### Data Consistency (What We Don't Promise)
- ❌ **Atomic delete**: Deleting a record removes the database row, then the stored blob (via `onAfterDelete`); a crash between steps can leave an orphaned blob
- ❌ **Transaction support**: Storage operations are not part of database transactions
- ❌ **Reference counting**: Deleting a file does not check for references from other resources

### Performance (What We Don't Promise)
- ❌ **Streaming downloads**: Download endpoint loads entire file into memory for local/memory adapters
- ❌ **Concurrent upload limits**: No built-in rate limiting for uploads
- ❌ **Resumable uploads**: Interrupted uploads must be restarted from scratch

## Failure Modes

### No Storage Configured
- `useFileResource()` throws during initialization: "Storage not configured"
- Must call `initializeStorage()` or `setGlobalStorage()` before creating file resource

### Upload Failures
- Network error during S3 upload returns 500 with original error
- Disk full on local storage returns 500 with filesystem error
- Invalid multipart request returns 400 with validation error

### Download Failures
- File not found in storage returns 404
- File exists in database but missing from storage returns 500
- S3 access denied returns 500 with permission error

### Delete Failures
- Delete from storage fails: file remains in database (inconsistent state)
- Delete from database fails: file removed from storage but remains in database

### Presigned URL Failures
- Adapter doesn't support presigned URLs: returns 400 (validation error)
- S3 credential error: returns 500 when generating presigned URL
- Expired presigned URL: S3 returns 403 directly to client

### MIME Type Validation
- Disallowed MIME type returns 400 with list of allowed types
- MIME type detection relies on client-provided Content-Type header

### Size Validation
- File too large returns 400 with configured max size in error message
- Size is checked after upload completes (not streaming validation)

## Test Coverage

- `tests/storage/memory.test.ts` - Memory adapter operations
- `tests/storage/local.test.ts` - Local filesystem adapter operations
- `tests/storage/s3.test.ts` - S3 adapter operations (mocked)

---

## Subscription Contracts


## Guarantees

### Event Delivery
- **Commit consistency**: Changelog entries and subscription events are emitted only *after* the database transaction commits. A mutation whose transaction rolls back (e.g. a throwing `onAfterUpdate`/`onAfterDelete` hook, or a failed commit) never produces a changelog entry or subscription event — there are no phantom events for uncommitted state. (On engines without interactive transactions — Cloudflare D1 — single-statement writes auto-commit before after-hooks run, so a throwing after-hook cannot roll the write back; see the [mutation-tracking contract](./track-mutations.md#engines-without-interactive-transactions-cloudflare-d1).)
- **Actor attribution**: Changelog entries carry the authenticated user's ID (`userId`) when the mutation came through a resource route or mutation pipeline with a user in context; anonymous/raw-SQL/external mutations leave it unset.
- **At-least-once delivery**: Every mutation that matches a subscription's filter will generate at least one event
- **Event exclusivity**: A single mutation generates exactly one of: `added`, `changed`, `removed`, or `invalidate` per subscription (never multiple conflicting events)
- **Filter scope transitions**:
  - Item entering filter scope → `added`
  - Item leaving filter scope → `removed`
  - Item staying in scope + modified → `changed`
  - Item never in scope → no event

### Ordering
- **Per-connection ordering**: Events on a single connection are delivered in sequence number order
- **Monotonic sequences**: Sequence numbers always increase within a connection
- **No duplicate sequences**: Each sequence number appears at most once per connection

### Resume Semantics
- **Gap detection**: If client resumes from sequence N but server's oldest is N+k, server sends `invalidate`
- **Catchup delivery**: If gap is within retention window, missed events are sent in order
- **Fresh start**: Resume from sequence 0 sends all matching items as `existing` events

### Scope Changes
- **Row-data scope changes (immediate)**: When a *mutation* moves a row out of a subscriber's scope — including scopes expressed against the row's own columns, e.g. `ownerOnly()` / `userId==<me>` — they receive `removed` immediately as part of normal mutation processing. A row entering scope yields `added`.
- **Out-of-band scope changes (periodic)**: Permission changes that are **not** driven by a row mutation (e.g. losing org membership, a revoked role) are caught by a periodic re-resolution of each subscription's scope. Every `sse.scopeRecheckMs` (default **30000ms**, per-resource, `0` disables) the subscription re-resolves its scope; if the resolved scope changed, the current matching set is recomputed and diffed against what the subscriber holds — rows that left scope emit `removed`, rows that entered emit `added`. The DB scan runs only when the resolved scope string actually changes; the new scope is also persisted so subsequent live events honor it (a revoked subscriber stops receiving live updates for rows it can no longer see).
  - **Detection limit**: the re-check reflects changes that the scope resolver itself recomputes (e.g. resolvers that query current membership/roles on each call). A resolver that only reads static fields off the user object captured at connect cannot observe an out-of-band change and still requires a reconnect.
  - **Session expiry** is handled separately: a subscription whose `authExpiresAt` has passed is torn down with an `invalidate`.

### Scalability
- **Per-resource isolation**: Subscriptions are stored sharded by resource (`covara:subs:byres:<resource>`, with a `covara:subs:resources` index for enumeration). A mutation loads and evaluates only the mutated resource's subscriptions — its cost scales with that resource's subscriber count, never the total subscription count across resources.
- **O(own subscriptions) disconnect**: SSE handlers are process-local, so each process tracks handler → subscription IDs in memory; a client disconnect removes exactly its own subscriptions without scanning the registry. (Cleanup of subscriptions left by a dead process falls back to a shard scan.)
- **Self-addressing IDs**: Subscription IDs embed their resource (`<uuid>:<resource>`), so ID-only operations (get/remove/seq-update) address the right shard with no secondary lookup. IDs remain opaque to clients.
- ❌ **Not promised**: Per-subscription *filter evaluation* within a resource is still O(subscribers-on-that-resource) per mutation — each subscription's filter/scope must be checked to decide delivery. This is in-memory predicate evaluation, not I/O.

### Aggregate Subscriptions (`GET /aggregate/subscribe`)
- **Recompute-on-change**: Unlike row subscriptions, aggregate subscriptions do not track individual rows. The server recomputes the full aggregate (honoring `groupBy`/`sum`/`avg`/`min`/`max`/`count`/`having` and the read scope + `filter`) whenever the resource is mutated, and emits an `aggregate` event with the new result.
- **Exactness**: Because the result is recomputed from the database, it is always exact for any grouping/having combination — no incremental-aggregation drift.
- **Initial snapshot**: On connect the server emits `connected` then one `aggregate` event with the current result (even when the resource is empty).
- **Scope-aware skip**: A subscription only recomputes when a mutated row could actually be in its scope. Each watcher carries the subscription's compiled read scope + `filter` and is handed the changed rows; if none match, the recompute is skipped entirely. This keeps a per-user aggregate (e.g. `userId==<me>`) from recomputing on every *other* user's insert, update, **or delete**. The changed rows passed are: the new row for inserts, new **and** previous state for updates (so scope entry/exit is caught), and the deleted rows' prior content for deletes. Unscoped/global aggregates (matcher `*`) always recompute.
- **Conservative fallback**: When the changed rows aren't available — raw-SQL/external invalidations (the framework doesn't know which rows changed) and cross-process notifications (row data is intentionally not shipped over pub/sub) — the watcher recomputes unconditionally. Skipping is only ever applied when it is provably safe; the result-level dedup below is the correctness backstop, so over-recomputing is always safe.
- **Debounced + deduplicated**: Bursts of mutations coalesce into a single recompute (`sse.aggregateDebounceMs`, default 150ms), and an `aggregate` event is suppressed when the recomputed result matches the last one sent under an **order-independent** comparison (group order is normalized, since `GROUP BY` has no stable `ORDER BY`).
- **Mutation coverage**: Inserts, updates, deletes, and raw-SQL/external invalidations all (potentially) trigger recompute. Cross-process mutations reach watchers via the `covara:aggregate` KV channel; double-delivery to the originating process is harmless (it collapses in the debounce).
- **Scope**: The read scope and `filter` are resolved once at connect and reused for every recompute for the life of the connection.

## Non-Guarantees

### Ordering (What We Don't Promise)
- ❌ **Global ordering**: Events across different subscriptions are NOT globally ordered
- ❌ **Cross-resource ordering**: Events for different resources are NOT ordered relative to each other
- ❌ **Real-time delivery**: Network delays may cause events to arrive later than expected

### Aggregate Subscriptions (What We Don't Promise)
- ❌ **Per-mutation events**: An `aggregate` event is not emitted per row change — only the recomputed result, after debounce, and only when it differs from the last sent payload.
- ❌ **Resume/catchup**: Aggregate subscriptions carry a `seq` for reference but do not support changelog catchup/`resumeFrom`; a reconnect simply re-emits the current snapshot.

### Delivery (What We Don't Promise)
- ❌ **Exactly-once delivery**: We guarantee at-least-once, not exactly-once
- ❌ **Bounded latency**: No SLA on event delivery time
- ❌ **Infinite retention**: Changelog has a max size; old events are pruned

### State (What We Don't Promise)
- ❌ **Snapshot consistency**: `existing` events represent a point-in-time snapshot; items may change during enumeration

## Failure Modes

### Network Disconnection
- Client receives `disconnected` callback
- On reconnect, client should resume from last sequence
- If gap too large, `invalidate` triggers full refetch

### Server Restart
- Active subscriptions are terminated
- Clients reconnect and resume normally
- Changelog persists across restarts (if configured)

### Changelog Overflow
- Oldest entries are pruned when max size reached
- Clients with stale sequences receive `invalidate`
- This is normal operation, not an error

### Slow Consumer / Backpressure
- Each connection has a bounded outbound queue (`sse.maxQueueBytes`, default 64 KB)
- When the queue is saturated the configured `sse.onBackpressure` policy applies:
  - `invalidate` (default): a single `invalidate` event is sent so the client refetches
  - `disconnect`: the connection is closed; the client reconnects and resumes from its last sequence
  - `drop`: the event is skipped for that connection (it may miss updates until the next sync)
- The server never buffers unboundedly for a stalled client

### Multi-Instance Delivery
- With a distributed KV store initialized via `initializeKV`, mutations on one instance are fanned out to subscribers on other instances (at-least-once)
- With the in-memory KV (per-process), cross-instance delivery is NOT provided

### External Writers (mutations outside the tracked db)
- Mutations made outside `useResource`/the tracked db (cron jobs, other services, manual edits) are NOT observed automatically
- Writers MUST call `recordExternalMutation(resource, type, { objectId? })` to notify subscribers; this emits an `invalidate` event (never `added`/`changed`/`removed`) so clients refetch
- This is the portable alternative to database-specific CDC; see the [mutation-tracking contract](./track-mutations.md)

## Test Coverage

- `tests/invariants/subscription-invariants.test.ts` - Core invariants
- `tests/resource/changelog-transaction-consistency.test.ts` - No changelog/event for rolled-back mutations
- `tests/subscription.test.ts` - Basic functionality
- `tests/subscription/backpressure.test.ts` - Load handling
- `tests/concurrency/subscribe-while-mutate.test.ts` - Concurrent operations

---

## Task Contracts


## Guarantees

### Execution Semantics
- **At-least-once execution**: Every scheduled task will be attempted at least once (unless cancelled)
- **Idempotency key respect**: Tasks with the same `idempotencyKey` run the handler at most once within `idempotencyRetentionMs` (default 24h); subsequent executions return the stored result. Requires a shared KV store to hold across workers/instances
- **Concurrency cap**: `maxConcurrency` is enforced via a distributed counter — at most N instances of a task type run concurrently across the fleet; a worker that can't reserve a slot leaves the task for another
- **State machine validity**: Tasks only transition through valid states:
  ```
  scheduled → claimed → running → success|failed|retry
  failed → dlq|retry|scheduled
  retry → scheduled
  dlq → scheduled (replay)
  ```

### Retry Behavior
- **Bounded retries**: Tasks retry up to `maxRetries` times before going to DLQ
- **Exponential backoff**: Retry delays increase exponentially with configurable base and multiplier
- **Jitter**: Retry times include random jitter to prevent thundering herd

### Claim/Lease
- **Exclusive execution**: Only one worker executes a task at a time (via claim mechanism)
- **Claim expiration**: If worker dies, claim expires after timeout, allowing reclaim
- **No dual execution**: CAS operations prevent split-brain dual execution

### Recurring Tasks
- **Scheduled execution**: Recurring tasks execute at specified intervals
- **Timezone honored**: Cron schedules are evaluated in the configured `timezone` (default UTC), so DST transitions shift wall-clock fire times correctly
- **Configurable catchup**: A `catchup` policy controls how missed occurrences (worker downtime / delayed tick) are handled — `"skip"` (default, fire once, no pile-up), `"last"` (coalesce all missed runs into a single execution), or `"all"` (re-run each missed occurrence between `lastRunAt` and now, bounded to 1000 per tick)
- **Drift control**: Fixed-rate vs fixed-delay semantics are explicit and honored

### Dead Letter Queue
- **Replay lineage**: Replaying a DLQ entry preserves `originalTaskId` and increments a `replayCount` that survives across repeated failures/replays; replays may carry an optional `replayedBy` actor and are recorded in a replay audit log
- **Alerting hook**: An optional `onDlqEnqueue` callback fires whenever a task lands in the DLQ (failures in the hook never affect DLQ persistence)
- **Bounded replay**: `retryAll` is bounded by a `limit` (default 100) and audited
- **Metrics**: `metrics()` exposes the current DLQ count and oldest-entry age

### Progress, Heartbeat, Result TTL
- **Progress reporting**: Handlers receive `ctx.reportProgress(percent, message?)` which persists progress (clamped 0–100) so a monitor can read it via `storage.getProgress`
- **Heartbeat**: Running tasks update `lastHeartbeatAt` independently of lock extension, so a stalled task is detectable even while its lock is still valid
- **Result TTL**: `resultTtlMs` (default 24h) sets `resultExpiresAt` on completed/failed records; expired records are removed lazily on the next read rather than accumulating forever

### Cloudflare Queues Backend
- **Push delivery**: `createCloudflareQueueProducer(binding)` enqueues tasks onto a Workers Queue and `createQueueConsumer({ kv, registry })` executes them from a `MessageBatch`, acking on success/dead-letter and retrying (with backoff `delaySeconds`) on retryable failure — no long-lived poller required

## Non-Guarantees

### Timing (What We Don't Promise)
- ❌ **Exact execution time**: Tasks execute "around" scheduled time, not precisely at it
- ❌ **Order preservation**: Tasks scheduled at same time may execute in any order
- ❌ **Clock accuracy**: System depends on reasonable clock accuracy (±seconds, not milliseconds)

### Execution (What We Don't Promise)
- ❌ **Exactly-once**: Delivery is at-least-once. `idempotencyKey` gives effectively-once execution within the retention window when a shared KV is configured, but without an idempotency key (or with a memory KV that isn't shared) a task may run more than once
- ❌ **Concurrency cap without shared KV**: `maxConcurrency` enforcement relies on the shared counter; with the per-process memory KV it only bounds a single instance
- ❌ **Execution duration limits**: Tasks can run indefinitely (unless timeout configured)
- ❌ **Permanent result persistence**: Completed task records (including results) are retained only until `resultExpiresAt` (`resultTtlMs`, default 24h), then removed on the next read; they are not kept forever

### Distributed (What We Don't Promise)
- ❌ **Fair distribution**: Work distribution across workers is best-effort, not guaranteed fair
- ❌ **Affinity**: Same task may execute on different workers across retries

## Failure Modes

### Worker Crash During Execution
- Task remains in `claimed` or `running` state
- Claim expires after timeout
- Another worker reclaims and retries
- `runCount` is incremented for retry tracking

### Database Unavailable
- Task scheduling fails (reported to caller)
- Running tasks may fail to update status
- On recovery, orphaned claims are reclaimed

### Poison Pill (Always-Failing Task)
- Retries up to `maxRetries`
- Moves to DLQ after exhausting retries
- Does NOT block other tasks in queue
- DLQ can be replayed with new idempotency key

### Clock Skew Between Workers
- Claim timeouts account for reasonable skew (recommended: timeout > 2× max skew)
- Scheduling uses server time, not worker time
- Backoff calculations use relative time

## Test Coverage

- `tests/invariants/task-state-machine.test.ts` - State machine invariants
- `tests/invariants/distributed-correctness.test.ts` - Distributed scenarios
- `tests/tasks/worker.test.ts` - Worker behavior
- `tests/tasks/scheduler.test.ts` - Scheduling
- `tests/tasks/retry.test.ts` - Retry logic
- `tests/tasks/dlq.test.ts` - Dead letter queue
- `tests/tasks/recurring.test.ts` - Recurring tasks

---

## Mutation Tracking Contracts


## Guarantees

### Automatic Tracking in Procedures
- **ctx.db is tracked**: When using `useResource`, the `ctx.db` provided to procedure handlers is automatically wrapped with tracking for the current resource
- **Double-wrapping prevention**: If the db passed to `useResource` is already tracked, it won't be wrapped again (checked via `isTrackedDb`)
- **Multi-table support**: For procedures that modify multiple tables, pass a pre-configured tracked db to `config.db`

### Changelog Recording
- **Builder pattern completeness**: Every `insert()`, `update()`, `delete()` operation using the builder pattern records a changelog entry
- **Returning required for full insert tracking**: Inserts with `.returning()` capture the full row; without `.returning()`, only the ID is captured from the input values
- **Update/delete affected rows from the pre-mutation SELECT**: Updates and deletes resolve their affected rows (and `previousObject`) from a pre-mutation SELECT over the `where` clause, so they record one accurate per-row entry **with or without `.returning()`** — they never key an entry off the driver's result-summary object. An update without `.returning()` reconstructs the new object by overlaying the `set` values on the previous row. (Requires `capturePreviousState` true, the default.)
- **Previous state capture**: Updates and deletes capture `previousObject` via a pre-mutation SELECT (when `capturePreviousState` is true)

### Raw SQL Detection
- **Pattern matching**: INSERT, UPDATE, DELETE statements are detected via SQL string parsing
- **Table extraction**: Table name is extracted from the SQL and matched to registered tables
- **Partial tracking**: Raw SQL mutations record `objectId: "*"` (indicating unknown specific IDs)
- **Invalidate semantics**: Raw SQL mutations trigger `invalidate` events for subscribers and invalidate the query cache

### Batch Statements (`db.batch`)
- **Per-statement detection**: Each statement passed to `db.batch([...])` has its compiled SQL inspected and detected as a mutation
- **Coarse tracking**: Detected batch mutations record `objectId: "*"` and trigger `invalidate` (same contract as raw SQL); individual rows are not visible
- **Best-effort**: A statement whose SQL cannot be introspected is silently not tracked

### External-Writer Notification (`recordExternalMutation`)
- **Public entry point**: `recordExternalMutation(resource, type, { objectId? })` is exported for writers outside the tracked db (cron jobs, other services, manual edits, CDC)
- **Effects**: appends a changelog entry, invalidates the query cache, and sends subscribers an `invalidate` event
- **Coarse by default**: `objectId` defaults to `"*"`; no `object`/`previousObject` is carried, so the event is always `invalidate`
- **Portable alternative to CDC**: this is the supported mechanism for keeping Covara subscriptions/caches consistent when mutations bypass the tracked db

### Subscription Integration
- **Automatic push**: Mutations automatically push events to active subscriptions (when `pushToSubscriptions` is true)
- **Event type mapping**:
  - Insert → `added` event
  - Update → `changed` event (with filter scope tracking)
  - Delete → `removed` event
  - Raw SQL → `invalidate` event

### Transaction Handling
- **Transaction wrapping**: Wrapped transactions track all mutations within them
- **Commit-gated side effects**: Inside a tracked `db.transaction(...)`, changelog entries, subscription pushes, and cache invalidations are buffered and only emitted *after* the transaction commits
- **Rollback discards effects**: If a transaction rolls back (the callback throws), the buffered side effects are discarded — no changelog entry, subscription event, or cache invalidation is produced for uncommitted state

### Engines Without Interactive Transactions (Cloudflare D1)
- **Auto-detected**: D1 has no interactive transactions (drizzle's `db.transaction()` issues `BEGIN`/`COMMIT`, which D1 rejects). The resource layer detects D1 and skips `db.transaction()`; override with `transactions: true | false` in the resource config for a custom/unrecognized driver.
- **Single-statement mutations stay atomic**: create / update / replace / delete (and batch update/delete by filter) issue a single write statement, which D1 auto-commits atomically. Changelog/subscription side effects (which are KV writes, never part of DB atomicity) fire exactly once, as on any engine.
- **Batch upsert uses `db.batch()`**: the multi-row upsert path runs all statements through D1's atomic `batch()` primitive instead of a transaction.
- ❌ **Nested writes are not atomic on D1**: a `nestedWrites` create chains inserts whose ids feed the next (parent → main → children), which can't be a single `batch()`. On D1 they run sequentially; a mid-chain failure can leave partial rows.
- ❌ **No after-hook rollback on D1**: because the write has already auto-committed, a throwing `onAfterCreate`/`onAfterUpdate`/`onAfterDelete` cannot roll the row back (it can on transactional engines). The commit-gated/rollback guarantees above apply only to engines with interactive transactions.
- ❌ **`ctx.withTransaction` is non-atomic on D1**: it runs the callback directly against the db; use `db.batch()` for atomic multi-statement work on D1.

### Cache Invalidation
- **Table-level invalidation**: Any mutation to a table invalidates ALL cached queries that reference that table
- **Join-aware invalidation**: Cached queries are tagged with every table they reference, including joined tables; a mutation to ANY referenced table invalidates the cached result (not just the `FROM` table)
- **Automatic clearing**: Cache invalidation happens after a successful mutation (and after commit for transactions), before returning
- **TTL support**: Cached queries respect configured TTL independently of mutation-based invalidation

## Non-Guarantees

### Tracking Completeness
- ❌ **Unregistered tables**: Operations on tables not in the registry are NOT tracked
- ❌ **Raw SQL specificity**: Raw SQL cannot identify specific affected IDs (always uses `objectId: "*"`)
- ❌ **Complex raw SQL parsing**: CTEs, subqueries, and complex SQL patterns may not have their mutation type or table correctly detected

### Cache Behavior
- ❌ **Query-level granularity**: We don't track which rows a query touches; the entire cache for any referenced table is invalidated
- ❌ **Unjoined related tables**: Invalidation only covers tables the cached query actually references (via `from`/`join`); a mutation to a logically-related but unreferenced table does not invalidate the cache
- ❌ **Key set cleanup**: Cache key tracking sets may not be cleaned up when cached data expires via TTL

### Ordering
- ❌ **Global ordering**: Mutations across different database connections are NOT globally ordered
- ❌ **Atomic changelog + data**: The mutation and changelog entry are NOT in a single atomic transaction

## Failure Modes

### Mutation Error
- Changelog entry is NOT recorded if the underlying mutation fails
- No partial state: either both mutation and changelog succeed, or neither does

### Cache Unavailable
- If global KV is not configured, caching is silently disabled
- Cache invalidation attempts are no-ops when KV is unavailable

### SQL Parsing Failure
- If raw SQL cannot be parsed for mutation type/table, no changelog entry is recorded
- The mutation still executes successfully
- No `invalidate` event is triggered

### Previous State Fetch Failure
- If pre-mutation SELECT fails, the mutation continues with `previousObject: undefined`
- Subscription events may have incomplete data

## Invariants

### Idempotent Tracking
- Wrapping an already-wrapped database is safe (the outer wrapper detects and passes through)

### State Consistency
- `hasConflictHandler` prevents false positive mutations on `onConflictDoNothing`
- Empty update/delete results (no rows affected) produce no changelog entries

### Tracking Control
- `withoutTracking` completely disables all tracking for the callback scope
- `skipTables` excludes specific tables from any tracking

## Test Coverage

- `tests/track-mutations.test.ts` - Core functionality
  - Insert tracking (single, batch, returning)
  - Update tracking (with previousObject)
  - Delete tracking (with previousObject)
  - Raw SQL detection (INSERT, UPDATE, DELETE, SELECT)
  - Transaction tracking
  - Configuration options (skipTables, withoutTracking, customResourceName, capturePreviousState)
  - Edge cases (onConflictDoNothing, empty update/delete)
- Query caching tests (same file)
  - Cache behavior (hit, invalidate on mutation)
  - Manual invalidation
  - Configuration (per-table settings, custom prefix)

---

## Aggregations


Every resource exposes `GET /aggregate` for analytics-style queries — counts, sums, averages, and grouping — and `GET /aggregate/subscribe` for a [live version](../realtime/aggregate-subscriptions.md) that recomputes on every mutation.

## Functions

| Function | Parameter | Description |
|----------|-----------|-------------|
| `count` | `count=true` | Count of matching rows. |
| `sum` | `sum=field` | Sum of a numeric column. |
| `avg` | `avg=field` | Average of a numeric column. |
| `min` | `min=field` | Minimum value. |
| `max` | `max=field` | Maximum value. |

Multiple fields are comma-separated (`sum=total,quantity`).

## Query parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `groupBy` | string[] | Columns to group by (comma-separated). |
| `count` | boolean | Include a count. |
| `sum` / `avg` / `min` / `max` | string[] | Columns to aggregate. |
| `filter` | string | [RSQL filter](./filtering.md) applied **before** grouping. |
| `having` | string | Filter the resulting groups by their aggregate output. |

## Response shape

```typescript
interface AggregationResponse {
  groups: Array<{
    key: Record<string, unknown> | null; // null when no groupBy
    count?: number;
    sum?: Record<string, number>;
    avg?: Record<string, number>;
    min?: Record<string, number | string>;
    max?: Record<string, number | string>;
  }>;
}
```

## Examples

```bash
# Count everything
GET /api/users/aggregate?count=true
# → { "groups": [{ "key": null, "count": 1234 }] }

# Group by one column
GET /api/users/aggregate?groupBy=role&count=true
# → groups: [{ key: { role: "admin" }, count: 5 }, { key: { role: "user" }, count: 95 }]

# Group by multiple columns with stats
GET /api/orders/aggregate?groupBy=category&count=true&sum=total,quantity&avg=total&min=total&max=total

# Filter rows before aggregating
GET /api/orders/aggregate?filter=status=="completed"&groupBy=category&sum=total
```

Client:

```typescript
const orders = client.resource<Order>("/api/orders");
const byCategory = await orders.aggregate({
  groupBy: ["category"],
  count: true,
  sum: ["total"],
  avg: ["total"],
});
```

## Filtering groups with HAVING

`filter` narrows rows **before** grouping; `having` filters **groups** by their aggregate output, joined by `;` (AND).

```bash
# Categories with ≥5 orders AND revenue > 100
GET /api/orders/aggregate?groupBy=category&count=true&sum=total&having=count>=5;sum_total>100
```

`having` references the aggregate **output aliases**:

| Alias | Produced by |
|-------|-------------|
| `count` | `count=true` |
| `sum_<field>` | `sum=<field>` |
| `avg_<field>` | `avg=<field>` |
| `min_<field>` | `min=<field>` |
| `max_<field>` | `max=<field>` |
| `<field>` | a `groupBy` column |

Supported operators: `==`, `!=`, `>`, `>=`, `<`, `<=`. An alias used in `having` must be selected by the query (`sum_total` requires `sum=total`); referencing an unknown alias returns `400`. Numeric right-hand values compare numerically; otherwise as strings.

```bash
GET /api/orders/aggregate?groupBy=status&avg=total&having=avg_total>500
```

:::note
`having` is exposed through the HTTP query parameter. The typed client's `aggregate()` helper does not yet surface it.
:::

## Live aggregations

`GET /aggregate/subscribe` (and `useLiveAggregate` / `subscribeAggregate` on the client) streams the aggregate result and recomputes it whenever the resource is mutated. It is scope-aware, so per-user aggregates don't recompute for other users' changes. See **[Aggregate subscriptions](../realtime/aggregate-subscriptions.md)** for the full semantics.

```tsx
import { useLiveAggregate } from "covara/client/react";

function TodoStats() {
  const { groups, isLive } = useLiveAggregate("/api/todos", { groupBy: ["completed"], count: true });
  const completed = groups.find((g) => g.key?.completed)?.count ?? 0;
  return {completed} completed {isLive ? "🟢" : "…"};
}
```

## Performance

- Aggregations scan all matching rows — index the columns used in `groupBy` and `filter`.
- For very large datasets consider pre-aggregated summary tables, time partitioning, or [background jobs](../platform/tasks.md).

## Related

- [Filtering](./filtering.md) · [Aggregate subscriptions](../realtime/aggregate-subscriptions.md)
- [Client queries](../client/queries.md) · [React hooks](../client/react-hooks.md)

---

## Batch operations


Resources expose bulk endpoints for creating, updating, deleting, and upserting many rows at once. They are gated by the single [`enableBatch`](./resources-and-app.md#capabilities) capability and bounded by the `batch` limits.

## Limits

```typescript
useResource(postsTable, {
  id: postsTable.id,
  db,
  batch: {
    create: 50,  // max items per POST /batch
    update: 50,  // max items per PATCH /batch
    replace: 50, // max items per PUT-style replace batch
    delete: 10,  // max items per DELETE /batch
  },
});
```

Exceeding a limit returns a `BatchLimitError` (`400`). See [Error handling](../tooling/error-handling.md).

## Batch create — `POST /batch`

```bash
POST /api/posts/batch
Content-Type: application/json

{ "items": [{ "title": "A" }, { "title": "B" }] }
```

Each item runs the create [lifecycle hooks](./procedures.md) and emits an `added` [event](../realtime/subscriptions.md). [`fields.writable`](./fields.md) enforcement and `strictInput` apply per item. Returns `{ "items": [...] }` with the created rows (read-masked, computed fields applied).

## Batch update — `PATCH /batch`

Updates many rows matched by a filter, applying the same patch to each:

```bash
PATCH /api/posts/batch
Content-Type: application/json

{ "filter": "authorId==\"u1\";published==false", "patch": { "published": true } }
```

Each affected row runs the update hooks and emits a `changed` event. The matched set respects the [update scope](../auth/scopes.md).

## Batch delete — `DELETE /batch`

```bash
DELETE /api/posts/batch
Content-Type: application/json

{ "filter": "status==\"spam\"" }
```

Deletes (or [soft-deletes](./soft-delete.md)) the matching rows within the delete scope, running delete hooks and emitting `removed` events.

## Bulk upsert — `POST /batch/upsert` {#bulk-upsert}

Inserts or updates a list keyed by primary key, in a single transaction. Same request shape as batch create, bounded by `batch.create`. Requires **both** `create` and `update` scope plus `enableBatch`.

```bash
POST /api/posts/batch/upsert
Content-Type: application/json

{
  "items": [
    { "id": "p1", "title": "Existing, updated" },
    { "id": "p2", "title": "Brand new" }
  ]
}
```

For each item:

- **Exists** → runs `onBeforeUpdate`/`onAfterUpdate`, emits `changed`.
- **New** → runs `onBeforeCreate`/`onAfterCreate`, emits `added`.

`fields.writable` enforcement applies to every item. Returns `{ "items": [...] }` with the upserted rows.

## Notes

- Batch mutations participate in [mutation tracking](../realtime/mutation-tracking.md), so every item streams to subscribers and invalidates caches.
- Confirmation/safety bounds and the per-operation limits guard against runaway bulk writes.

## Related

- [CRUD endpoints](./crud.md) · [Procedures & hooks](./procedures.md) · [Soft delete](./soft-delete.md)
- [Authorization scopes](../auth/scopes.md) · [Error handling](../tooling/error-handling.md)

---

## CRUD endpoints


Every [resource](./resources-and-app.md) generates a standard set of REST endpoints. This page documents their request and response shapes. Filtering, pagination, ordering, and relation includes are covered in their own pages and apply to the list endpoint.

## List — `GET /`

Returns a paginated list. Supports [`filter`](./filtering.md), [`select`](#projections), [`include`](./relations.md), [`orderBy`, `cursor`, `limit`, `totalCount`](./pagination.md).

```bash
GET /api/posts?filter=published==true&orderBy=createdAt:desc&limit=20&include=author
```

```json
{
  "items": [{ "id": "p1", "title": "Hello", "author": { "id": "u1", "name": "Ada" } }],
  "nextCursor": "eyJ2YWx1ZXMiOnsuLi59fQ==",
  "hasMore": true,
  "totalCount": 137
}
```

`totalCount` is present only when `?totalCount=true`.

## Get one — `GET /:id`

```bash
GET /api/posts/p1?include=author,tags
```

Returns the single row, or `404` if not found or outside the read [scope](../auth/scopes.md). With [ETags](./optimistic-locking.md) enabled, the response carries an `ETag` header and honors `If-None-Match` (returns `304`).

## Create — `POST /`

```bash
POST /api/posts
Content-Type: application/json

{ "title": "Hello", "body": "..." }
```

- Runs `onBeforeCreate` → insert → `onAfterCreate` ([hooks](./procedures.md)).
- [`fields.writable`](./fields.md) strips non-writable columns before hooks run; [`strictInput`](./fields.md) rejects unknown fields with `422`.
- Emits an `added` [subscription event](../realtime/subscriptions.md).
- Returns the created row (`201`), read-masked with [computed fields](./fields.md#computed-fields) applied.
- With [`nestedWrites`](./nested-writes.md), embedded relation objects are created in the same transaction.

## Update (partial) — `PATCH /:id`

Updates only the provided fields.

```bash
PATCH /api/posts/p1
Content-Type: application/json

{ "title": "Updated title" }
```

Runs `onBeforeUpdate` → update → `onAfterUpdate`, emits a `changed` event, enforces [`If-Match`](./optimistic-locking.md) when ETags are configured (`412` on mismatch), and auto-increments the version field.

## Replace (full) — `PUT /:id`

Same as `PATCH` but replaces the whole row; omitted writable fields are reset to their defaults/null. Governed by the same `enableUpdate` [capability](./resources-and-app.md#capabilities).

## Delete — `DELETE /:id`

```bash
DELETE /api/posts/p1
```

Returns `204`. Runs `onBeforeDelete`/`onAfterDelete`, emits a `removed` event, enforces `If-Match`. With [`softDelete`](./soft-delete.md), the row is marked instead of removed.

## Counting — `GET /count` {#counting}

```bash
GET /api/posts/count?filter=published==true
```

```json
{ "count": 137 }
```

Honors the read scope and `filter`; excludes [soft-deleted](./soft-delete.md) rows unless `?withDeleted=true`.

## Projections

The `select` parameter narrows returned columns:

```bash
GET /api/posts?select=id,title,createdAt
GET /api/posts/p1?select=id,title
```

`select` cannot recover columns hidden by [`fields.readable`](./fields.md) — masking is applied after projection. [Computed fields](./fields.md#computed-fields) and included relations always pass through.

The typed client narrows the return type to exactly the selected fields — see [Client queries](../client/queries.md).

## Error format

All errors use RFC 7807 Problem Details. See [Error handling](../tooling/error-handling.md).

```json
{
  "type": "https://covara.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "post p1 not found"
}
```

## Related

- [Filtering](./filtering.md) · [Pagination](./pagination.md) · [Relations](./relations.md)
- [Fields](./fields.md) · [Optimistic locking](./optimistic-locking.md) · [Batch operations](./batch.md)
- [Subscriptions](../realtime/subscriptions.md) — every mutation streams to subscribers

---

## Fields: masking, writable, computed


The `fields` config controls, per column, what clients can **read**, **write**, **filter**, and **sort** by. Combined with `computed`, `generatedFields`, and `strictInput`, it gives you defense against mass-assignment and over-exposure with no extra code.

Pass the **Drizzle column** (like `id`); a string column name also works but is deprecated.

```typescript
useResource(usersTable, {
  id: usersTable.id,
  db,
  fields: {
    readable: [usersTable.id, usersTable.name, usersTable.email, usersTable.createdAt],
    writable: [usersTable.name, usersTable.email],
    filterable: [usersTable.name, usersTable.email, usersTable.createdAt],
    sortable: [usersTable.name, usersTable.createdAt],
  },
});
```

## Read masking — `fields.readable`

When set, `readable` is an **allowlist of table columns** that may leave the server. Any column not listed is stripped from **every** response — list, get, create, update, batch, search — and from **every** subscription event (`existing`, `added`, `changed`) and the initial snapshot.

The mask is applied server-side, so a client **cannot** recover a hidden column via `?select=` or by subscribing:

```typescript
fields: {
  // passwordHash, internalNotes, etc. are never returned, regardless of ?select=
  readable: [usersTable.id, usersTable.name, usersTable.email, usersTable.createdAt],
}
```

Only **table columns** are masked. [Relation keys](./relations.md) (loaded via `?include=`), [computed values](#computed-fields), and internal markers like `_etag`/`_optimisticId` always pass through, so includes keep working. See the [auth contract](../contracts/auth.md) for the guarantee.

## Write enforcement — `fields.writable` (mass-assignment protection) {#write-enforcement-fieldswritable-mass-assignment-protection}

When set, `writable` is an **enforced allowlist** of table columns a client may set on create/update. Any table column not listed is silently stripped from the incoming body **before** it reaches lifecycle hooks or the database — on `POST /`, `PATCH /:id`, `PUT /:id`, `POST /batch`, `PATCH /batch`, and `POST /batch/upsert`.

This stops a malicious client from setting protected columns (e.g. `role`, `isAdmin`, `ownerId`) by smuggling them into a body.

**Exemptions:**

- The **primary key** (`id`) is never stripped.
- Columns in [`generatedFields`](#generated-fields) are never stripped.
- Non-column keys (relation payloads for [nested writes](./nested-writes.md), etc.) always pass through — only real table columns are subject to the allowlist.

Stripping happens **before** hooks run, so a server-side `onBeforeCreate`/`onBeforeUpdate` can still set a protected field itself:

```typescript
hooks: {
  onBeforeCreate: async (ctx, data) => ({ ...data, ownerId: ctx.user.id }), // ownerId set server-side
}
```

See [Secure queries](../auth/secure-queries.md) for the broader pattern.

## Filter & sort allowlists

- `fields.filterable` — only these columns may appear in [`?filter=`](./filtering.md); others return a `400 FilterParseError`.
- `fields.sortable` — only these columns may appear in `?orderBy=`.

Use these to prevent clients from filtering/sorting on sensitive or unindexed columns.

## `strictInput`

By default, unknown fields in a body are silently ignored. Set `strictInput: true` to reject them with a `422` (Zod strict mode):

```typescript
{ strictInput: true }
```

`generatedFields` may still be omitted. Combine `strictInput` (reject unknown fields) with `fields.writable` (strip known-but-not-writable columns) for the strictest input handling.

## Generated fields

`generatedFields` marks columns the server fills in (id, timestamps, ownership). They are:

- exempt from `fields.writable` stripping (a hook can set them),
- optional in inbound bodies even under `strictInput`.

```typescript
{ generatedFields: [posts.id, posts.userId, posts.createdAt, posts.updatedAt] }
```

## Computed fields

Virtual fields added to every response and subscription event, computed from the **full, unmasked row** and never persisted:

```typescript
computed: {
  fullName: (row) => `${row.firstName} ${row.lastName}`,
  isOverdue: (row) => row.dueAt != null && Date.parse(row.dueAt) < Date.now(),
}
```

Computed fields:

- appear in list, get, create, update, batch, and search responses, plus every subscription event and the initial snapshot;
- can derive from columns that `fields.readable` hides (they read the unmasked row);
- are **exempt from read masking** (not table columns), so the `readable` allowlist never strips them;
- are not written to the database.

## Related

- [Authorization scopes](../auth/scopes.md) · [Secure queries](../auth/secure-queries.md)
- [Filtering](./filtering.md) · [Relations](./relations.md) · [Auth contract](../contracts/auth.md)

---

## Filtering (RSQL)

# Filtering

Covara uses an RSQL-like syntax for the `filter` query parameter. The same filter string is compiled to **Drizzle SQL** for database queries and executed **in-memory** for subscription matching, so a subscription's filter always behaves identically to the equivalent list query.

:::tip
This page covers applying filters to query endpoints. For the full RSQL reference — the language, every operator, and the type-safe TypeScript builder (`rsql` tag + helpers) shared with [authorization scopes](../auth/scopes.md) — see [**RSQL**](./rsql.md).
:::

```bash
GET /api/users?filter=status=="active";age>18
```

## Basic syntax

```
field==value        # Equals
field!=value        # Not equals
field>value         # Greater than
field>=value        # Greater than or equal
field<value         # Less than
field<=value        # Less than or equal
```

Both symbolic and named comparison operators are supported and equivalent:

| Symbolic | Named | Description |
|----------|-------|-------------|
| `>` | `=gt=` | Greater than |
| `>=` | `=ge=` | Greater than or equal |
| `<` | `=lt=` | Less than |
| `<=` | `=le=` | Less than or equal |

```bash
GET /api/users?filter=age>18      # equivalent to:
GET /api/users?filter=age=gt=18
```

## Combinators

| Combinator | Meaning | Forms |
|------------|---------|-------|
| AND | both must hold | `;` · `&&` · `and` |
| OR | either holds | `,` · `\|\|` · `or` |
| Grouping | precedence | `( ... )` |

```
status=="active";age>18
status=="active" && age>18
role=="admin",role=="moderator"
(status=="active";age>18),(role=="admin")
```

## Set membership

```
field=in=(a,b,c)    # value is in the list
field=out=(a,b,c)   # value is not in the list
```

```bash
GET /api/users?filter=role=in=("admin","moderator")
GET /api/users?filter=status=out=("deleted","banned")
```

## Range / between

Both `[...]` and `(...)` forms work:

```bash
GET /api/users?filter=age=between=[18,65]
GET /api/products?filter=price=between=(10,100)
GET /api/events?filter=date=between=["2024-01-01","2024-12-31"]
GET /api/users?filter=age=nbetween=[0,17]
```

## String operations

### Pattern matching (LIKE)

```
field%="pattern"        # LIKE (case-sensitive)
field!%="pattern"       # NOT LIKE
field=ilike="pattern"   # case-insensitive LIKE
field=nilike="pattern"  # case-insensitive NOT LIKE
```

SQL wildcards: `%` matches any sequence, `_` matches a single character.

```bash
GET /api/users?filter=email%="%@gmail.com"
GET /api/users?filter=name=ilike="%john%"
```

### Substring / prefix / suffix

```
field=contains="text"     field=icontains="text"
field=startswith="text"   field=istartswith="text"
field=endswith="text"     field=iendswith="text"
```

```bash
GET /api/users?filter=name=contains="Smith"
GET /api/users?filter=email=iendswith="@company.com"
```

### Case-insensitive equality

```
field=ieq="value"   # case-insensitive equals
field=ine="value"   # case-insensitive not equals
```

### Regular expressions

```
field=regex="pattern"    field=iregex="pattern"
```

```bash
GET /api/users?filter=email=regex="^admin@"
```

Regex support varies by database; in-memory subscription matching uses JavaScript `RegExp`.

### Length checks

```
field=length=N       field=minlength=N       field=maxlength=N
```

## Null and empty checks

```
field=isnull=true    # is null
field=isnull=false   # is not null
field=isempty=true   # null or empty string
field=isempty=false  # has a non-empty value
```

## Boolean comparisons

Booleans are matched intelligently, handling databases that store them as 0/1:

```
field==true    # matches true, 1, "true", "1"
field==false   # matches false, 0, "false", "0"
field!=true    # matches anything not truthy
```

```bash
GET /api/users?filter=isActive==true
```

## Dates

ISO 8601 strings are auto-detected and parsed:

```bash
GET /api/posts?filter=createdAt>"2024-01-15T10:30:00.000Z"
GET /api/posts?filter=createdAt>="2024-01-15"
GET /api/posts?filter=createdAt>="2024-01-01";createdAt<"2024-02-01"
GET /api/events?filter=startDate=between=["2024-06-01","2024-06-30"]
```

## Value types & escaping

```
name=="John Doe"             # strings (quoted)
age==25  price==19.99        # numbers (unquoted)
active==true                 # booleans
deletedAt==null              # null
tags=in=("tech","news")      # sets
age=between=[18,65]          # ranges
name=="John \"Johnny\" Doe"  # escape quotes inside strings
path=="C:\\Users\\John"      # escape backslashes
```

## Complete operator reference

| Operator | Description | Example |
|----------|-------------|---------|
| `==` | Equals | `status=="active"` |
| `!=` | Not equals | `status!="deleted"` |
| `>`, `=gt=` | Greater than | `age>18` |
| `>=`, `=ge=` | Greater than or equal | `age>=18` |
| `<`, `=lt=` | Less than | `age<65` |
| `<=`, `=le=` | Less than or equal | `age<=65` |
| `=in=` | In list | `role=in=("a","b")` |
| `=out=` | Not in list | `role=out=("x","y")` |
| `%=` | LIKE | `name%="%john%"` |
| `!%=` | NOT LIKE | `name!%="%test%"` |
| `=ilike=` | Case-insensitive LIKE | `name=ilike="%john%"` |
| `=nilike=` | Case-insensitive NOT LIKE | `name=nilike="%test%"` |
| `=contains=` | Contains substring | `name=contains="john"` |
| `=icontains=` | Case-insensitive contains | `name=icontains="john"` |
| `=startswith=` | Starts with | `name=startswith="Dr."` |
| `=istartswith=` | Case-insensitive starts with | `name=istartswith="dr."` |
| `=endswith=` | Ends with | `email=endswith=".com"` |
| `=iendswith=` | Case-insensitive ends with | `email=iendswith=".COM"` |
| `=ieq=` | Case-insensitive equals | `status=ieq="ACTIVE"` |
| `=ine=` | Case-insensitive not equals | `status=ine="deleted"` |
| `=isnull=` | Is null | `deletedAt=isnull=true` |
| `=isempty=` | Null or empty string | `bio=isempty=true` |
| `=between=` | In range (inclusive) | `age=between=[18,65]` |
| `=nbetween=` | Not in range | `age=nbetween=[0,17]` |
| `=regex=` | Regex match | `email=regex="^admin@"` |
| `=iregex=` | Case-insensitive regex | `name=iregex="^john"` |
| `=length=` | Exact string length | `code=length=6` |
| `=minlength=` | Minimum string length | `password=minlength=8` |
| `=maxlength=` | Maximum string length | `username=maxlength=20` |

## Custom operators

Define operators with both a SQL `convert` (for queries) and a JS `execute` (for subscription matching). Providing both keeps query and subscription behavior consistent.

```typescript
import { sql } from "drizzle-orm";

useResource(usersTable, {
  id: usersTable.id,
  db,
  customOperators: {
    "=jsoncontains=": {
      convert: (lhs, rhs) => sql`JSON_CONTAINS(${lhs}, ${rhs})`,
      execute: (lhs, rhs) => JSON.parse(String(lhs)).includes(rhs),
    },
  },
});
```

```bash
GET /api/users?filter=permissions=jsoncontains="write"
```

## Filterable allowlist

To restrict which columns may be filtered, set [`fields.filterable`](./fields.md). A filter referencing a non-allowed column returns a `400 FilterParseError`.

## Related

- [Fields](./fields.md) — `filterable`/`sortable` allowlists
- [Subscriptions](../realtime/subscriptions.md) — filters scope the live stream
- [Authorization scopes](../auth/scopes.md) — scopes are RSQL filters combined with the request filter
- [RSQL](./rsql.md) — the full language reference + the type-safe TypeScript builder (`rsql` tag + helpers), used for both filters and scopes

---

## Nested write-through


With `nestedWrites: true`, a `POST /` body may embed related objects under their [relation](./relations.md) names. They are created together with the main row in a **single transaction**, with foreign keys wired automatically. If any insert fails, the whole transaction rolls back.

`nestedWrites` is off by default and requires `relations` to be configured.

:::caution Cloudflare D1
D1 has no interactive transactions, and a nested write chains inserts whose generated ids feed the next, so it can't be a single atomic `batch()`. On D1 these inserts run sequentially and are **not** atomic — a mid-chain failure can leave partial rows. See the [Workers guide](../deployment/workers.md#d1-and-transactions).
:::

```typescript
useResource(postsTable, {
  db,
  id: postsTable.id,
  nestedWrites: true,
  relations: {
    author: {
      resource: "users", schema: usersTable, type: "belongsTo",
      foreignKey: postsTable.authorId, references: usersTable.id,
    },
    comments: {
      resource: "comments", schema: commentsTable, type: "hasMany",
      foreignKey: commentsTable.postId, references: postsTable.id,
    },
  },
});
```

```jsonc
// POST /api/posts
{
  "title": "Hello",
  // belongsTo parent — created first, its key wired into the post's foreignKey
  "author": { "id": "u1", "name": "Ada" },
  // hasMany children — created after the post, wired to the new post's referenced key
  "comments": [{ "text": "first!" }, { "text": "nice" }]
}
```

## Order of operations

Inside the transaction:

1. **`belongsTo` parents** are inserted first; the new parent's referenced value is written into the main row's foreign-key column.
2. **The main row** is inserted (after `onBeforeCreate` hooks run).
3. **`hasMany`/`hasOne` children** are inserted, each wired to the new row's referenced key. A `hasOne` value may be a single object; `hasMany` accepts an array (a single object is also accepted as one child).

The response is the **created main row** — parents and children are not echoed back. Refetch with [`?include=`](./relations.md) to read them.

## Limitation

`manyToMany` nested writes are **not** supported. Embedding a `manyToMany` relation in the create body has no effect on the junction table — manage those links separately (e.g. with a custom [RPC procedure](./procedures.md) or batch insert into the junction resource).

## Related

- [Relations](./relations.md) · [CRUD endpoints](./crud.md) · [Procedures & hooks](./procedures.md)

---

## Optimistic locking (ETags)


Configure `etag` on a resource to get HTTP conditional requests and optimistic concurrency control: ETag headers on single-item responses, `If-Match` enforcement on writes (with compare-and-swap), `If-None-Match` 304s on reads, and auto-incrementing version fields.

```typescript
useResource(postsTable, {
  id: postsTable.id,
  db,
  etag: {
    versionField: postsTable.version,      // integer column, auto-incremented on every update
    // updatedAtField: postsTable.updatedAt,  // alternative: timestamp-based tags
    // idField: postsTable.id,                // paired with updatedAtField (default "id")
    // algorithm: "weak",                      // "weak" (default) or "strong"
  },
});
```

Pass the **Drizzle column** to `versionField`/`updatedAtField`/`idField` (like `id`); a string column name also works but is deprecated.

Without the `etag` config, no ETag headers are emitted and conditional headers are ignored.

## ETag emission

`POST /`, `GET /:id`, `PATCH /:id`, and `PUT /:id` responses carry an `ETag` header. The tag is derived in this precedence:

1. `versionField` (if set and present on the item), then
2. `updatedAtField` + `idField` (timestamp-id pair), then
3. an MD5 hash of the serialized item.

Tags are **weak** (`W/"..."`) unless `algorithm: "strong"`. The same item state always produces the same ETag. Treat ETags as **opaque** — the hash-fallback format may change between minor versions.

## Conditional writes — `If-Match`

`If-Match` is checked against the **current** stored item on `PATCH /:id`, `PUT /:id`, and `DELETE /:id` before the mutation runs:

- **Mismatch → `412 Precondition Failed`** (RFC 7807 body with `currentETag` in `details`); the row is unchanged.
- **Compare-and-swap:** when `If-Match` is present, the write statement carries a CAS predicate on the version/updated-at field, so the validated version must still match at write time. If a concurrent writer changed the row between read and write, zero rows match and the request fails with `412` — exactly one of N concurrent `If-Match` writers wins, the rest get `412`.
- **`If-Match: *`** matches any current state (write proceeds if the item exists).
- A comma-separated list passes if **any** tag matches; comparison uses RFC 7232 strong comparison.
- **No header → unconditional** write (last-write-wins, no CAS predicate).

```bash
PATCH /api/posts/p1
If-Match: W/"4"
Content-Type: application/json

{ "title": "New title" }
# → 200 with ETag W/"5", or 412 if the stored version is no longer 4
```

## Conditional reads — `If-None-Match`

`GET /:id` with a matching `If-None-Match` returns `304 Not Modified` (empty body, current `ETag`). A non-matching tag returns `200` with the full representation.

```bash
GET /api/posts/p1
If-None-Match: W/"5"
# → 304 if unchanged, 200 + body otherwise
```

## Version auto-increment

When `versionField` is configured, it is incremented by 1 on every `PATCH`/`PUT`, starting from the stored value (missing/non-numeric values are left untouched). If the request body explicitly sets the version field, that value is used instead.

**Lost-update protection:** two clients read version N and both write with `If-Match`. The CAS predicate guarantees exactly one write lands; the other matches zero rows, gets `412`, and must refetch.

## Limitations

- `GET /` (list) responses do **not** carry per-item ETags.
- `If-Match` is **not** enforced on `/batch` operations, and batch updates do not auto-increment the version field.
- The CAS predicate requires a `versionField` or `updatedAtField`. With neither (hash-only ETags), `If-Match` is still checked before the write but is not atomic with it.

See the [ETag contract](../contracts/etag.md) for the full guarantee list and failure modes.

## Client integration

The [offline client](../client/offline.md) tracks ETags per item and replays `If-Match` on queued mutations, surfacing `412`s as conflicts to reconcile.

## Related

- [CRUD endpoints](./crud.md) · [Offline support](../client/offline.md) · [ETag contract](../contracts/etag.md)

---

## Pagination


Covara uses **cursor-based (keyset) pagination** for list endpoints. It is stable under concurrent modification — inserting or deleting rows on an earlier page does not shift items across page boundaries the way offset pagination does.

## Configuration

```typescript
useResource(usersTable, {
  id: usersTable.id,
  db,
  pagination: {
    defaultLimit: 20, // page size when ?limit is omitted
    maxLimit: 100,    // ceiling; larger ?limit values are clamped
  },
});
```

## Query parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Items per page (capped by `maxLimit`). |
| `cursor` | string | Opaque cursor from the previous response. |
| `orderBy` | string | Sort order, e.g. `name:asc,createdAt:desc`, or the `-field` shorthand. |
| `totalCount` | boolean | Include the total count of matching rows. |

## Response shape

```typescript
interface PaginatedResponse<T> {
  items: T[];
  nextCursor: string | null; // null on the last page
  hasMore: boolean;
  totalCount?: number;       // only when totalCount=true
}
```

## Ordering

```bash
GET /api/users?orderBy=name:asc
GET /api/users?orderBy=createdAt:desc
GET /api/users?orderBy=role:asc,name:asc      # multi-field
GET /api/users?orderBy=-createdAt             # JSON:API shorthand = createdAt:desc
GET /api/users?orderBy=-createdAt,name        # desc, then asc
```

Mixing both syntaxes on the **same** field (e.g. `-name:desc`) is a conflict and returns `400`.

The primary key is always appended as the final sort key to guarantee a total ordering, so pagination never skips or duplicates rows even when the chosen sort columns have ties.

## Total count

```bash
GET /api/users?limit=10&totalCount=true
```

`totalCount` requires an extra `COUNT` query. Omit it on large tables when you do not need it.

## Cursor internals

A cursor is base64-encoded JSON capturing the last row's sort values and ID plus the order spec:

```json
{ "values": { "name": "Alice", "id": 42 }, "orderBy": ["name:asc", "id:asc"] }
```

By default a cursor is **validated** (version, structure, and an `orderBy` fingerprint), so a malformed cursor or one replayed under a different `orderBy` fails with a `400`. The payload itself is base64-readable and not cryptographically protected — but it doesn't need to be: a cursor only encodes a keyset *position*, and every query still runs through the resource's auth scope + filter, so a forged position can't widen access. **Do not** change `orderBy` between pages while reusing a cursor; the cursor encodes the order it was issued for.

### Signed cursors (optional)

Set a `cursorSigningSecret` to HMAC-sign cursors — the encoded payload is suffixed with `.<hmac-sha256(payload, secret)>` and the signature is verified on decode, so a tampered or forged cursor is rejected with a `400` (`reason: "tampered"`). Configure it per resource or globally:

```typescript
import { setGlobalCursorSigningSecret } from "covara";

// Global default for every resource:
setGlobalCursorSigningSecret(env.CURSOR_SECRET);

useResource(usersTable, {
  id: usersTable.id,
  db,
  cursorSigningSecret: env.CURSOR_SECRET, // per-resource (overrides global)
});
```

Resolution: a resource's `cursorSigningSecret` overrides the global one; set it to `null` to disable signing for that resource even when a global secret is configured; leave it unset (`undefined`) to inherit the global. With no secret anywhere, cursors are unsigned (still validated as above). See the [pagination contract](../contracts/pagination.md) for the integrity guarantees.

## Client usage

```typescript
const users = client.resource<User>("/api/users");

const page1 = await users.list({ limit: 10, orderBy: "name:asc" });
if (page1.hasMore) {
  const page2 = await users.list({ limit: 10, orderBy: "name:asc", cursor: page1.nextCursor });
}
```

Iterate every page:

```typescript
async function getAll(filter?: string): Promise<User[]> {
  const out: User[] = [];
  let cursor: string | null = null;
  do {
    const page = await users.list({ filter, limit: 100, cursor: cursor ?? undefined });
    out.push(...page.items);
    cursor = page.nextCursor;
  } while (cursor !== null);
  return out;
}
```

In React, prefer [`useInfiniteList`](../client/react-hooks.md) / `useLiveList`'s `loadMore` which manage cursors for you.

## Best practices

- Keep `maxLimit` modest to bound payload size and query cost.
- Index the columns you sort by; the trailing primary-key tiebreaker should be indexed too.
- Avoid `totalCount` on large tables unless the UI needs it.
- Keep `orderBy` constant across a paged sequence.

## Related

- [Filtering](./filtering.md) — combine `filter` with pagination
- [Client queries](../client/queries.md) · [React hooks](../client/react-hooks.md)
- [Pagination contract](../contracts/pagination.md)

---

## Procedures & lifecycle hooks


Covara gives you two extension points for business logic on a resource: **RPC procedures** (custom validated endpoints) and **lifecycle hooks** (before/after every CRUD operation).

## RPC procedures

`defineProcedure` creates a Zod-validated endpoint mounted at `POST /rpc/:name`.

```typescript
import { defineProcedure } from "covara";
import { z } from "zod";
import { eq } from "drizzle-orm";

useResource(postsTable, {
  id: postsTable.id,
  db,
  procedures: {
    publish: defineProcedure({
      input: z.object({ id: z.string(), scheduledAt: z.string().datetime().optional() }),
      output: z.object({ success: z.boolean(), publishedAt: z.string().datetime() }),
      handler: async (ctx, input) => {
        if (!ctx.user) throw new Error("Not authenticated");
        const publishedAt = input.scheduledAt ?? new Date().toISOString();
        await ctx.db
          .update(postsTable)
          .set({ published: true, publishedAt: new Date(publishedAt) })
          .where(eq(postsTable.id, input.id))
          .returning();
        return { success: true, publishedAt };
      },
    }),
  },
});
```

```bash
POST /api/posts/rpc/publish
Content-Type: application/json

{ "id": "post-123" }
```

Input is validated against the `input` schema (`422` on failure) and the result against `output`.

### Procedure context

```typescript
interface ProcedureContext {
  db: TrackedDatabase;      // tracked db — mutations auto-recorded for this resource
  schema: Table;            // the Drizzle table
  user: UserContext | null; // authenticated user
  req: Request | null;      // raw web Request
  context: Context | null;  // Hono Context (headers, cookies, ...)
}
```

`ctx.db` is automatically [tracked](../realtime/mutation-tracking.md) for the current resource, so mutations made through it record to the changelog and push to subscribers with no extra code.

### Multi-table tracking

If a procedure mutates several tables, wrap your db once at startup and pass it as `config.db`:

```typescript
import { trackMutations } from "covara";

const trackedDb = trackMutations(baseDb, {
  posts: { table: postsTable, id: postsTable.id },
  notifications: { table: notificationsTable, id: notificationsTable.id },
});

useResource(postsTable, {
  id: postsTable.id,
  db: trackedDb, // already tracked — not double-wrapped
  procedures: {
    publish: defineProcedure({
      handler: async (ctx, input) => {
        await ctx.db.update(postsTable).set({ published: true }).where(eq(postsTable.id, input.id)).returning();
        await ctx.db.insert(notificationsTable).values({ type: "post_published", postId: input.id }).returning();
        return { success: true };
      },
    }),
  },
});
```

See [Mutation tracking](../realtime/mutation-tracking.md).

:::warning Deprecated
The `writeEffects` property is deprecated. Use `trackMutations` and `ctx.db` for accurate subscription updates.
:::

## Lifecycle hooks

Run code before/after each operation. `onBefore*` hooks can transform the payload (return the modified data) or throw to cancel.

```typescript
useResource(postsTable, {
  id: postsTable.id,
  db,
  hooks: {
    onBeforeCreate: async (ctx, data) => ({ ...data, authorId: ctx.user?.id, createdAt: new Date() }),
    onAfterCreate: async (ctx, created) => { await sendNotification("New post"); },
    onBeforeUpdate: async (ctx, id, data) => ({ ...data, updatedAt: new Date() }),
    onAfterUpdate: async (ctx, updated) => { await reindex(updated); },
    onBeforeDelete: async (ctx, id) => {
      const post = await db.query.posts.findFirst({ where: eq(postsTable.id, id) });
      if (post?.protected) throw new Error("Cannot delete protected post");
    },
    onAfterDelete: async (ctx, deleted) => { await cleanupComments(deleted.id); },
  },
});
```

Hooks run for the equivalent batch operations too (`onBeforeCreate` per item on `POST /batch`, etc.). Field stripping from [`fields.writable`](./fields.md) happens **before** `onBefore*` hooks, so a hook can still set protected columns.

## Composing hooks

```typescript
import { composeHooks, createTimestampHooks } from "covara";

const auditHooks = {
  onAfterCreate: async (ctx, created) => logAudit("create", ctx.user?.id, created.id),
  onAfterUpdate: async (ctx, updated) => logAudit("update", ctx.user?.id, updated.id),
  onAfterDelete: async (ctx, deleted) => logAudit("delete", ctx.user?.id, deleted.id),
};

useResource(postsTable, {
  id: postsTable.id,
  db,
  hooks: composeHooks(
    createTimestampHooks(),                                  // createdAt/updatedAt
    auditHooks,                                              // audit logging
    { onBeforeCreate: async (ctx, data) => ({ ...data, slug: slugify(data.title) }) },
  ),
});
```

`composeHooks` runs `onBefore*` hooks left-to-right (each receiving the previous one's output) and `onAfter*` hooks in order.

## Related

- [Mutation tracking](../realtime/mutation-tracking.md) · [Subscriptions](../realtime/subscriptions.md)
- [Fields](./fields.md) · [Authorization scopes](../auth/scopes.md) · [Background tasks](../platform/tasks.md)

---

## Relations & joins


Covara loads related data with **batch loading** to avoid N+1 queries: one query for the parents, then one query per relation using `IN (...)`. Relations are declared per resource and loaded via the `?include=` query parameter.

## Relation types

| Type | Description | Example |
|------|-------------|---------|
| `belongsTo` | Foreign key on **this** table | A post belongs to a user |
| `hasOne` | Foreign key on the **related** table (1:1) | A user has one profile |
| `hasMany` | Foreign key on the **related** table (1:N) | A user has many posts |
| `manyToMany` | Junction table | A post has many tags |

## Defining relations

```typescript
useResource(postsTable, {
  db,
  id: postsTable.id,
  relations: {
    author: {
      resource: "users",
      schema: usersTable,
      type: "belongsTo",
      foreignKey: postsTable.authorId,
      references: usersTable.id,
      defaultSelect: [usersTable.id, usersTable.name, usersTable.avatar], // limit fields returned (columns of the related table)
    },
    comments: {
      resource: "comments",
      schema: commentsTable,
      type: "hasMany",
      foreignKey: commentsTable.postId,
      references: postsTable.id,
    },
    tags: {
      resource: "tags",
      schema: tagsTable,
      type: "manyToMany",
      foreignKey: postsTable.id,
      references: tagsTable.id,
      through: {
        schema: postTagsTable,
        sourceKey: postTagsTable.postId,
        targetKey: postTagsTable.tagId,
      },
    },
  },
});
```

### Relation config

```typescript
interface RelationConfig {
  resource: string;            // resource name (used for nested loading)
  schema: Table;               // Drizzle table
  type: "belongsTo" | "hasOne" | "hasMany" | "manyToMany";
  foreignKey: AnyColumn;
  references: AnyColumn;
  through?: { schema: Table; sourceKey: AnyColumn; targetKey: AnyColumn }; // manyToMany only
  strategy?: "eager" | "lazy"; // eager auto-loads on list/get; default lazy
  defaultSelect?: string[];
  filterable?: boolean;        // allow filtering parents by this relation
  subscribeToChanges?: boolean;// include in subscription events
}
```

## Auto-discovery

Set `autoRelations: true` to derive relations from your Drizzle foreign keys instead of declaring them by hand:

```typescript
useResource(postsTable, { db, id: postsTable.id, autoRelations: true });
```

- **`belongsTo`** is discovered from this table's own single-column FKs — `posts.authorId → users.id` becomes a relation named `author` (the FK column name with a trailing `Id`/`_id` stripped).
- **`hasMany`** is discovered from other **registered resources** whose FKs reference this table — if `comments.postId → posts.id`, `posts` gains a relation named after the referencing table (`comments`).
- Only single-column FKs to registered resources are discovered — no guessing. `manyToMany`, custom names, eager strategy, and `defaultSelect` must be declared explicitly.
- **Explicit `relations` always win** over a discovered relation of the same name, so you can enable `autoRelations` and still override or add specific ones.
- Discovered relations are **lazy** (loaded only via `?include=`) and run through the same scope-enforced loader as explicit relations (see [Scope enforcement](#scope-enforcement)).

## Including relations

```bash
GET /api/posts?include=author                              # single
GET /api/posts?include=author,category,tags                # multiple
GET /api/posts?include=author.profile                      # nested
GET /api/posts?include=comments(limit:5;select:id,text)    # with options
```

### Include options

| Option | Description | Example |
|--------|-------------|---------|
| `limit` | Max items **per parent** (`hasMany`/`manyToMany`) | `comments(limit:10)` |
| `offset` | Skip items per parent | `comments(limit:10;offset:10)` |
| `select` | Fields to include | `author(select:id,name)` |
| `filter` | [RSQL filter](./filtering.md) on related rows | `comments(filter:status=="approved")` |

`limit`/`offset` apply **per parent row**, so each parent gets its own page of children. The `filter` is combined with the relation's join condition.

## Scope enforcement

Included relations honor the **target resource's `read` [auth scope](../auth/scopes.md)** for the requesting user — a relation can never reveal rows the user could not read by querying that resource directly. For each included relation, the target resource's read scope is resolved for the effective user (including an [impersonated](../tooling/admin-ui.md) one) and AND-ed into the relation query: rows outside the user's scope are filtered out (`belongsTo`/`hasOne` becomes `null`; `hasMany`/`manyToMany` omits them), and a user denied read on the target resource gets nothing. This applies identically to explicit and [auto-discovered](#auto-discovery) relations.

Relations to tables that are **not** registered as resources have no scope to enforce — only expose such relations to data you intend to be readable through the parent.

> **Subscriptions:** relations embedded in [subscription](../realtime/subscriptions.md) events **are** scope-filtered per subscriber — the target resource's `read` scope is resolved for each subscriber's user (captured at subscribe time) and applied to the embedded relation, exactly as on the read path. A relation in a subscription event can never reveal rows that subscriber couldn't read directly. (Relations are loaded per subscriber rather than shared across them, so the cost scales with subscriber count; loads are deduplicated per subscriber within a single push.)

### Eager relations

A relation with `strategy: "eager"` loads automatically on `GET /` and `GET /:id` without `?include=`. If the client also requests it explicitly, the explicit spec (filter/limit/offset/select/nested) wins.

```typescript
relations: {
  author: { /* ... */ strategy: "eager" },
}
```

### Include limits

```typescript
useResource(postsTable, {
  db,
  id: postsTable.id,
  relations: { /* ... */ },
  include: {
    maxDepth: 3,              // max nesting depth (default 3)
    defaultLimit: 100,        // default per-parent limit for hasMany
    allowNestedFilters: true, // allow filters on nested relations
  },
});
```

## Filtering parents by relation

```bash
GET /api/posts?filter=tags.name=="TypeScript"
GET /api/posts?filter=author.organizationId=="org-123"
```

This requires `filterable: true` on the relation and may use subqueries — index accordingly on large tables.

## Relations in subscriptions

Includes work with [subscriptions](../realtime/subscriptions.md): related data is attached to `added`/`changed` events.

```typescript
posts.subscribe(
  { filter: 'status=="published"', include: "author,tags" },
  {
    onAdded: (post) => console.log("New post by", post.author.name),
    onChanged: (post) => { /* related data included */ },
  }
);
```

## Nested write-through

With [`nestedWrites: true`](./nested-writes.md), a `POST` body can embed related objects to create them atomically. See **[Nested writes](./nested-writes.md)** for the full transaction order and limitations (`manyToMany` is not supported for nested writes).

## TypeScript

```typescript
import type { RelationType, RelationConfig, IncludeSpec } from "covara";
```

The [typed client](../client/typegen.md) infers included relations into the result type — `posts.include("author", "tags")` returns rows with typed `author` and `tags`.

## Related

- [Nested writes](./nested-writes.md) · [Filtering](./filtering.md) · [Subscriptions](../realtime/subscriptions.md)
- [Client queries](../client/queries.md) — the fluent `.include()` builder

---

## Resources & the app factory


A **resource** is the core of Covara. Each resource maps to a Drizzle table and generates a complete Hono router: CRUD, batch operations, count, aggregations, subscriptions, search, and RPC. You create resources either with the `createCovara` factory or directly with `useResource`.

## `createCovara`

`createCovara(options)` returns a `CovaraApp` (which `extends Hono`) pre-wired with RFC 7807 [error handling](../tooling/error-handling.md), [security headers](../auth/security-headers.md), health endpoints, [OpenAPI](../tooling/openapi.md), and an optional [admin UI](../tooling/admin-ui.md). Resources are added with the chainable `.resource()`.

```typescript
import { createCovara } from "covara";

const app = createCovara({
  basePath: "/api",            // resource mount prefix (default: "/api")
  cors: true,                  // true | false | hono/cors options
  auth: { router, middleware },// the object returned by useAuth()
  middleware: [],              // extra Hono MiddlewareHandler[] applied to all routes
  observability: true,         // request/subscription metrics (or { metrics })
  health: true,                // /healthz + /readyz (default: true)
  adminUI: false,              // admin dashboard at /__covara/ui (default: false)
  openapi: true,               // OpenAPI document at /__covara (default: true)
})
  .resource(usersTable, { id: usersTable.id, db })             // → /api/users
  .resource("/people", usersTable, { id: usersTable.id, db }); // → /api/people
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `basePath` | `string` | `"/api"` | Prefix every resource is mounted under. |
| `cors` | `boolean \| CorsOptions` | `false` | Enable CORS, or pass a [hono/cors](https://hono.dev/docs/middleware/builtin/cors) config. |
| `auth` | `{ router, middleware }` | — | Result of [`useAuth`](../auth/overview.md); mounts auth routes and populates `c.get("user")`. |
| `middleware` | `MiddlewareHandler[]` | `[]` | Extra middleware applied before resources. |
| `observability` | `boolean \| { metrics }` | `false` | Collect request/subscription [metrics](../tooling/middleware.md). |
| `health` | `boolean \| HealthOptions` | `true` | Mount [`/healthz` and `/readyz`](../platform/health.md). |
| `adminUI` | `boolean \| AdminUIOptions` | `false` | Mount the [admin dashboard](../tooling/admin-ui.md). |
| `openapi` | `boolean \| OpenAPIOptions` | `true` | Serve the [OpenAPI spec](../tooling/openapi.md). |

The mount path is inferred from the table name unless you pass an explicit path as the first argument to `.resource()`.

### Serving the app

- **Node:** `await startServer(app, { port })` from `covara/node` — see [Node deployment](../deployment/node.md).
- **Cloudflare Workers:** `export default app` (or `app.fetch`) — see [Workers deployment](../deployment/workers.md).

## `useResource`

`useResource(table, config)` returns a plain `Hono` router. Use it when you want to compose routing yourself:

```typescript
import { Hono } from "hono";
import { useResource, errorHandler, notFoundHandler } from "covara";

const app = new Hono();
app.onError(errorHandler);
app.notFound(notFoundHandler);
app.route("/api/posts", useResource(postsTable, { id: postsTable.id, db }));
```

`createCovara().resource()` is a thin wrapper over `useResource` that also registers the resource for OpenAPI, the admin UI, and cross-resource subscriptions.

## Configuration reference

### `id` (required)

The primary key column.

```typescript
{ id: postsTable.id }
```

### `db` (required)

The Drizzle database instance. Wrap it with [`trackMutations`](../realtime/mutation-tracking.md) if you want custom routes/procedures to feed subscriptions automatically.

```typescript
{ db }
```

### `auth`

Authorization scopes per operation. Each scope is a function of the current user returning an [RSQL](../auth/scopes.md) filter that is `AND`-combined with the request filter. See [Authorization scopes](../auth/scopes.md).

```typescript
{
  auth: {
    public: { read: true, subscribe: true }, // allow anonymous read/subscribe
    read: async (user) => rsql`*`,
    create: async (user) => (user ? rsql`*` : rsql``),
    update: async (user) => rsql`userId==${user.id}`,
    delete: async (user) => rsql`userId==${user.id}`,
    subscribe: async (user) => rsql`userId==${user.id}`,
  },
}
```

A scope function's return value decides **which rows** the operation may touch: `` rsql`*` `` allows everything, `` rsql`userId==${user.id}` `` restricts to matching rows (AND-combined with the request `?filter=`), and `` rsql`` `` (empty) denies entirely. Omit a scope to deny that operation for everyone except where `public` grants it.

#### `public` vs a scope returning `` rsql`*` ``

These look similar but act at different stages — `public` controls **who** (authenticated or not), while a scope function controls **which rows** an already-authenticated user sees:

- **`public`** is checked **first** and bypasses the auth requirement, so an **anonymous** request is allowed and resolves to all rows. Only `read` and `subscribe` can be made public (`public: true` is shorthand for both) — you cannot open `create`/`update`/`delete` this way.
- **A scope function returning `` rsql`*` ``** is only reached **after** the user check. An anonymous request gets a `401` (the function never runs); an authenticated user gets all rows. It means "any logged-in user can read everything, but you must be logged in."

| Config | Anonymous | Authenticated |
|--------|-----------|---------------|
| `public: { read: true }` | ✅ all rows | ✅ all rows |
| scope `read` returns `*` | ❌ `401` | ✅ all rows |
| both together | ✅ all rows | ✅ all rows |
| neither (omitted) | ❌ `401` | ❌ `403` |

For the common "public reads, owner-only writes" pattern you need **both** — set `public.read` *and* owner-scoped `create`/`update`/`delete` functions (this is exactly `scopePatterns.publicReadOwnerWrite`). See [Authorization scopes](../auth/scopes.md).

### `capabilities`

Enable/disable whole operations. All default to `true`. Reading, filtering, and sorting are always enabled.

```typescript
{
  capabilities: {
    enableCreate: true,
    enableUpdate: true,       // governs PATCH and PUT
    enableDelete: true,
    enableBatch: true,        // governs all /batch routes incl. /batch/upsert
    enableAggregations: true,
    enableSubscribe: true,
  },
}
```

### `fields`

Field-level policies. See [Fields: masking, writable, computed](./fields.md) for full behavior and security guarantees. Every column-name option below takes the **Drizzle column** (like `id`); string column names also work but are deprecated.

```typescript
{
  fields: {
    readable: [users.id, users.name, users.email, users.createdAt], // allowlist; everything else stripped from responses
    writable: [users.name, users.email],                            // enforced allowlist for create/update (mass-assignment protection)
    filterable: [users.name, users.email, users.createdAt],         // columns allowed in ?filter=
    sortable: [users.name, users.createdAt],                        // columns allowed in ?orderBy=
  },
}
```

### `generatedFields`

Columns the server fills in (id, timestamps, ownership). They are exempt from `fields.writable` stripping (a hook can set them) and may be omitted from inbound bodies even with `strictInput`.

```typescript
{ generatedFields: [users.id, users.userId, users.createdAt, users.updatedAt] }
```

### `strictInput`

By default unknown fields in a body are ignored. Set `strictInput: true` to reject them with a `422` (Zod strict mode).

```typescript
{ strictInput: true }
```

### `computed`

Virtual fields added to every response and subscription event, computed from the **full** (unmasked) row and never persisted. See [Fields](./fields.md#computed-fields).

```typescript
{
  computed: {
    fullName: (row) => `${row.firstName} ${row.lastName}`,
    isOverdue: (row) => row.dueAt != null && Date.parse(row.dueAt) < Date.now(),
  },
}
```

### `pagination`

```typescript
{ pagination: { defaultLimit: 20, maxLimit: 100 } }
```

See [Pagination](./pagination.md).

### `batch`

```typescript
{ batch: { create: 50, update: 50, replace: 50, delete: 10 } }
```

See [Batch operations](./batch.md).

### `etag`

Optimistic concurrency control. See [Optimistic locking](./optimistic-locking.md).

```typescript
{ etag: { versionField: posts.version } } // or { updatedAtField: posts.updatedAt }
```

### `softDelete`

Mark rows deleted instead of removing them. See [Soft delete](./soft-delete.md).

```typescript
{ softDelete: { field: posts.deletedAt } }
```

### `relations`

Declare `belongsTo` / `hasOne` / `hasMany` / `manyToMany` relations loadable via `?include=`. See [Relations](./relations.md).

### `nestedWrites`

Enable write-through of embedded relation objects in `POST` bodies (requires `relations`). See [Nested writes](./nested-writes.md).

```typescript
{ nestedWrites: true }
```

### `search`

Register searchable fields for the `GET /search` endpoint. See [Search](./search.md).

```typescript
{ search: { enabled: true, fields: { title: { weight: 2 }, body: {} } } }
```

### `rateLimit`

Per-resource rate limiting. See [Middleware](../tooling/middleware.md#rate-limiting).

```typescript
{ rateLimit: { windowMs: 60_000, maxRequests: 100 } }
```

### `customOperators`

Add filter operators. See [Filtering → Custom operators](./filtering.md#custom-operators).

### `hooks`

Lifecycle hooks around every mutation. See [Procedures & hooks](./procedures.md).

```typescript
{
  hooks: {
    onBeforeCreate: async (ctx, data) => ({ ...data, createdAt: new Date() }),
    onAfterCreate: async (ctx, created) => {},
    onBeforeUpdate: async (ctx, id, data) => ({ ...data, updatedAt: new Date() }),
    onAfterUpdate: async (ctx, updated) => {},
    onBeforeDelete: async (ctx, id) => {},
    onAfterDelete: async (ctx, deleted) => {},
  },
}
```

### `procedures`

Custom Zod-validated RPC endpoints at `POST /rpc/:name`. See [Procedures](./procedures.md#rpc-procedures).

## Generated endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | [List](./crud.md) with pagination, filtering, ordering, projections |
| `GET` | `/:id` | Get one |
| `POST` | `/` | Create |
| `PATCH` | `/:id` | Partial update |
| `PUT` | `/:id` | Full replace |
| `DELETE` | `/:id` | Delete (or soft delete) |
| `GET` | `/count` | [Count](./crud.md#counting) |
| `GET` | `/aggregate` | [Aggregations](./aggregations.md) |
| `GET` | `/aggregate/subscribe` | [Live aggregation](../realtime/aggregate-subscriptions.md) |
| `GET` | `/subscribe` | [SSE subscription](../realtime/subscriptions.md) |
| `GET` | `/search` | [Full-text search](./search.md) (when configured) |
| `POST` | `/batch` | [Batch create](./batch.md) |
| `PATCH` | `/batch` | Batch update |
| `DELETE` | `/batch` | Batch delete |
| `POST` | `/batch/upsert` | [Bulk insert-or-update](./batch.md#bulk-upsert) |
| `POST` | `/rpc/:name` | [RPC procedures](./procedures.md) |

## Query parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `filter` | [Filter expression](./filtering.md) | `status=="active"` |
| `select` | Field projection | `id,name,email` |
| `include` | [Load relations](./relations.md) | `category,tags(limit:5)` |
| `cursor` | [Pagination cursor](./pagination.md) | `eyJpZCI6MTB9` |
| `limit` | Page size | `20` |
| `orderBy` | Sort order | `name:asc,age:desc` |
| `totalCount` | Include total count | `true` |
| `having` | Filter aggregate groups (`/aggregate`) | `count>=5;sum_total>100` |
| `withDeleted` | Include [soft-deleted](./soft-delete.md) rows | `true` |

## Related

- [CRUD endpoints](./crud.md) · [Filtering](./filtering.md) · [Pagination](./pagination.md) · [Aggregations](./aggregations.md)
- [Relations](./relations.md) · [Procedures & hooks](./procedures.md) · [Mutation tracking](../realtime/mutation-tracking.md)
- [Authorization scopes](../auth/scopes.md) · [Secure queries](../auth/secure-queries.md)

---

## RSQL


RSQL is the single expression language Covara uses everywhere it needs a predicate: the `?filter=` [query parameter](#as-a-query-filter), [authorization scopes](#in-authorization-scopes), subscription matching, aggregations, and batch operations. One string is compiled to **Drizzle SQL** for the database *and* executed **in-memory** for live subscription matching, so a filter behaves identically as a query and as a subscription.

```bash
GET /api/users?filter=status=="active";age>18
```

```typescript
// the same predicate, built safely in TypeScript:
rsql`status==${"active"};age>${18}`
```

This page is the full reference: the [language](#the-language), the [operators](#operator-reference), the [TypeScript builder](#building-rsql-in-typescript), and its two uses — [query filters](#as-a-query-filter) and [scopes](#in-authorization-scopes).

## The language

### Comparison

```
field==value        field!=value
field>value         field>=value
field<value         field<=value
```

Symbolic and named operators are equivalent:

| Symbolic | Named | Meaning |
|----------|-------|---------|
| `>` | `=gt=` | greater than |
| `>=` | `=ge=` | greater than or equal |
| `<` | `=lt=` | less than |
| `<=` | `=le=` | less than or equal |

### Combinators & grouping

| Combinator | Meaning | Forms |
|------------|---------|-------|
| AND | both hold | `;` · `&&` · `and` |
| OR | either holds | `,` · `\|\|` · `or` |
| Group | precedence | `( … )` |

```
status=="active";age>18
role=="admin",role=="moderator"
(status=="active";age>18),(role=="admin")
```

### Sets, ranges, strings, null, booleans

```
field=in=(a,b,c)        field=out=(a,b,c)        # set membership
field=between=[18,65]   field=nbetween=[0,17]    # range (inclusive); [..] or (..)
field%="pat"  field!%="pat"  field=ilike="pat"   # LIKE / NOT LIKE / case-insensitive
field=contains="t"  field=startswith="t"  field=endswith="t"   # (+ i-prefixed variants)
field=regex="^a"  field=iregex="^a"             # regex (in-memory uses JS RegExp)
field=length=N  field=minlength=N  field=maxlength=N
field=isnull=true   field=isempty=true          # null / null-or-empty checks
field==true   field==false                      # matches true/1/"true" and false/0/"false"
```

`%` matches any sequence, `_` a single character. ISO-8601 date strings are auto-detected and parsed (`createdAt>"2024-01-15"`).

### Value types & escaping

```
name=="John Doe"             # strings (quoted)
age==25   price==19.99       # numbers (unquoted)
active==true                 # booleans
deletedAt==null              # null
tags=in=("tech","news")      # sets
name=="John \"Johnny\" Doe"  # escape quotes inside strings
path=="C:\\Users\\John"      # escape backslashes
```

When you build RSQL in code, the [builder](#building-rsql-in-typescript) handles all of this escaping for you.

## Operator reference

| Operator | Description | Example |
|----------|-------------|---------|
| `==` | Equals | `status=="active"` |
| `!=` | Not equals | `status!="deleted"` |
| `>`, `=gt=` | Greater than | `age>18` |
| `>=`, `=ge=` | Greater than or equal | `age>=18` |
| `<`, `=lt=` | Less than | `age<65` |
| `<=`, `=le=` | Less than or equal | `age<=65` |
| `=in=` | In list | `role=in=("a","b")` |
| `=out=` | Not in list | `role=out=("x","y")` |
| `%=` | LIKE | `name%="%john%"` |
| `!%=` | NOT LIKE | `name!%="%test%"` |
| `=ilike=` | Case-insensitive LIKE | `name=ilike="%john%"` |
| `=nilike=` | Case-insensitive NOT LIKE | `name=nilike="%test%"` |
| `=contains=` | Contains substring | `name=contains="john"` |
| `=icontains=` | Case-insensitive contains | `name=icontains="john"` |
| `=startswith=` | Starts with | `name=startswith="Dr."` |
| `=istartswith=` | Case-insensitive starts with | `name=istartswith="dr."` |
| `=endswith=` | Ends with | `email=endswith=".com"` |
| `=iendswith=` | Case-insensitive ends with | `email=iendswith=".COM"` |
| `=ieq=` | Case-insensitive equals | `status=ieq="ACTIVE"` |
| `=ine=` | Case-insensitive not equals | `status=ine="deleted"` |
| `=isnull=` | Is null | `deletedAt=isnull=true` |
| `=isempty=` | Null or empty string | `bio=isempty=true` |
| `=between=` | In range (inclusive) | `age=between=[18,65]` |
| `=nbetween=` | Not in range | `age=nbetween=[0,17]` |
| `=regex=` | Regex match | `email=regex="^admin@"` |
| `=iregex=` | Case-insensitive regex | `name=iregex="^john"` |
| `=length=` | Exact string length | `code=length=6` |
| `=minlength=` | Minimum string length | `password=minlength=8` |
| `=maxlength=` | Maximum string length | `username=maxlength=20` |

## Building RSQL in TypeScript

Instead of concatenating strings, build expressions with the `rsql` tag and helpers (exported from `covara` and `covara/auth`). Every value is **escaped**, so dynamic input can't break out of the expression or inject operators. Each builder returns a `CompiledScope`.

### The `rsql` tag

Static text is the expression; interpolated values are escaped by type.

```typescript
import { rsql } from "covara";

rsql`authorId==${user.id}`;            // authorId=="user-123"
rsql`age=ge=${18};role=in=${roles}`;   // age=ge=18;role=in=("admin","user")
rsql`name=contains=${query}`;          // any operator works — it's the full language
```

| Interpolated value | Becomes |
|--------------------|---------|
| string | quoted, with `"` `'` `\` escaped |
| number / boolean | raw |
| `Date` | quoted ISO 8601 |
| array | parenthesized list — `("a","b")` |
| `null` / `undefined` | `null` |
| `CompiledScope` | parenthesized sub-expression — see [composition](#composing-expressions) |

:::warning Values are escaped; field names and operators are not
Only interpolated **values** are escaped. The static template text — field names and operators — is trusted code. Never build a template's field names/operators from untrusted input.
:::

### Comparison helpers

For computed fields/operators, the helpers read better than a template:

| Helper | Emits | | Helper | Emits |
|--------|-------|---|--------|-------|
| `eq(f, v)` | `f==v` | | `inList(f, vs)` | `f=in=(…)` |
| `ne(f, v)` | `f!=v` | | `notIn(f, vs)` | `f=out=(…)` |
| `gt` / `gte` | `f=gt=v` / `f=ge=v` | | `like(f, p)` | `f%=p` |
| `lt` / `lte` | `f=lt=v` / `f=le=v` | | `notLike(f, p)` | `f!%=p` |
| `isNull(f)` | `f=isnull=true` | | `isNotNull(f)` | `f=isnull=false` |

```typescript
import { eq, gte, inList, like } from "covara";

eq("status", "active");              // status=="active"
inList("role", ["admin", "editor"]); // role=in=("admin","editor")
like("email", "%@acme.com");         // email%="%@acme.com"
```

:::note No `NOT` combinator
The grammar has no `NOT`, so there's no `not()` helper — use the negated operators: `ne`, `notIn`, `notLike`, `isNotNull`.
:::

### Combinators

```typescript
import { and, or, eq, gt } from "covara";

and(eq("status", "active"), gt("age", 18));   // (status=="active");(age=gt=18)
or(eq("role", "admin"), eq("role", "owner")); // (role=="admin"),(role=="owner")

eq("status", "active").and(gt("age", 18));    // fluent form on any CompiledScope
```

`and`/`or` **drop empty scopes**, so conditional pieces compose cleanly:

```typescript
and(eq("orgId", orgId), isAdmin ? emptyScope() : eq("ownerId", userId));
// admins → orgId=="…"; everyone else → (orgId=="…");(ownerId=="…")
```

### Composing expressions

A `CompiledScope` interpolated into a template embeds as a **parenthesized sub-expression** (not a quoted string), so expressions compose — including nested `rsql` calls:

```typescript
const mine = eq("authorId", user.id);
rsql`published==${true};${mine}`;                       // published==true;(authorId=="user-123")
rsql`status==${"active"};${rsql`tier=in=${["pro"]}`}`;  // status=="active";(tier=in=("pro"))
```

`` rsql`${a};${b}` `` is exactly `and(a, b)`.

:::tip Empty scopes in templates
`and`/`or` skip empties, but a raw template can't — `` rsql`a==1;${emptyScope()}` `` yields the dangling `a==1;()`. Use the combinators when a piece may be empty.
:::

### Special expressions

| Builder | Expression | Meaning |
|---------|-----------|---------|
| `allScope()` | `*` | match everything (no restriction) |
| `emptyScope()` | *(empty)* | match nothing (deny) |

### Utilities & the `CompiledScope` type

```typescript
import { scopeFromString, isCompiledScope } from "covara";

scopeFromString('status=="active"'); // wrap a raw RSQL string
isCompiledScope(value);              // runtime type guard
```

```typescript
interface CompiledScope {
  toString(): string;   // the RSQL expression
  isEmpty(): boolean;
  and(other: CompiledScope): CompiledScope;
  or(other: CompiledScope): CompiledScope;
}
```

## As a query filter

The most common use: filtering reads. Send a filter string on any list/count/aggregate/search endpoint; subscriptions apply it to the live stream too.

**HTTP**

```bash
GET /api/users?filter=status=="active";age>18
```

**Client** — pass a string, or build it with the [query builder](../client/queries.md) (which escapes for you):

```typescript
import { rsql } from "covara";

client.resources.users.filter('status=="active";age>18').list();
client.resources.users.filter(rsql`status==${status};age>${minAge}`).list();

useLiveList("/api/users", { filter: 'status=="active"' }); // React
```

Restrict which columns may be filtered with [`fields.filterable`](./fields.md) — a filter on a non-allowed column returns `400 FilterParseError`.

## In authorization scopes

A [scope](../auth/scopes.md) is just an RSQL expression returned per operation; the framework combines it with the request filter so a user can only ever see/act on rows their scope allows. Build scopes with the same `rsql` tag and helpers:

```typescript
useResource(posts, {
  db, id: posts.id,
  auth: {
    read: async (user) =>
      user?.role === "admin" ? allScope() : rsql`authorId==${user?.id};published==${true}`,
    update: async (user) => (user ? eq("authorId", user.id) : emptyScope()),
  },
});
```

`combineScopes(scope, filter?)` merges a scope with an incoming `?filter=` (the basis of [secure queries](../auth/secure-queries.md)) — `*` adds no restriction, an empty scope denies:

```typescript
import { combineScopes } from "covara";
combineScopes(eq("ownerId", user.id), 'status=="archived"');
// (ownerId=="user-123");(status=="archived")
```

See [Authorization scopes](../auth/scopes.md) for how scopes are resolved and enforced (including the higher-level [`scopePatterns`](../auth/scopes.md#scope-patterns)).

## Custom operators

Define operators with a SQL `convert` (for queries) and a JS `execute` (for subscription matching) so query and live behavior stay consistent.

```typescript
import { sql } from "drizzle-orm";

useResource(usersTable, {
  id: usersTable.id,
  db,
  customOperators: {
    "=jsoncontains=": {
      convert: (lhs, rhs) => sql`JSON_CONTAINS(${lhs}, ${rhs})`,
      execute: (lhs, rhs) => JSON.parse(String(lhs)).includes(rhs),
    },
  },
});
```

```bash
GET /api/users?filter=permissions=jsoncontains="write"
```

## Best practices

- **Always interpolate dynamic values** through the `rsql` tag or helpers — never string-concatenate user input. Escaping is what makes filters and scopes injection-safe.
- **Template for readability, helpers for dynamics** — `` rsql`ownerId==${id}` `` for fixed shapes; `eq`/`and`/`or` when fields/operators/membership are computed.
- **`allScope()` / `emptyScope()` for the extremes** — grant unrestricted access or deny, instead of inventing always-true/false expressions.
- **Keep query and subscription behavior identical** — when adding a custom operator, always provide both `convert` and `execute`.

## Related

- [Filtering](./filtering.md) — applying filters to query endpoints
- [Authorization scopes](../auth/scopes.md) · [Secure queries](../auth/secure-queries.md)
- [Fields](./fields.md) — `filterable`/`sortable` allowlists · [Subscriptions](../realtime/subscriptions.md)

---

## Full-text search


When a search adapter is registered, every resource gains a `GET /search` endpoint. By default all fields are searchable with zero configuration, and documents are auto-indexed on create/update/delete.

## Choosing an adapter

| Adapter | Factory | Best for |
|---------|---------|----------|
| **SQLite FTS5** | `createSqliteFtsAdapter` | Most apps on SQLite/libsql/D1 — no extra service |
| **Postgres `tsvector`** | `createPostgresFtsAdapter` | Apps on PostgreSQL — no extra service |
| **OpenSearch / Elasticsearch** | `createOpenSearchAdapter` | Large-scale / advanced relevance |
| **In-memory** | `createMemorySearchAdapter` | Development & tests |

Register one globally with `setGlobalSearch`. The database-backed FTS adapters are the recommended default — search works against your primary database with no extra infrastructure.

```typescript
import { setGlobalSearch } from "covara";
import { createSqliteFtsAdapter, createPostgresFtsAdapter } from "covara/search";

// SQLite (libsql / better-sqlite3 / D1) — FTS5 virtual tables
setGlobalSearch(createSqliteFtsAdapter({
  db,                          // your Drizzle db (a runner with run()/all())
  tablePrefix: "covara_fts_",  // optional
  columns: ["title", "body"],  // optional; defaults to all string fields
}));

// PostgreSQL — tsvector / to_tsquery
setGlobalSearch(createPostgresFtsAdapter({
  db,                  // a runner with execute()
  language: "english", // optional
  tablePrefix: "covara_fts_",
}));
```

Both FTS adapters create and manage their own backing tables lazily on first index, implement the full `SearchAdapter` interface, validate identifiers against injection, and flatten nested object/array values to text.

### OpenSearch

```typescript
import { setGlobalSearch, createOpenSearchAdapter } from "covara";

setGlobalSearch(createOpenSearchAdapter({
  node: "http://localhost:9200",         // or string[]
  auth: { username: "admin", password: "admin" },
  ssl: { rejectUnauthorized: false },
  indexPrefix: "myapp_",                  // default "covara_"
}));
```

Uses `multi_match` (`best_fields`), `AUTO` fuzziness, field boosting, and refreshes after each write.

### In-memory

```typescript
import { setGlobalSearch, createMemorySearchAdapter } from "covara";
setGlobalSearch(createMemorySearchAdapter()); // case-insensitive substring, not persisted
```

## The search endpoint

```bash
GET /api/todos/search?q=important&filter=completed==false&limit=10&offset=0&highlight=true
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| `q` | Search query (required) | — |
| `filter` | [RSQL filter](./filtering.md) applied after the query | — |
| `limit` | Max results | 20 |
| `offset` | Results to skip | 0 |
| `highlight` | Include highlighted matches | false |

```json
{
  "items": [{ "id": 1, "title": "Important Task", "status": "active" }],
  "total": 15,
  "highlights": { "1": { "title": ["Important Task"] } }
}
```

Search results are subject to the same [auth scopes](../auth/scopes.md) and [field masking](./fields.md) as regular reads.

## Resource configuration

```typescript
useResource(todos, {
  db,
  id: todos.id,
  search: {
    enabled: true,                 // default true when an adapter is registered
    indexName: "custom_index",     // default: table name
    fields: {
      title: { weight: 2.0 },      // boost
      description: { weight: 1.0 },
      internalNotes: { searchable: false }, // exclude
    },
    autoIndex: true,               // index on create/update/delete (default true)
    outbox: false,                 // durable index queue (see below)
    onIndexError: (info) => { /* observe inline index failures */ },
  },
});
```

`fields` also accepts a plain array — `fields: [posts.title, posts.description]` — to restrict searchable columns without weights. Array entries take the Drizzle column (preferred) or a column-name string (deprecated). The record/weights form is keyed by column name.

## Transactional outbox (at-least-once indexing)

By default, indexing runs inline after a mutation commits with one immediate retry. If the search backend is down, the op is dropped (the DB write still succeeds), leaving the index stale until the row is touched again.

Enable `outbox: true` for at-least-once DB → index convergence. Index/delete ops are written to a durable [KV](../platform/kv.md)-backed queue at mutation time and drained in the background with exponential backoff; exhausted ops are parked in a dead set, not lost.

```typescript
useResource(todos, { db, id: todos.id, search: { outbox: true } });
```

- Requires a global KV (`setGlobalKV(...)`); without one, `outbox` has no effect.
- **On Node**, enabling `outbox` starts a background drainer (a `.unref()`'d `setInterval`, default every 2s, up to 100 ops/tick).
- Retries use exponential backoff `base * 2^attempts` capped at 5 min (default base 1s, 10 attempts), then move to the dead set.
- **On Cloudflare Workers** there is no long-lived process — drain it yourself from a scheduled handler or queue consumer:

```typescript
import { drainSearchOutbox } from "covara";

export default {
  fetch: app.fetch,
  async scheduled(event, env, ctx) {
    ctx.waitUntil(drainSearchOutbox());
  },
};
```

### Outbox API

```typescript
import {
  enqueueSearchOp, drainSearchOutbox, startSearchOutboxDrainer, getSearchOutboxStats,
} from "covara";

await enqueueSearchOp({ index: "todos", type: "index", docId: "1", document: { id: 1, title: "Hi" } });
const result = await drainSearchOutbox({ maxAttempts: 10, backoffBaseMs: 1000, batchSize: 100 });
const stop = startSearchOutboxDrainer({ intervalMs: 2000 }); // Node
const { pending, dead } = await getSearchOutboxStats();
```

See the [search contract](../contracts/search.md) for the indexing guarantees.

## Manual index management

```typescript
import { getGlobalSearch, hasGlobalSearch } from "covara";

const search = getGlobalSearch();
await search.index("todos", "123", { id: 123, title: "Important Task" });
await search.delete("todos", "123");
const results = await search.search("todos", {
  query: "important", fields: ["title"], fieldWeights: { title: 2 }, from: 0, size: 20, highlight: true,
});
await search.createIndex("todos", { properties: { title: { type: "text" }, status: { type: "keyword" } } });
```

Global helpers: `setGlobalSearch`, `getGlobalSearch`, `hasGlobalSearch`, `clearGlobalSearch`.

## Client

```tsx
import { useSearch } from "covara/client/react";

const { items, isSearching, search, clear } = useSearch(client.resources.todos, { enabled: true });
search("important"); // debounced query
```

See [React hooks](../client/react-hooks.md).

## Related

- [Filtering](./filtering.md) · [KV store](../platform/kv.md) · [Search contract](../contracts/search.md)
- [Workers deployment](../deployment/workers.md) — draining the outbox on the edge

---

## Soft delete


Soft delete marks rows as deleted by setting a column, instead of removing them from the table. Reads hide soft-deleted rows by default; pass `?withDeleted=true` to include them.

## Configuration

```typescript
useResource(postsTable, {
  id: postsTable.id,
  db,
  softDelete: {
    field: postsTable.deletedAt,   // column used as the deletion marker
    // deletedValue: () => Date.now(), // optional; defaults to current ISO timestamp
  },
});
```

A row is considered deleted when the `field` column is **non-null**. Pass the **Drizzle column** (like `id`); a string column name also works but is deprecated.

## Behavior

- `DELETE /:id` **sets the marker column** instead of removing the row, and still returns `204`.
- Subscribers receive a **`removed`** event, because the row leaves the (not-deleted) read scope.
- `GET /`, `GET /:id`, `GET /count`, `GET /aggregate`, and subscription snapshots **exclude** soft-deleted rows.
- Pass `?withDeleted=true` to include soft-deleted rows in any of those reads.
- Re-deleting an already soft-deleted row returns `404` — it is invisible to the delete scope.

```bash
DELETE /api/posts/p1                 # sets deletedAt, returns 204
GET    /api/posts                    # p1 is hidden
GET    /api/posts?withDeleted=true   # p1 is included
```

## Custom marker values

Use `deletedValue` for non-timestamp columns. The column counts as "deleted" whenever it is non-null.

```typescript
softDelete: { field: postsTable.isDeleted, deletedValue: () => 1 }   // integer flag
softDelete: { field: postsTable.deletedAt, deletedValue: () => Date.now() } // numeric epoch
```

## Restoring

There is no dedicated restore endpoint — clear the marker with an update (the row must be reachable via `?withDeleted=true` and your update scope):

```bash
PATCH /api/posts/p1
{ "deletedAt": null }
```

## Related

- [CRUD endpoints](./crud.md) · [Subscriptions](../realtime/subscriptions.md) — soft delete emits `removed`
- [Resources](./resources-and-app.md#softdelete)

---

## Database matrix


Everything goes through [Drizzle ORM](https://orm.drizzle.team), so any Drizzle-supported driver works. Tested combinations:

| Database | Driver | Runtime | Notes |
|----------|--------|---------|-------|
| SQLite | `@libsql/client` (`drizzle-orm/libsql`) | Node | Local file or [Turso](https://turso.tech) |
| SQLite | `better-sqlite3` (`drizzle-orm/better-sqlite3`) | Node | Synchronous, fast local |
| SQLite | D1 (`drizzle-orm/d1`) | Workers | Native Cloudflare binding |
| PostgreSQL | `postgres` (`drizzle-orm/postgres-js`) | Node + Workers | Use [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) on Workers |
| PostgreSQL | `@neondatabase/serverless` (`drizzle-orm/neon-http`) | Node + Workers | HTTP driver, edge-friendly |
| PostgreSQL | `@electric-sql/pglite` (`drizzle-orm/pglite`) | Node | Embedded Postgres, great for tests |

## Examples

```typescript
// libsql (local file or Turso)
import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
const db = drizzle(createClient({ url: "file:./data.db" }));

// better-sqlite3
import Database from "better-sqlite3";
import { drizzle } from "drizzle-orm/better-sqlite3";
const db = drizzle(new Database("data.db"));

// D1 (Workers)
import { drizzle } from "drizzle-orm/d1";
const db = drizzle(env.DB);

// postgres-js
import postgres from "postgres";
import { drizzle } from "drizzle-orm/postgres-js";
const db = drizzle(postgres(env.DATABASE_URL));

// Neon (HTTP, edge-friendly)
import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
const db = drizzle(neon(env.DATABASE_URL));

// PGlite (embedded, tests)
import { PGlite } from "@electric-sql/pglite";
import { drizzle } from "drizzle-orm/pglite";
const db = drizzle(new PGlite());
```

Pass whichever `db` you build to `useResource`/`createCovara` — or wrap it with [`trackMutations`](../realtime/mutation-tracking.md) first if you have custom routes.

## Migrations

Covara doesn't impose a migration tool — use [`drizzle-kit`](https://orm.drizzle.team/kit-docs/overview):

```bash
npx drizzle-kit generate   # generate migration SQL from your schema
npx drizzle-kit push       # push schema directly (dev)
```

On D1, apply migrations via wrangler — see [Workers deployment](./workers.md).

## Internal tables (`covara/db`)

The auth subsystem persists state in four framework-owned tables. The `covara/db` subpath provides canonical schemas, an idempotent migrator, a generic seeder, and pool-sizing guidance.

| Table | Purpose | Used by |
|-------|---------|---------|
| `auth_sessions` | Server-side [sessions](../auth/sessions.md) | `DrizzleSessionStore` |
| `auth_accounts` | Linked OAuth/OIDC accounts | Auth.js / [federated](../auth/federated.md) adapters |
| `auth_api_keys` | Hashed [API keys](../auth/api-keys.md) | API-key credential flow |
| `auth_verification_tokens` | Email/magic-link/reset tokens | [Verification flows](../auth/account-security.md) |

Timestamps are stored as Unix-epoch integers on SQLite (`{ mode: "timestamp" }`) and as `TIMESTAMP` on Postgres.

Spread the dialect-appropriate tables into your Drizzle schema so drizzle-kit and queries see them:

```typescript
import { internalSchema } from "covara/db";

export const schema = {
  ...internalSchema("sqlite"), // or "postgresql"
  // ...your own tables
};
```

Individual tables are exported too (`authSessions`, `authAccounts`, `authApiKeys`, `authVerificationTokens` default to SQLite; `*Sqlite` / `*Pg` are explicit).

## Framework migrations

`migrateInternal(db, { dialect? })` runs `CREATE TABLE IF NOT EXISTS` (+ `CREATE INDEX IF NOT EXISTS`) for every internal table — idempotent and safe to call on every boot. `autoMigrate(db)` is the convenience wrapper; the dialect is inferred from the Drizzle db.

```typescript
import { autoMigrate } from "covara/db";
await autoMigrate(db); // run once at startup
```

DDL runs through the passed Drizzle db (`db.run` on libsql/D1, `db.execute` on postgres/pglite), so it's Workers-safe — no Node `fs` at runtime.

## Seeding

`seed(db, { tables })` / `createSeed()` performs insert-or-ignore (`ON CONFLICT DO NOTHING`), so dev/staging data applies deterministically and repeatably. It works with any Drizzle table.

```typescript
import { createSeed } from "covara/db";

await createSeed()
  .table(usersTable, [{ id: "1", email: "demo@example.com" }])
  .run(db);
```

## Connection pooling

Use `recommendedPoolConfig(driver)` for sane defaults; tune to your origin's connection limit.

| Driver | `max` | Notes |
|--------|-------|-------|
| `postgres-js` | 10 | Long-lived Node process; keep `max` below (DB limit ÷ instances). Use a pooler URL for serverless. |
| `neon` | 1 | Serverless HTTP driver is connectionless per request; use the `-pooler` endpoint. |
| `pglite` | 1 | Embedded single-connection engine; pooling N/A. |
| `libsql` | 1 | HTTP/WS client multiplexes over one connection. |
| `d1` | 1 | Request-scoped binding; avoid long transactions. |
| `hyperdrive` | 5 | Hyperdrive pools at the edge; keep the Worker-side `max` small. |

```typescript
import { recommendedPoolConfig } from "covara/db";
import postgres from "postgres";

const { max, idleTimeoutMs, connectTimeoutMs } = recommendedPoolConfig("postgres-js");
const client = postgres(url, { max, idle_timeout: idleTimeoutMs / 1000, connect_timeout: connectTimeoutMs / 1000 });
```

## Search indexes

The built-in [search](../core/search.md) adapters create their own backing tables — SQLite FTS5 or Postgres `tsvector` — so full-text search needs no extra service on either database.

## Related

- [Node deployment](./node.md) · [Cloudflare Workers](./workers.md) · [Search](../core/search.md)

---

## Durable Object KV


On Cloudflare Workers the in-memory [KV](../platform/kv.md) is per-isolate, and Cloudflare may run many isolates of your app at once. Without a shared KV:

- a mutation handled by one isolate never reaches [SSE subscribers](../realtime/subscriptions.md) connected to another,
- [rate limits](../tooling/middleware.md) and [sessions](../auth/sessions.md) aren't shared,
- the [task queue](../platform/tasks.md) can't coordinate.

The **Durable Object KV** gives you shared, strongly-consistent state on Workers without standing up Redis.

## Setup

```typescript
// src/worker.ts
import {
  createCovara, createDurableObjectKV, setGlobalKV, initializeEventSubscription,
  type CovaraApp, type DurableObjectNamespaceLike,
} from "covara";

export { CovaraKVDurableObject } from "covara";

interface Env { DB: D1Database; COVARA_KV: DurableObjectNamespaceLike }

let app: CovaraApp | undefined;
const buildApp = (env: Env): CovaraApp => {
  setGlobalKV(createDurableObjectKV(env.COVARA_KV));
  void initializeEventSubscription(); // cross-isolate subscription fan-out
  return createCovara().resource(/* ... */);
};

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    app ??= buildApp(env);
    return app.fetch(request, env, ctx);
  },
};
```

```toml
# wrangler.toml
[durable_objects]
bindings = [{ name = "COVARA_KV", class_name = "CovaraKVDurableObject" }]

[[migrations]]
tag = "v1"
new_sqlite_classes = ["CovaraKVDurableObject"]
```

You re-export `CovaraKVDurableObject` from your worker so wrangler can bind it. Projects from `npx covara create --template cloudflare` have all of this wired up.

## How it works

- **Strong consistency.** All KV operations (strings, hashes, sets, lists, sorted sets, TTLs, transactions) run inside a single, single-threaded Durable Object — operations are strongly consistent, and a `multi()` batch is atomic with respect to other requests.
- **No 128 KB cap.** Collections are stored **one entry per member** in Durable Object storage, so they aren't limited by the 128 KB single-value cap.
- **Hibernatable WebSocket pub/sub.** Each isolate holds one WebSocket to the Durable Object for its subscriptions; idle connections don't accrue Durable Object duration charges, and they reconnect automatically with backoff.
- **Zero Cloudflare imports.** It uses structural types, so the implementation is Node-testable.

## Factory forms

```typescript
// Direct (name selects which DO instance backs the store; default "covara-kv")
createDurableObjectKV(env.COVARA_KV, { name: "covara-kv", prefix: "app" });

// Config-style
createKV({ type: "durable-object", durableObject: { namespace: env.COVARA_KV } });
```

## Cross-process fan-out

`initializeEventSubscription()` makes each isolate replay other isolates' mutation events into its local subscribers. If you initialize via `initializeKV(config)` instead of `setGlobalKV(...)`, this is called automatically for any distributed store. See [Scaling across instances](./workers.md#scaling-across-instances).

## Related

- [KV store](../platform/kv.md) · [Cloudflare Workers](./workers.md) · [Subscriptions](../realtime/subscriptions.md)
- [Tasks](../platform/tasks.md)

---

## Environment variables


`createEnv` defines a Zod-validated environment schema with automatic public/private separation, an HTTP endpoint to expose public variables (with ETag caching), a React hook, and type generation. **This is the recommended way to read config and secrets in your app** — reference the typed `env.X` everywhere instead of `process.env`.

Under the hood it reads through the runtime-safe primitives `readEnv`, `isProduction`, and `isDebugEnabled` (so it works on Workers too — Covara itself never touches `process.env` directly). Reach for those primitives directly only for a quick one-off read where a full schema is overkill; otherwise prefer `createEnv` for type safety and fail-fast validation.

## Define a schema

```typescript
import { createEnv } from "covara";
import { z } from "zod";

export const env = createEnv({
  NODE_ENV: z.enum(["development", "production", "test"]),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  PUBLIC_API_URL: z.string().url(),
  PUBLIC_VERSION: z.string(),
});

env.PORT;         // number
env.DATABASE_URL; // string
```

Values are read from `process.env` using the key path joined with underscores. Nested schemas map accordingly:

```typescript
const env = createEnv({
  SERVER: { PORT: z.string().transform(Number), HOST: z.string() },
  DB: { URL: z.string(), POOL_SIZE: z.string().transform(Number) },
});
// reads SERVER_PORT, SERVER_HOST, DB_URL, DB_POOL_SIZE
```

Use Zod defaults and transforms for optional/parsed values:

```typescript
createEnv({
  PORT: z.string().default("3000").transform(Number),
  DEBUG: z.string().default("false").transform((v) => v === "true"),
  ALLOWED_ORIGINS: z.string().transform((s) => s.split(",")),
});
```

## Public vs private

A variable is **public** (exposable to the client) in two ways:

```typescript
import { createEnv, envVariable } from "covara";

createEnv({
  PUBLIC_API_URL: z.string(), // PUBLIC_ prefix → automatically public
  SECRET_KEY: z.string(),     // private by default
  API_URL: envVariable(process.env.API_URL, z.string(), { public: true }), // explicit
});
```

Everything else is private. `env.getPublicEnvironmentVariables()` returns only the public set.

## Serving public vars over HTTP

```typescript
import { usePublicEnv } from "covara";

app.route("/api/env", usePublicEnv(env, {
  cacheControl: "public, max-age=3600",
  exposeSchema: true, // also serve /api/env/schema for typegen
}));
```

This mounts `GET /api/env` (public vars as JSON) and `GET /api/env/schema` (schema for [typegen](../client/typegen.md)). The endpoint computes an **ETag** from the public values at startup, so `If-None-Match` returns `304` until the server restarts with new values.

## Client

```typescript
import { fetchPublicEnv, createEnvClient } from "covara/client";

const env = await fetchPublicEnv<{ PUBLIC_API_URL: string }>("http://localhost:3000");

const envClient = createEnvClient<{ PUBLIC_API_URL: string }>({ baseUrl: "http://localhost:3000" });
const unsubscribe = envClient.subscribe((env) => console.log(env), 60000); // poll
```

```tsx
import { usePublicEnv } from "covara/client/react";

function App() {
  const { env, isLoading, error, refetch } = usePublicEnv<{ PUBLIC_API_URL: string; PUBLIC_VERSION: string }>();
  if (isLoading) return Loading…;
  return {env?.PUBLIC_API_URL} v{env?.PUBLIC_VERSION};
}
```

Hook options: `baseUrl`, `envPath` (default `/api/env`), `refreshInterval`, `enabled`.

## Type generation

The [typegen](../client/typegen.md) tool emits a `PublicEnv` type from the schema endpoint:

```typescript
export type PublicEnv = { PUBLIC_API_URL: string; PUBLIC_VERSION: string };
```

```bash
npx covara types --url http://localhost:3000 --out src/generated/api-types.ts
```

## Best practices

- Use the `PUBLIC_` prefix consistently; never expose secrets (only `PUBLIC_`/`{ public: true }` are exposed).
- Validate strictly with Zod (`.url()`, `.min()`, `.pipe()`).
- Cache aggressively on the client with `cacheControl`.

See the [environment-variables contract](../contracts/environment-variables.md) for the public-exposure guarantee.

## Related

- [Type generation](../client/typegen.md) · [Client overview](../client/overview.md) · [Env vars contract](../contracts/environment-variables.md)

---

## Deploy on Node


A `CovaraApp` runs standalone on Node via `startServer` from `covara/node` (which wraps `@hono/node-server`).

```typescript
import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import { createCovara } from "covara";
import { startServer } from "covara/node";
import { todos } from "./schema.js";
import { env } from "./env.js"; // your createEnv schema — see Environment variables

const db = drizzle(createClient({ url: env.DB_FILE_NAME }));

const app = createCovara({ cors: true }).resource(todos, {
  db, id: todos.id, auth: { public: true },
});

const server = await startServer(app, {
  port: env.PORT,
  hostname: "0.0.0.0",
  onListen: ({ port }) => console.log(`Listening on ${port}`),
});
```

`startServer(app, options)` resolves once the server is listening and returns `{ port, address, close }`. If `port` is omitted, `PORT` from the environment is used (default 3000).

## Graceful shutdown

By default `startServer` installs `SIGTERM`/`SIGINT` handlers that drain the instance before exiting. On a shutdown signal it:

1. Flips readiness so [`/readyz`](../platform/health.md) returns `503` — load balancers and Kubernetes readiness probes stop routing new traffic here.
2. Closes long-lived [SSE subscriptions](../realtime/subscriptions.md) cleanly so clients reconnect to a healthy instance instead of seeing a dropped socket.
3. Waits a bounded drain window (`drainTimeoutMs`, default 10s) before closing the listener and exiting.

```typescript
await startServer(app, {
  port: 3000,
  drainTimeoutMs: 15000,    // drain window before forcing the socket closed
  // gracefulShutdown: false, // opt out and manage shutdown yourself via close()
});
```

Set `gracefulShutdown: false` to manage shutdown yourself — the returned `close()` still performs the same drain sequence. `/healthz` (liveness) keeps returning `200` during drain; only `/readyz` flips to `503`.

## Docker

`npx covara create` writes a `Dockerfile` and `docker-compose.yml` (app + Redis, plus Postgres when `--db postgres`) and a `.dockerignore`. See the [CLI](../tooling/cli.md).

## Scaling

Run multiple instances behind a load balancer; give every instance a shared [Redis KV](../platform/kv.md) (via `initializeKV`) so [subscriptions](../realtime/subscriptions.md), sessions, rate limits, and the [task queue](../platform/tasks.md) are shared. See [Scaling across instances](./workers.md#scaling-across-instances).

## Runtime notes

- Covara never reads `process.env` directly — it uses runtime-safe helpers (`readEnv`, `isProduction`, `isDebugEnabled`). See [Environment variables](./environment-variables.md).
- [Local filesystem storage](../platform/storage.md) is available on Node (use R2/S3 on Workers).

## Related

- [Cloudflare Workers](./workers.md) · [Database matrix](./databases.md) · [Health checks](../platform/health.md)
- [Environment variables](./environment-variables.md) · [CLI](../tooling/cli.md)

---

## Deploy on Cloudflare Workers


A `CovaraApp` is a Hono app, so it works directly as a Worker fetch handler.

```typescript
// src/worker.ts
import { drizzle } from "drizzle-orm/d1";
import { createCovara, type CovaraApp } from "covara";
import { todos } from "./schema";

interface Env { DB: D1Database }

let app: CovaraApp | undefined;

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    app ??= createCovara({ cors: true }).resource(todos, {
      db: drizzle(env.DB), id: todos.id, auth: { public: true },
    });
    return app.fetch(request, env, ctx);
  },
};
```

If your app needs nothing from `env`, `export default app` works too.

### D1 and transactions

Cloudflare D1 has **no interactive transactions** (drizzle's `db.transaction()` would issue `BEGIN`/`COMMIT`, which D1 rejects). Covara detects D1 automatically and adapts: single-statement mutations (create/update/replace/delete) auto-commit atomically, and batch upsert uses D1's atomic `db.batch()`. Two limitations are inherent to D1: `nestedWrites` creates run sequentially (not atomic), and a throwing `onAfter*` hook can't roll back an already-committed write. If you wire a custom driver the detection can't classify, set `transactions: true | false` in the resource config. See the [mutation-tracking contract](../contracts/track-mutations.md#engines-without-interactive-transactions-cloudflare-d1).

## wrangler.toml

`nodejs_compat` is required (Covara uses `node:crypto`):

```toml
name = "my-app"
main = "src/worker.ts"
compatibility_date = "2026-06-01"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "REPLACE_WITH_YOUR_D1_DATABASE_ID"
```

```bash
wrangler d1 create my-app-db          # copy database_id into wrangler.toml
npx drizzle-kit generate
wrangler d1 migrations apply my-app-db --local
wrangler d1 migrations apply my-app-db --remote
wrangler deploy
```

## PostgreSQL on Workers

Use `postgres-js` with a connection-string secret, and consider [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) for pooling:

```typescript
import postgres from "postgres";
import { drizzle } from "drizzle-orm/postgres-js";

const buildApp = (env: { DATABASE_URL: string }) => {
  const client = postgres(env.DATABASE_URL, { max: 5, fetch_types: false });
  return createCovara({ cors: true }).resource(todos, { db: drizzle(client), id: todos.id });
};
```

```bash
wrangler secret put DATABASE_URL
```

See the full [database matrix](./databases.md).

## Shared state: Durable Object KV

The in-memory KV is per-isolate, and Cloudflare runs many isolates — without a shared KV, a mutation handled by one isolate never reaches [SSE subscribers](../realtime/subscriptions.md) on another, and rate limits/sessions aren't shared. Use the [Durable Object KV](./durable-object-kv.md):

```typescript
import { createCovara, createDurableObjectKV, setGlobalKV, initializeEventSubscription, type CovaraApp } from "covara";
export { CovaraKVDurableObject } from "covara";

interface Env { DB: D1Database; COVARA_KV: DurableObjectNamespace }

let app: CovaraApp | undefined;
const buildApp = (env: Env): CovaraApp => {
  setGlobalKV(createDurableObjectKV(env.COVARA_KV));
  void initializeEventSubscription();
  return createCovara().resource(/* ... */);
};

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    app ??= buildApp(env);
    return app.fetch(request, env, ctx);
  },
};
```

```toml
[durable_objects]
bindings = [{ name = "COVARA_KV", class_name = "CovaraKVDurableObject" }]

[[migrations]]
tag = "v1"
new_sqlite_classes = ["CovaraKVDurableObject"]
```

Projects from `npx covara create --template cloudflare` wire all of this up. See [Durable Object KV](./durable-object-kv.md) for how it works.

## Scaling across instances

Run as many instances as you like behind a load balancer. For realtime to stay correct, give every instance a shared distributed [KV](../platform/kv.md) (Redis on Node, the Durable Object KV on Workers) and initialize it via `initializeKV` so subscription fan-out is wired up:

```typescript
import { initializeKV } from "covara/kv";
await initializeKV({ type: "redis", redis: { url: env.REDIS_URL } });
```

`initializeKV` calls `initializeEventSubscription()` for any distributed store, so a mutation on one instance reaches subscribers on another, and rate limits, sessions, and the task queue are shared. The explicit `void initializeEventSubscription()` is only needed when you use `setGlobalKV(...)` directly. The in-memory KV is per-process and must not be used when state spans instances.

## Cost: SSE subscriptions on Workers

Cloudflare bills **CPU time, not wall-clock time**. A long-lived idle SSE subscription costs essentially nothing while it waits — heartbeats and event pushes consume only microseconds of CPU each. Thousands of mostly-idle realtime connections are cheap to keep open.

## Background tasks on the edge

There's no long-lived poller on Workers — use the [Cloudflare Queues adapter](../platform/tasks.md#cloudflare-queues), and drain the [search outbox](../core/search.md#transactional-outbox-at-least-once-indexing) from a `scheduled` handler.

## Runtime notes

- Covara never reads `process.env` directly (`readEnv`/`isProduction`/`isDebugEnabled`), so it works where `process` doesn't exist.
- [Local filesystem storage](../platform/storage.md) is Node-only; use R2 or S3-compatible storage on Workers.

## Related

- [Durable Object KV](./durable-object-kv.md) · [Database matrix](./databases.md) · [Tasks](../platform/tasks.md)
- [Environment variables](./environment-variables.md) · [CLI](../tooling/cli.md)

---

## Server-rendered htmx — Overview


> **Beta.** Server-rendered htmx support is newer than Covara's JSON API and TypeScript client and may still change between releases. The JSON API and subscription engine it builds on are stable.

Covara can serve a complete, **server-rendered, real-time UI with htmx** — list, create, update, delete, live updates, live aggregates, optimistic updates and offline — from a **single JSX page**. You write the page; Covara generates the htmx endpoints.

The package subpath is `covara/htmx`.

## The idea: the JSX page is the spec

You register one JSX component per route with `app.page(path, Component)`. Inside it, **`<Live>` is the only special element** — it declares a resource, a query, and how a row renders. Everything else is plain JSX/HTML wired with **boring attribute helpers** from the row/region context (`c`). Covara introspects the page and **auto-generates the htmx endpoints** it needs:

| Generated endpoint | Purpose |
| --- | --- |
| `GET <page>` | Full server-side render of the page |
| `GET /__covara/live/<regionId>` | List / pagination fragment |
| `POST /__covara/live/<regionId>` | Create → returns the rendered row |
| `PATCH \| DELETE /__covara/live/<regionId>/<id>` | Update / delete |
| `GET /__covara/live/<regionId>/subscribe` | Live SSE stream of server-rendered fragments |

All generated endpoints reuse the resource's own query/validation/scope engine, and the live stream reuses the existing subscription engine — Covara only adds the HTML rendering. The generated endpoints live under the framework-internal `/__covara/live` namespace, so they never collide with your routes.

## A complete page

```tsx
app.page("/todos", ({ user }) => (
  <Live
    resource={todos}
    query={{ filter: "done==false", orderBy: "position", limit: 50 }}
    create={(c) => (
      <form {...c.create()}>
        <input name="title" />
        <button>Add</button>
      </form>
    )}
    container={(rows, c) => {rows}}
    empty={() => No todos}
    render={(todo, c) => (
      
        <input type="checkbox" name="done" hx-patch={`/api/todos/${todo.id}`} hx-vals='{"done":true}' />
        {todo.title}
        <button {...c.delete(todo.id)}>Delete</button>
      
    )}
  />
));
```

Covara generates wiring, **not UI components**. You spread `c.create()`, `c.row(id)`, `c.update(id)`, `c.delete(id)`, `c.container()` onto your own elements.

## What the helpers emit

```ts
c.row("42")      // { id: "cv-todos-0-42", "data-covara-id": "42" }
c.create()       // { "hx-post": "/__covara/live/todos-0", "hx-target": "#cv-todos-0-list", "hx-swap": "beforeend" }
c.update("42")   // { "hx-patch": "/__covara/live/todos-0/42", "hx-target": "#cv-todos-0-42", "hx-swap": "outerHTML" }
c.delete("42")   // { "hx-delete": "/__covara/live/todos-0/42", "hx-target": "#cv-todos-0-42", "hx-swap": "outerHTML" }
c.container()    // { id, data-cv-region, data-cv-sse, data-cv-list, data-cv-template }
```

## Live updates

Each `<Live>` container connects to its generated SSE endpoint. When **anyone** mutates the resource (another tab, a background job, a raw query), the subscription engine pushes the change and the server renders just the affected row via your `render` closure. The client applies it by id:

- `added` → insert the rendered row,
- `changed` → replace the row in place,
- `removed` → remove the row,
- `invalidate` → refetch the list.

`<LiveAggregate>` works the same way for aggregates (it re-fetches its fragment when the resource changes).

## Optimistic updates & offline

A new row is inserted exactly once, by the region's live SSE `added` event (the create form posts with `hx-swap="none"`), so it appears identically in every open tab with no duplicate or phantom row. Deletes are optimistic (the row hides immediately and is restored on failure), and create mutations made while offline are queued and replayed on reconnect. Covara also ships a server-derived row `<template>` per page for custom client rendering.

This runs from the bundled client runtime (vendored htmx core + the Covara runtime), served automatically at `/__covara/live/_runtime.js` and injected into every page. See [Building pages](./pages.md) for setup and details.

---

## Building pages


> **Beta.** The server-rendered htmx layer is newer than the rest of Covara and its API may still change.

## Enable JSX

The `<Live>`/`<LiveAggregate>` elements are [hono/jsx](https://hono.dev/docs/guides/jsx) components. Configure your app's `tsconfig.json` for hono's JSX runtime:

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}
```

You can also skip JSX entirely and call `jsx()` / use the `html` tagged template — the closures only need to return a string-coercible value. JSX is recommended.

## Register a page

```tsx
import { createCovara } from "covara/server";
import { Live } from "covara/htmx";
import { todos } from "./schema";

const app = createCovara()
  .resource("/todos", todos, { id: todos.id, db })
  .page("/todos", ({ user }) => (
    <Live
      resource={todos}
      query={{ orderBy: "position" }}
      create={(c) => (
        <form {...c.create()}>
          <input name="title" />
          <button>Add</button>
        </form>
      )}
      container={(rows, c) => {rows}}
      render={(t, c) => (
        
          {t.title}
          <button {...c.delete(t.id)}>Delete</button>
        
      )}
    />
  ));
```

`GET /todos` now returns a full server-rendered page, and the generated endpoints under `/__covara/live/todos-0` handle list/create/update/delete/subscribe. The page must reference a resource that was registered with `.resource(...)` on the same app.

## The client bundle

A bundle (vendored htmx core + the Covara live runtime) is served at `/__covara/live/_runtime.js` and a `<script>` for it is appended to every page automatically — nothing to wire up. To serve/inline it yourself:

```ts
import { serveHtmxBundle, htmxBundle } from "covara/htmx";

app.get("/assets/covara.js", serveHtmxBundle());
// or: const js = htmxBundle();
```

## Pages must render synchronously

A page component runs synchronously: each `<Live>` returns a placeholder immediately and the framework fetches that region's data afterwards. Don't use async components in the page shell (data fetching is per-`<Live>`, handled for you). Page components must also be **pure functions of their context** — they are re-run to resolve regions for the generated endpoints.

## Filters are display refinements, not security

`query.filter` is a UX refinement (e.g. `done==false`), captured per request. **Row-level access control must come from the resource's `auth` scope** — it is enforced on every generated endpoint (list, mutate, subscribe), because they run through the resource engine. Never rely on a `<Live>` filter for security.

When an update moves a row out of a region's filter (e.g. toggling `done` on a `done==false` list), the update endpoint returns an empty body so the row is removed for the acting client; other clients get the correct `removed` event over SSE.

## Live updates

The container connects to its SSE endpoint and applies server-rendered fragments by id. The initial rows are SSR'd, so the stream uses `skipExisting` and the client de-duplicates by row id. Reconnection, sequence-gap recovery and backpressure are handled by the existing subscription engine.

## Live updates, optimism & offline

- **Create** is inserted exactly once by the region's live SSE `added` event — the same path every connected client uses. The create form posts with `hx-swap="none"` (its response is not swapped in), so there is no duplicate or phantom row, and the new row appears identically in every open tab.
- **Delete** hides the row immediately (optimistic) and removes it on success; on failure the row is restored.
- **Update** swaps the affected row in place from the server's response and is reconciled by the SSE `changed` event.
- **Offline**: failed create mutations are queued in `localStorage` and replayed on reconnect, after which affected regions resync.

The server still ships a per-region `<template>` of the row markup (derived from your `render` closure); it is available for custom client behavior but the default flow relies on the SSE insert to keep create duplication-free.

## Live aggregates

```tsx
import { LiveAggregate } from "covara/htmx";

app.page("/stats", () => (
  <LiveAggregate
    resource={todos}
    groupBy={["done"]}
    render={(data) => {(data?.groups ?? []).length} groups}
  />
));
```

The aggregate fragment is server-rendered on load and re-fetched whenever the underlying resource changes.

## CSP

The page and generated endpoints inherit your app's security headers. The attribute-driven htmx + the served runtime need `script-src 'self'` and `connect-src 'self'` (for the SSE stream); no `'unsafe-inline'` is required.

---

## Introduction

# Covara

**Your Drizzle schema is already a backend.**

Covara turns a [Drizzle ORM](https://orm.drizzle.team) schema into a complete, production-ready API — REST endpoints, real-time subscriptions, auth, file uploads, billing, email, and background jobs — with a type-safe, offline-first TypeScript client on the other end. It is built on [Hono](https://hono.dev) and runs standalone on Node or at the edge on Cloudflare Workers.

## The problem Covara solves

Every product backend is the same 80%: CRUD endpoints, filtering, pagination, auth, sessions, password reset, file uploads, webhooks for payments, transactional email, a job queue, and a client that talks to all of it. You rewrite this plumbing for every project, and the pieces never quite fit together — your realtime layer doesn't know about your auth scopes, your client types drift from your API, your offline cache fights your subscriptions.

Covara makes that 80% *one coherent system* derived from a single source of truth: your Drizzle schema.

- **Define a table** → get a full REST API with filtering, pagination, aggregations, batch ops, and OpenAPI docs.
- **Add an auth scope** → it is enforced everywhere: queries, mutations, subscriptions, search.
- **Mutate data anywhere** — a generated endpoint, a custom route, or an RPC — and every subscribed client updates in real time.
- **Use the client** → full TypeScript inference, optimistic updates, an offline queue, and automatic reconnect, in React, React Native, or plain TypeScript.

The remaining 20% — your business logic — lives in lifecycle hooks, RPC procedures, and ordinary Hono routes, with the framework's mutation tracking and typing intact.

## In one screen

```tsx
// server: a table becomes an API
import { createCovara, rsql } from "covara";
import { startServer } from "covara/node";

const app = createCovara({ cors: true }).resource("/todos", todosTable, {
  id: todosTable.id,
  db,
  auth: { update: async (user) => rsql`userId==${user.id}` },
});

await startServer(app, { port: 3000 });
```

```tsx
// client: the API becomes live UI
import { useLiveList } from "covara/client/react";

function TodoList() {
  const { items, mutate } = useLiveList<Todo>("/api/todos", { orderBy: "position" });
  return items.map((todo) => (
    <Todo key={todo.id} {...todo} onDelete={() => mutate.delete(todo.id)} />
  ));
  // creates/updates/deletes apply optimistically, sync offline,
  // and stream to every other connected client over SSE
}
```

## How the pieces fit together

```mermaid
flowchart LR
  Schema[Drizzle schema] --> Resource[useResource / createCovara]
  Resource --> REST[REST endpoints]
  Resource --> Sub[SSE subscriptions]
  Resource --> OpenAPI[OpenAPI + Admin UI]
  Mutations[Any mutation\nendpoint · custom route · RPC] --> Changelog[Changelog]
  Changelog --> Sub
  Sub --> Client[TypeScript client]
  REST --> Client
  Client --> React[React / React Native hooks]
  Client --> Offline[Offline queue]
```

A mutation through any path — a generated endpoint, a custom Hono route wrapped with [mutation tracking](./realtime/mutation-tracking.md), or an [RPC procedure](./core/procedures.md) — writes to the [changelog](./realtime/changelog.md). Subscriptions read the changelog and push deltas to connected clients with sequence numbers for reliable, resumable delivery.

## Feature map

| Area | Highlights |
|------|-----------|
| **[Core API](./core/resources-and-app.md)** | CRUD, [filtering (30+ operators)](./core/filtering.md), [cursor pagination](./core/pagination.md), [aggregations](./core/aggregations.md), [relations](./core/relations.md), [batch ops](./core/batch.md), [soft delete](./core/soft-delete.md), [computed/masked fields](./core/fields.md), [optimistic locking](./core/optimistic-locking.md), [nested writes](./core/nested-writes.md) |
| **[Real-time](./realtime/subscriptions.md)** | [SSE subscriptions](./realtime/subscriptions.md), [live aggregations](./realtime/aggregate-subscriptions.md), [changelog](./realtime/changelog.md), [mutation tracking](./realtime/mutation-tracking.md) |
| **[Auth & security](./auth/overview.md)** | [OIDC provider](./auth/oidc-provider.md), [federated login](./auth/federated.md), [JWT](./auth/jwt.md), [sessions](./auth/sessions.md), [MFA/TOTP](./auth/mfa.md), [magic links](./auth/magic-links.md), [API keys](./auth/api-keys.md), [RSQL scopes](./auth/scopes.md), [field masking](./core/fields.md), [security headers](./auth/security-headers.md) |
| **[Platform services](./platform/storage.md)** | [File storage](./platform/storage.md), [email](./platform/email.md), [billing](./platform/billing.md), [background tasks](./platform/tasks.md), [KV store](./platform/kv.md), [health checks](./platform/health.md) |
| **[Client library](./client/overview.md)** | Typed client, [React hooks](./client/react-hooks.md), [live queries](./client/live-queries.md), [offline](./client/offline.md), [auth](./client/auth.md), [file uploads](./client/files.md), [type generation](./client/typegen.md), [React Native](./client/react-native.md) |
| **[Runs everywhere](./deployment/node.md)** | [Node](./deployment/node.md), [Cloudflare Workers](./deployment/workers.md), [SQLite & PostgreSQL](./deployment/databases.md), [Durable Object KV](./deployment/durable-object-kv.md) |
| **[Tooling](./tooling/cli.md)** | [CLI scaffolder](./tooling/cli.md), [OpenAPI](./tooling/openapi.md), [Admin UI](./tooling/admin-ui.md), [middleware](./tooling/middleware.md), [error handling](./tooling/error-handling.md) |

## Requirements

- Node.js 18+ or Cloudflare Workers (`nodejs_compat`)
- TypeScript 5+
- [Drizzle ORM](https://orm.drizzle.team) (peer dependency `>=0.30.0`)
- [Hono](https://hono.dev) 4+
- [Zod](https://zod.dev) (peer dependency `>=3.0.0`)
- React `>=18` is an optional peer dependency, only needed for the React client hooks.

## Where to go next

- **[Quick Start](./quick-start.md)** — scaffold a project or add Covara to an existing app in a few minutes.
- **[Tutorial: a real-time todo app](./tutorial.md)** — build a complete app end to end, server and client.
- **[Resources & the app factory](./core/resources-and-app.md)** — the central abstraction every endpoint is built on.
- **[Contracts](./contracts/overview.md)** — the formal guarantees (and non-guarantees) the framework commits to.

---

## Billing


A single, provider-agnostic billing layer over **Stripe**, **Lemon Squeezy**, **Paddle**, and **Polar.sh**. One `BillingAdapter` interface covers customers, checkout (subscriptions + one-time + usage), subscription management, usage reporting, a hosted portal, and signature-verified webhooks. On top of it, `createBilling()` adds plan definitions, a KV-backed **credits ledger**, idempotent webhook handling with automatic credit granting, a mountable **router**, and a typed **client** with React hooks.

All adapters are `fetch`-based with **no SDK dependencies** and run on Node and Cloudflare Workers. Import from `covara` or `covara/billing`.

## Choose an adapter

```typescript
import {
  createStripeAdapter, createLemonSqueezyAdapter, createPaddleAdapter, createPolarAdapter,
} from "covara/billing";

const adapter = createStripeAdapter({ apiKey: env.STRIPE_SECRET_KEY });
// createLemonSqueezyAdapter({ apiKey, storeId })
// createPaddleAdapter({ apiKey, sandbox: true })
// createPolarAdapter({ accessToken, server: "sandbox" })
```

What `items[].priceId` means per provider, and the verified webhook header:

| Provider | `priceId` is | Webhook header |
|----------|--------------|----------------|
| Stripe | Price id (`price_…`) | `stripe-signature` (HMAC-SHA256 of `t.payload`) |
| Lemon Squeezy | Variant id | `x-signature` (HMAC-SHA256 hex of body) |
| Paddle | Price id (`pri_…`) | `paddle-signature` (`ts:payload`) |
| Polar | Product/price id | Standard Webhooks (`webhook-signature`) |

## `createBilling`

```typescript
import { createBilling } from "covara/billing";

const billing = createBilling({
  adapter,
  webhookSecret: env.STRIPE_WEBHOOK_SECRET,
  plans: [
    { key: "pro_monthly", priceId: "price_123", type: "subscription", interval: "month", credits: 10_000 },
    { key: "credits_pack", priceId: "price_456", type: "one_time", credits: 5_000 },
    { key: "metered_api", priceId: "price_789", type: "usage" },
  ],
});
```

`BillingPlan`: `{ key, priceId, name?, type?: "subscription"|"one_time"|"usage", credits?, interval?, metadata? }`. `credits` is granted to the account automatically when a payment for that plan succeeds (see [Webhooks](#webhooks)).

## Checkout

```typescript
const session = await billing.checkoutPlan("pro_monthly", {
  customerEmail: "user@example.com",
  successUrl: "https://app.acme.com/welcome",
  cancelUrl: "https://app.acme.com/pricing",
  metadata: { accountId: user.id }, // correlate the webhook back to your user
});
// redirect the browser to session.url
```

Or build directly with `billing.checkout({ mode, items, successUrl, ... })` — `mode` is `"subscription"` or `"payment"`; `checkoutPlan` infers it from the plan's `type`.

## Subscriptions & usage

```typescript
const sub = await billing.getSubscription("sub_123");
await billing.cancelSubscription("sub_123", { atPeriodEnd: true });
await billing.adapter.updateSubscription("sub_123", { priceId: "price_higher_tier" });
await billing.reportUsage({ subscriptionItemId: "si_123", quantity: 42, action: "increment" });
```

`BillingSubscription` is normalized: `{ id, customerId, status, priceId?, currentPeriodStart?, currentPeriodEnd?, cancelAtPeriodEnd?, metadata?, provider }`, with `status ∈ active|trialing|past_due|canceled|paused|incomplete|expired|unpaid`.

:::note Paddle
`reportUsage` and the hosted portal are managed differently on Paddle and throw a clear `BillingError` / are unavailable; usage is driven by Paddle prices.
:::

## Credits ledger

KV-backed and atomic (uses the KV's `incrBy`). Available as `billing.credits` or standalone via `createCreditsLedger()`.

```typescript
await billing.credits.grant(accountId, 1000, { reason: "signup-bonus" });
const { ok, balance } = await billing.credits.consume(accountId, 50, { reason: "api-call" });
await billing.credits.balance(accountId);
await billing.credits.history(accountId, 50);
```

`consume` refuses to overdraw unless `{ allowNegative: true }`.

## Webhooks

```typescript
const event = await billing.handleWebhook(rawBody, headers);
```

`handleWebhook` verifies the provider signature (when `webhookSecret` is set), **de-duplicates** retried deliveries by event id (via [KV](./kv.md)), resolves the matched `planKey`/`creditsToGrant`, and — on `payment.succeeded` — **auto-grants** the plan's credits to the resolved account (from `metadata.accountId`/`userId`, else the customer id), then calls your `onEvent`. Normalized `BillingEvent.type`: `checkout.completed | subscription.created | subscription.updated | subscription.canceled | payment.succeeded | payment.failed | unknown`.

Disable auto-granting with `autoGrantCredits: false`, or customize account resolution with `resolveAccount: (event) => string`.

## Server router

```typescript
import { createBillingRouter } from "covara/billing";
import { getUser } from "covara";

app.route("/api/billing", createBillingRouter(billing, {
  getAccount: (c) => getUser(c)?.id,
  getCustomerId: (c) => getUser(c)?.billingCustomerId,
  getCustomerEmail: (c) => getUser(c)?.email,
}));
```

Endpoints (non-webhook routes require an authenticated user):

- `POST /checkout` → `{ id, url }`
- `GET /subscription` → `{ subscriptions }`
- `POST /portal` → `{ url }`
- `GET /credits` → `{ balance }`
- `POST /webhook` → signature-verified, idempotent

## Client & React

```typescript
import { getOrCreateClient } from "covara/client";
import { useCredits, useSubscription, useCheckout } from "covara/client/react";

const client = getOrCreateClient({ baseUrl: location.origin, billing: { basePath: "/api/billing" } });
await client.billing.redirectToCheckout({ plan: "pro_monthly", successUrl: location.origin + "/welcome" });
```

```tsx
const { balance, refresh } = useCredits();
const { activeSubscription } = useSubscription();
const { redirectToCheckout, loading } = useCheckout();
```

See [Client billing hooks](../client/billing.md).

## End-to-end flow

1. Define `plans` (with `credits`) and `createBilling`.
2. Mount `createBillingRouter`; point the provider's webhook at `/api/billing/webhook`.
3. Client calls `redirectToCheckout({ plan })` → hosted checkout.
4. Provider fires `payment.succeeded` → router verifies + dedupes + grants `plan.credits`.
5. App consumes credits via `billing.credits.consume(accountId, n)`.

Webhook idempotency and credit granting require a configured global [KV](./kv.md). For side effects beyond credit granting (emails, provisioning), handle them in `onEvent` and offload to a [background task](./tasks.md).

## Related

- [Client billing hooks](../client/billing.md) · [KV store](./kv.md) · [Background tasks](./tasks.md)
- [Billing contract](../contracts/billing.md)

---

## Email


Covara ships a small, provider-agnostic email layer: a unified `EmailAdapter` interface, adapters for **Resend** and the **Cloudflare Email Service**, and a fluent **template builder** that renders responsive, client-safe HTML plus a plaintext fallback. Import from `covara` or `covara/email`.

## Configure an adapter

```typescript
import { createResendAdapter, setGlobalEmail } from "covara/email";

setGlobalEmail(createResendAdapter({ apiKey: env.RESEND_API_KEY }));
```

On Cloudflare Workers, use the Email Service binding (no API key, no network egress):

```typescript
import { createCloudflareEmailAdapter, setGlobalEmail } from "covara/email";

setGlobalEmail(createCloudflareEmailAdapter({ binding: env.EMAIL, from: "noreply@acme.com" }));
```

Both adapters are Workers-safe (Resend via `fetch`, Cloudflare via the binding).

## Sending

```typescript
import { sendEmail, sendEmailBatch } from "covara/email";

await sendEmail({
  from: "Acme <noreply@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: "Welcome",
  text: "Welcome",
});

await sendEmailBatch([msg1, msg2]); // uses the adapter's batch API when available
```

`EmailMessage` fields: `from`, `to`, `subject`, `html`, `text`, `cc`, `bcc`, `replyTo`, `attachments` (`{ filename, content, contentType }`), `headers`, `tags`. Addresses accept `"a@b.com"`, `{ email, name }`, or arrays of either. `sendEmail` returns `{ id?, provider }`.

## Template builder

`createEmail(theme?)` returns a fluent builder; `.build()` returns `{ html, text }`. All user-supplied content is HTML-escaped automatically.

```typescript
import { createEmail, sendEmail } from "covara/email";

const { html, text } = createEmail({ brandColor: "#4f46e5", logoUrl: "https://cdn.acme.com/logo.png" })
  .preview("Confirm your email address")
  .heading("Confirm your email")
  .text("Tap the button below to verify your account.")
  .button("Verify email", `https://acme.com/verify?token=${token}`)
  .divider()
  .text("Or use this code:")
  .code("123456")
  .footer("If you didn't sign up, you can ignore this email.")
  .build();

await sendEmail({ from: "noreply@acme.com", to: email, subject: "Confirm your email", html, text });
```

### Blocks

`heading(text, level?)`, `text(text)`, `button(label, url)`, `link(label, url)`, `divider()`, `spacer(px?)`, `image(url, alt?)`, `code(text)`, `footer(text)`, `raw(html, text)`, and `preview(text)` (hidden inbox preview line).

### Theme (`EmailTheme`)

`brandColor`, `textColor`, `mutedColor`, `backgroundColor`, `bodyColor`, `fontFamily`, `borderRadius`, `width`, `logoUrl`, `logoAlt` — all optional with sane defaults.

## Using with auth flows

The auth [verification / password-reset](../auth/account-security.md) / [magic-link](../auth/magic-links.md) flows take app-provided `sendToken`/`sendLink` callbacks — render with the builder and send:

```typescript
useAuth({
  verification: {
    async sendToken({ identifier, token }) {
      const { html, text } = createEmail()
        .heading("Verify your email")
        .button("Verify", `https://acme.com/verify?token=${token}`)
        .build();
      await sendEmail({ from: "noreply@acme.com", to: identifier, subject: "Verify your email", html, text });
    },
  },
});
```

## Delivery semantics

Sends are **best-effort** and return the provider's message id; there is no built-in retry queue. For guaranteed delivery, send from a [background task](./tasks.md) (which gives you retries + a dead-letter queue) rather than inline in a request handler. See the [email contract](../contracts/email.md).

## Related

- [Background tasks](./tasks.md) · [Account security](../auth/account-security.md) · [Magic links](../auth/magic-links.md)
- [Email contract](../contracts/email.md)

---

## Health checks


`createCovara` mounts two endpoints by default:

| Endpoint | Probe | Meaning |
|----------|-------|---------|
| `GET /healthz` | Liveness | The process is up. Stays `200` even during graceful shutdown. |
| `GET /readyz` | Readiness | The instance is ready to serve traffic. Flips to `503` during shutdown so load balancers drain it. |

Both support `HEAD` for cheap probes. Wire them into your orchestrator (Kubernetes `livenessProbe`/`readinessProbe`, load-balancer health checks).

## Configuration

```typescript
const app = createCovara({
  health: {
    version: "1.0.0",
    checks: {
      kv: getGlobalKV(),         // dependency checks — included in the readiness result
    },
    thresholds: {
      eventLoopLagMs: 100,        // mark unhealthy above this lag
      memoryPercent: 90,          // mark unhealthy above this memory usage
    },
  },
});
```

Pass `health: false` to disable the endpoints, or `health: true` for defaults.

`checks` accepts dependency objects (e.g. the [KV store](./kv.md), a database) that the readiness endpoint probes; a failing dependency makes `/readyz` report unhealthy. `thresholds` add runtime guards (event-loop lag, memory) on Node.

## Response shape

```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "checks": { "kv": { "status": "ok" } }
}
```

## Graceful shutdown

On Node, [`startServer`](../deployment/node.md) installs `SIGTERM`/`SIGINT` handlers that, on shutdown:

1. flip readiness so `/readyz` returns `503` (new traffic stops routing here),
2. close long-lived [SSE subscriptions](../realtime/subscriptions.md) cleanly so clients reconnect elsewhere,
3. wait a bounded drain window (`drainTimeoutMs`, default 10s) before closing the listener.

`/healthz` stays `200` throughout — only `/readyz` flips — so the orchestrator distinguishes "draining" from "dead". See [Node deployment](../deployment/node.md#graceful-shutdown).

## Related

- [Node deployment](../deployment/node.md) · [KV store](./kv.md) · [Admin UI](../tooling/admin-ui.md)

---

## KV store


A Redis-compatible key-value abstraction underpins much of Covara: cross-isolate [subscriptions](../realtime/subscriptions.md), [sessions](../auth/sessions.md), the [task queue](./tasks.md), [rate limits](../tooling/middleware.md), the [changelog](../realtime/changelog.md), [billing](./billing.md) idempotency, and the [search outbox](../core/search.md). Initialize it once and the framework wires everything to it.

## Backends

| Backend | `type` | Use |
|---------|--------|-----|
| Memory | `memory` | Development, single process. Per-isolate — not shared. |
| Redis | `redis` | Production on Node / multi-instance. |
| Durable Object | `durable-object` | Cloudflare Workers — shared state without Redis. |

## Initialize

The recommended entry point is `initializeKV`, which also wires **cross-process subscription fan-out** for distributed stores:

```typescript
import { initializeKV } from "covara/kv";

// Development
await initializeKV({ type: "memory", prefix: "my-app" });

// Production (Node)
await initializeKV({ type: "redis", redis: { url: env.REDIS_URL } });
```

For any distributed (non-memory) store, `initializeKV` calls `initializeEventSubscription()` for you, so a mutation on one instance reaches subscribers on another. If you instead set the global KV directly with `setGlobalKV(...)`, call `initializeEventSubscription()` yourself.

```typescript
import { getGlobalKV, setGlobalKV } from "covara";

const kv = getGlobalKV(); // throws if not initialized
```

## Durable Object KV (Workers)

The in-memory KV is per-isolate, and Cloudflare runs many isolates — so a mutation handled by one isolate wouldn't reach subscribers on another without a shared store. The Durable Object KV solves this:

```typescript
import { createDurableObjectKV, setGlobalKV, initializeEventSubscription } from "covara";
export { CovaraKVDurableObject } from "covara";

setGlobalKV(createDurableObjectKV(env.COVARA_KV));
void initializeEventSubscription();
```

```toml
[durable_objects]
bindings = [{ name = "COVARA_KV", class_name = "CovaraKVDurableObject" }]

[[migrations]]
tag = "v1"
new_sqlite_classes = ["CovaraKVDurableObject"]
```

Key properties:

- All operations (strings, hashes, sets, lists, sorted sets, TTLs, transactions) run inside a single, single-threaded Durable Object — **strongly consistent**, and a `multi()` batch is atomic.
- Collections store **one entry per member**, avoiding the 128 KB single-value cap.
- Pub/sub uses **hibernatable WebSockets** — one WebSocket per isolate, idle connections don't accrue duration charges, automatic reconnect with backoff.
- Zero Cloudflare imports (structural types), so it's Node-testable.

`createDurableObjectKV(namespace, { name?, prefix? })` is the direct form (`name` selects the DO instance, default `"covara-kv"`); `createKV({ type: "durable-object", durableObject: { namespace: env.COVARA_KV } })` is the config-style equivalent. Full setup in [Durable Object KV deployment](../deployment/durable-object-kv.md).

## What uses the KV

| Feature | What it stores |
|---------|----------------|
| [Subscriptions](../realtime/subscriptions.md) / [changelog](../realtime/changelog.md) | Sharded subscriptions, changelog window, cross-process events |
| [Aggregate subscriptions](../realtime/aggregate-subscriptions.md) | The `covara:aggregate` pub/sub channel |
| [Sessions](../auth/sessions.md) | Session records (Redis store) |
| [Tasks](./tasks.md) | Queue, locks, idempotency, results, DLQ |
| [Rate limiting](../tooling/middleware.md) / [login throttle](../auth/account-security.md) | Counters |
| [OIDC](../auth/oidc-provider.md) | Clients, codes, refresh tokens, consents (when KV present) |
| [Billing](./billing.md) | Webhook dedupe, credits ledger |
| [Search outbox](../core/search.md) | Index queue, in-flight ops, dead set |

## Related

- [Subscriptions](../realtime/subscriptions.md) · [Tasks](./tasks.md) · [Durable Object KV](../deployment/durable-object-kv.md)
- [Scaling across instances](../deployment/workers.md#scaling-across-instances)

---

## File storage


A file resource **is a regular [resource](../core/resources-and-app.md)** plus an upload/download layer. It gives you everything `useResource` does — cursor-paginated list, single get, update, delete, [subscriptions](../realtime/subscriptions.md), [RPC procedures](../core/procedures.md), [lifecycle hooks](../core/procedures.md), [relations](../core/relations.md), [field policies](../core/fields.md), and full [auth scopes](../auth/scopes.md) — and adds `upload`, `upload-url`, `confirm`, and `download` endpoints, all behind one `StorageAdapter` (local disk, S3, Cloudflare R2, or memory).

## Quick start

```typescript
import { createCovara, initializeStorage, rsql } from "covara";

initializeStorage({ type: "local", local: { basePath: "./uploads", baseUrl: "/uploads" } });

const app = createCovara({ cors: true })
  .resource("/todos", todosTable, { id: todosTable.id, db })
  // Chains like any other resource:
  .fileResource("/files", filesTable, {
    id: filesTable.id,
    db,
    allowedMimeTypes: ["image/jpeg", "image/png", "image/gif"],
    maxFileSize: 5 * 1024 * 1024,
    auth: {
      read: async (user) => rsql`userId==${user?.id}`,
      create: async (user) => (user ? rsql`*` : rsql``),
      delete: async (user) => rsql`userId==${user?.id}`,
    },
  });
```

Local uploads are **served automatically** at the storage `baseUrl` (here `/uploads`) — `createCovara` mounts static serving for a local adapter with a `baseUrl`, so you no longer wire `serveStatic` by hand. (Opt out with `createCovara({ serveLocalStorage: false })`; on Workers use R2 and presigned URLs.) You can still mount `useFileResource(table, config)` manually with `app.route(...)` if you prefer.

## Adapters

| Adapter | `type` | Notes |
|---------|--------|-------|
| Local disk | `local` | Dev/simple deploys. Nested dirs, `.meta.json` sidecars, direct URLs. No presigned URLs. |
| S3 / compatible | `s3` | AWS S3, MinIO, DigitalOcean Spaces. Presigned URLs, multipart. |
| Cloudflare R2 | `r2` | Recommended on Workers. Binding mode or S3-compat mode. |
| Memory | `memory` | Tests; not persisted. |

```typescript
// S3
initializeStorage({
  type: "s3",
  s3: { bucket: "my-bucket", region: "us-east-1", accessKeyId: "...", secretAccessKey: "...", presignedUrlExpiry: 3600 },
});

// S3-compatible (MinIO, Spaces)
initializeStorage({
  type: "s3",
  s3: { bucket: "my-bucket", endpoint: "https://minio.example.com", forcePathStyle: true, accessKeyId: "...", secretAccessKey: "..." },
});

// R2 binding (inside a Worker)
initializeStorage({ type: "r2", r2: { binding: env.MY_BUCKET, publicUrl: "https://cdn.example.com" } });

// R2 via S3-compatible API (anywhere)
initializeStorage({
  type: "r2",
  r2: { accountId: env.R2_ACCOUNT_ID, bucket: "my-bucket", accessKeyId: "...", secretAccessKey: "...", presignedUrlExpiry: 3600 },
});
```

`createR2Adapter(config)` builds the adapter directly — a `binding` selects bindings mode (streams through the Worker), otherwise S3-compatible credentials enable presigned upload/download. On Workers, prefer R2 — there is no local filesystem. See [Workers deployment](../deployment/workers.md).

## Schema

```typescript
export const filesTable = sqliteTable("files", {
  id: text("id").primaryKey(),
  userId: text("userId").references(() => usersTable.id),
  filename: text("filename").notNull(),
  mimeType: text("mimeType").notNull(),
  size: integer("size").notNull(),
  storagePath: text("storagePath").notNull(),
  url: text("url"),
  status: text("status").notNull().default("pending"),
  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
});
```

## Configuration

`FileResourceConfig` is a **superset of [`ResourceConfig`](../core/resources-and-app.md)** — every regular-resource option (`hooks`, `procedures`, `relations`, `autoRelations`, `fields`, `capabilities`, `auth` as a full scope config with `read`/`create`/`update`/`delete`/`subscribe`/`public`, etc.) plus the storage options below:

```typescript
.fileResource("/files", filesTable, {
  db, id: filesTable.id,
  storage: adapter,                 // override the global adapter
  allowedMimeTypes: ["image/jpeg", "image/png"],
  maxFileSize: 5 * 1024 * 1024,
  validation: { maxSize: 5 * 1024 * 1024, allowedTypes: ["image/jpeg"], blockedTypes: ["application/x-msdownload"] },
  usePresignedUrls: false,
  presignedUrlExpiry: 3600,
  generateKey: (filename, userId) => `${userId}/${Date.now()}-${filename}`,
  auth: { /* full scope config: read/create/update/delete/subscribe/public */ },
  hooks: { onAfterCreate: async (ctx, file) => { /* runs after upload */ } },
  relations: { owner: { resource: "users", schema: usersTable, type: "belongsTo", foreignKey: filesTable.userId, references: usersTable.id } },
});
```

**Validation** runs before any bytes are persisted; a rejected upload returns `400 ValidationError` and writes nothing. **Orphan cleanup**: deleting a record removes the stored blob — storage cleanup is wired through an internal `onAfterDelete` hook (composed with yours), so `DELETE /:id` (and `DELETE /batch`) never leave orphaned objects.

## Endpoints

A file resource exposes the **full resource API** — `GET /` (cursor pagination, `?select`, `?include`, `?filter`), `GET /:id`, `PATCH`/`PUT /:id`, `DELETE /:id`, `GET /count`, `GET /aggregate`, `GET /subscribe`, `POST /rpc/:name` — plus the file-specific routes:

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/` | Upload (multipart/form-data) → the created file record (fires create hooks + pushes an `added` subscription event) |
| `GET` | `/upload-url` | Presigned upload URL (S3/R2) → `{ fileId, uploadUrl, expiresAt }` |
| `POST` | `/:id/confirm` | Confirm a presigned upload completed → the file record |
| `GET` | `/:id/download` | Stream the file or redirect to a presigned URL |
| `DELETE` | `/batch` | Delete many (`{ ids: [...] }`) → `{ deleted }` |

> **Response shapes match regular resources** (no `{ data }` envelope): `GET /` returns `{ items, nextCursor }`, `GET /:id` and the upload/confirm endpoints return the raw record. The bundled `useFile`/`useFiles`/`useFileUpload` client hooks already speak this shape.

### Admin download

In the [admin data explorer](../tooling/admin-ui.md), rows of a file resource show a **Download** action that streams the stored object (admin-gated), so you can fetch any file regardless of the resource's per-user scopes.

### Direct upload

```bash
curl -X POST http://localhost:3000/api/files -F "file=@photo.jpg"
```

### Presigned upload (S3/R2)

```bash
curl "http://localhost:3000/api/files/upload-url?filename=photo.jpg&contentType=image/jpeg"
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @photo.jpg
curl -X POST "http://localhost:3000/api/files/abc123/confirm"
```

## Relating files to resources

```typescript
export const todosTable = sqliteTable("todos", {
  id: text("id").primaryKey(),
  imageId: text("imageId").references(() => filesTable.id, { onDelete: "set null" }),
});

useResource(todosTable, {
  relations: { image: { resource: "files", schema: filesTable, type: "belongsTo", foreignKey: todosTable.imageId, references: filesTable.id } },
});
// GET /api/todos?include=image
```

## Client

```tsx
import { createFileClient } from "covara/client";
import { useFileUpload, useFiles } from "covara/client/react";

const files = createFileClient({ transport: client.transport, resourcePath: "/api/files" });
await files.upload(file, { onProgress: ({ percent }) => console.log(percent) });
await files.uploadWithPresignedUrl(file);

function UploadButton() {
  const { upload, isUploading, progress } = useFileUpload({ resourcePath: "/api/files" });
  return <input type="file" disabled={isUploading} onChange={(e) => e.target.files?.[0] && upload(e.target.files[0])} />;
}
```

See [Client file uploads](../client/files.md).

## Adapter interface

```typescript
interface StorageAdapter {
  upload(key, data, options?): Promise<UploadResult>;
  download(key): Promise<Buffer>;
  downloadStream(key): Promise<Readable>;
  delete(key): Promise<void>;
  deleteMany(keys): Promise<void>;
  exists(key): Promise<boolean>;
  getMetadata(key): Promise<FileMetadata | null>;
  getUrl(key): string | null;
  getDownloadUrl(key, options?): Promise<string | null>;
  getUploadUrl(key, options?): Promise<PresignedUploadResult | null>;
  supportsPresignedUrls(): boolean;
}
```

Globals: `initializeStorage`, `setGlobalStorage`, `getGlobalStorage`, `hasGlobalStorage`.

## Related

- [Client file uploads](../client/files.md) · [Relations](../core/relations.md) · [Workers deployment](../deployment/workers.md)
- [Storage contract](../contracts/storage.md)

---

## Background tasks


Covara ships a distributed task queue backed by the [KV store](./kv.md): Zod-validated task definitions, retry strategies, delayed/cron scheduling, idempotency, concurrency caps, a dead-letter queue, and a Cloudflare Queues adapter for the edge.

## Quick start

```typescript
import {
  defineTask, initializeTasks, getTaskScheduler, getTaskRegistry, startTaskWorkers,
} from "covara/tasks";
import { createKV } from "covara/kv";
import { z } from "zod";

const kv = await createKV({ type: "redis", redis: { url: "redis://localhost" } });
initializeTasks(kv);

const sendEmailTask = defineTask({
  name: "send-email",
  input: z.object({ to: z.string().email(), subject: z.string(), body: z.string() }),
  handler: async (ctx, input) => {
    await sendEmail(input.to, input.subject, input.body);
    return { sent: true };
  },
});

getTaskRegistry().register(sendEmailTask);
await startTaskWorkers(kv, getTaskRegistry(), 3);

const taskId = await getTaskScheduler().enqueue(sendEmailTask, {
  to: "user@example.com", subject: "Welcome!", body: "Thanks for signing up.",
});
```

```mermaid
flowchart LR
  Enqueue[enqueue / schedule] --> Queue[(KV priority queue)]
  Queue --> Worker[worker pool]
  Worker -->|success| Result[result + TTL]
  Worker -->|retry| Queue
  Worker -->|exhausted| DLQ[dead letter queue]
  DLQ -->|dlq.retry| Queue
```

## Defining tasks

```typescript
const myTask = defineTask({
  name: "my-task",
  input: z.object({ data: z.string() }),
  output: z.object({ result: z.number() }),
  handler: async (ctx, input) => { /* ... */ },

  retry: {
    maxAttempts: 5,
    backoff: "exponential",   // "exponential" | "linear" | "fixed"
    initialDelayMs: 1000,
    maxDelayMs: 60000,
    retryOn: (error) => error.name !== "ValidationError",
  },

  timeout: 30000,
  maxConcurrency: 10,          // enforced fleet-wide cap
  priority: 75,                // higher = sooner (0-100)
  debounce: { windowMs: 5000, key: (input) => input.userId },
  idempotencyKey: (input) => `order-${input.orderId}`,
  idempotencyRetentionMs: 24 * 60 * 60 * 1000,
  resultTtlMs: 60 * 60 * 1000,
});
```

### Task context

| Property | Description |
|----------|-------------|
| `taskId` | Unique id |
| `attempt` | Current attempt (1-based) |
| `scheduledAt` / `startedAt` | Timestamps |
| `workerId` | Processing worker |
| `signal` | `AbortSignal` for cancellation |
| `reportProgress(percent, message?)` | Persist progress (0–100, clamped) |

```typescript
handler: async (ctx, input) => {
  for (let i = 0; i < input.rows.length; i++) {
    await importRow(input.rows[i]);
    await ctx.reportProgress((i / input.rows.length) * 100, `row ${i}`);
  }
}
// elsewhere: (await scheduler.getTask(id))?.progress → { percent, message?, updatedAt }
```

While running, the worker writes a heartbeat (`lastHeartbeatAt`, default every 10s) and extends its distributed lock; if the lock can't be extended, the task is aborted via `ctx.signal` and rescheduled.

### Idempotency & concurrency (enforced)

- **Idempotency:** when `idempotencyKey` is set, the first successful completion is recorded in KV. A second execution with the same key within `idempotencyRetentionMs` (default 24h) short-circuits and returns the stored result. Use a distributed KV so this holds across workers.
- **Concurrency:** `maxConcurrency` is enforced via a distributed counter — workers reserve a slot before running and release on completion; over-cap tasks wait for free capacity.

### Result TTL

A completed/failed task carries `resultExpiresAt = completedAt + resultTtlMs` (default 24h) and is deleted lazily on next read. Dead tasks live in the DLQ until purged.

## Scheduling

```typescript
const scheduler = getTaskScheduler();

await scheduler.enqueue(myTask, { data: "hello" });                       // ASAP
await scheduler.schedule(myTask, { data: "hello" }, { delay: 5 * 60_000 }); // delayed
await scheduler.schedule(myTask, { data: "hello" }, { at: new Date("2024-12-25T00:00:00Z") });
await scheduler.schedule(myTask, { data: "urgent" }, { delay: 1000, priority: 100 });
```

### Recurring tasks

```typescript
await scheduler.scheduleRecurring(dailyReportTask, {}, { interval: 60 * 60 * 1000 });
await scheduler.scheduleRecurring(dailyReportTask, {}, { cron: "0 0 * * *", timezone: "UTC" });
await scheduler.scheduleRecurring(weeklyDigestTask, {}, { cron: "0 9 * * 1", timezone: "America/New_York" });
```

**Missed-occurrence catchup** decides what happens when the scheduler comes back after downtime:

| `catchup` | Behavior |
|-----------|----------|
| `"skip"` (default) | Fire once for the current occurrence; drop missed ones |
| `"last"` | Run only the latest missed occurrence |
| `"all"` | One task per missed occurrence, capped at 1000 |

### Managing tasks

```typescript
const task = await scheduler.getTask(taskId);   // status: pending|scheduled|running|completed|failed|dead
await scheduler.cancel(taskId);
await scheduler.getTasks({ status: ["pending", "scheduled"], name: "send-email", limit: 100 });
await scheduler.getQueueDepth();
```

## Workers

```typescript
import { startTaskWorkers, createTaskWorker } from "covara/tasks";

const workers = await startTaskWorkers(kv, registry, 3, {
  concurrency: 5, pollIntervalMs: 1000, lockTtlMs: 30000, heartbeatMs: 10000,
});

const worker = createTaskWorker(kv, registry, { id: "worker-main", concurrency: 10, taskTypes: ["send-email"] });
await worker.start();

worker.pause(); worker.resume();
await worker.drain(30000);                       // stop claiming, wait for in-flight
await worker.stop({ drain: true, timeoutMs: 30000 });
worker.getStats();                               // { activeTasks, processedCount, failedCount, uptime, ... }
```

## Retry strategies

```typescript
retry: { backoff: "exponential", initialDelayMs: 1000, maxDelayMs: 60000 } // 1,2,4,8,16s (cap 60), +10-20% jitter
retry: { backoff: "linear", initialDelayMs: 2000, maxDelayMs: 30000 }      // 2,4,6,8s (cap 30)
retry: { backoff: "fixed", initialDelayMs: 5000 }                          // 5,5,5s
retry: { maxAttempts: 3, retryOn: (e) => e.name !== "ValidationError" }     // conditional
```

## Dead letter queue

Tasks exceeding `maxAttempts` go to the DLQ.

```typescript
import { createDeadLetterQueue } from "covara/tasks";
const dlq = createDeadLetterQueue(kv, requeue);

await dlq.list(100, 0);
await dlq.get(taskId);
const newId = await dlq.retry(taskId, "ops@example.com"); // fresh task, preserves lineage
await dlq.retryAll({ limit: 100, replayedBy: "ops@example.com" });
await dlq.purge(7 * 24 * 60 * 60 * 1000);
await dlq.count();
await dlq.audit(100); // [{ originalTaskId, newTaskId, replayedAt, replayedBy?, replayCount }]
```

**Replay lineage:** a replay creates a fresh task (new id, reset attempts) while preserving `originalTaskId` (always the first task), `replayCount`, `replayedFromDlqAt`, and `replayedBy`, and appends a durable audit entry.

**Alerting:** provide `onDlqEnqueue` (on the worker config or the DLQ) to be paged when a task is parked. Callback failures never affect persistence.

```typescript
await startTaskWorkers(kv, registry, 3, {
  onDlqEnqueue: async (entry) => alert(`Task ${entry.taskId} dead: ${entry.reason}`),
});
```

## Cloudflare Queues

On Workers there is no long-lived poller — use the Queues adapter. Retries are delegated to Cloudflare (`message.retry()`); idempotency, DLQ, and result storage still use your [KV](./kv.md).

```typescript
import { createCloudflareQueueProducer, createQueueConsumer, getTaskRegistry } from "covara/tasks";
import { createDurableObjectKV } from "covara/kv";

export default {
  async fetch(req, env) {
    const producer = createCloudflareQueueProducer(env.TASK_QUEUE);
    return new Response(await producer.enqueue(sendEmailTask, { to: "a@b.com", subject: "Hi", body: "..." }));
  },
  async queue(batch, env) {
    const consumer = createQueueConsumer({
      kv: createDurableObjectKV(env.KV_DO),
      registry: getTaskRegistry(),
      onDlqEnqueue: async (entry) => { /* alert */ },
    });
    await consumer.process(batch);
  },
};
```

```toml
[[queues.producers]]
queue = "tasks"
binding = "TASK_QUEUE"

[[queues.consumers]]
queue = "tasks"
max_batch_size = 10
max_retries = 3
dead_letter_queue = "tasks-dlq"
```

The producer maps `delay`/`at` to the queue's `delaySeconds`. DLQ entries produced by the consumer are **not** auto-requeued — replay with `dlq.retry(...)` or use a Cloudflare dead-letter queue binding. See [Workers deployment](../deployment/workers.md).

## Resource-trigger hooks

Fire tasks automatically when resources change:

```typescript
import { createTaskTriggerHooks, composeHooks } from "covara/tasks";

const taskHooks = createTaskTriggerHooks({
  onCreate: [
    { task: sendWelcomeEmailTask, when: (data) => data.role === "user" },
    { task: auditLogTask, delay: 1000 },
  ],
  onUpdate: [{ task: auditLogTask, transform: (data) => ({ changes: data }) }],
  onDelete: [{ task: auditLogTask }],
});

useResource(usersTable, { id: usersTable.id, db, hooks: composeHooks(taskHooks, { /* ... */ }) });
```

`ResourceTaskTrigger`: `{ task, when?(data), transform?(data), delay? }`.

## Recurring scheduler management

```typescript
import { createRecurringManager, startRecurringScheduler } from "covara/tasks";

const recurring = createRecurringManager(kv);
const scheduleId = await recurring.create(dailyReportTask, {}, { cron: "0 0 * * *", timezone: "America/New_York" });
await recurring.pause(scheduleId); await recurring.resume(scheduleId); await recurring.delete(scheduleId);

const stop = startRecurringScheduler(kv, async (name, input) => {
  const task = registry.get(name);
  return task ? scheduler.enqueue(task, input) : "";
}, 1000);
```

## Best practices

1. Always set `timeout`. 2. Use `idempotencyKey` for payments/critical ops. 3. Don't retry non-transient errors (`retryOn`). 4. Alert on the DLQ. 5. Reserve high priority for time-sensitive work. 6. Scale workers horizontally. 7. Use a distributed KV (Redis / Durable Object) in production.

## Related

- [KV store](./kv.md) · [Email](./email.md) · [Procedures & hooks](../core/procedures.md)
- [Workers deployment](../deployment/workers.md) · [Tasks contract](../contracts/tasks.md)

---

## Quick Start


There are two ways to get going: scaffold a fresh project with the CLI, or add Covara to an app you already have.

## Option 1 — Scaffold with the CLI

The fastest path is the `covara create` scaffolder:

```bash
npx covara create my-app                          # Node + SQLite (default)
npx covara create my-app --template cloudflare    # Cloudflare Workers + D1
npx covara create my-app --db postgres            # PostgreSQL
```

:::tip Want a full-stack app? Add `--frontend react`

```bash
npx covara create my-app --frontend react
```

This is the easiest way to get a complete real-time full-stack application. On top of the API it scaffolds a **React + Vite** SPA wired to the typed client with [`useLiveList`](./client/react-hooks.md) — so the UI updates in real time out of the box — and a **single-process dev server**: `npm run dev` serves the SPA (with HMR), the API (`/api`), and the admin UI (`/__covara`) on one origin, while live-regenerating the typed client. No proxy, no second terminal.

:::

| Flag | Values | Default |
|------|--------|---------|
| `--frontend` | `react`, `none` | `none` |
| `--template` | `node`, `cloudflare` | `node` |
| `--db` | `sqlite`, `postgres` | `sqlite` |
| `--no-install` | skip dependency install | — |

This generates a complete project: a Drizzle schema, database setup, a `drizzle.config.ts`, a running server, the right `package.json` scripts, and — with `--frontend react` — a ready-to-edit React frontend. See the [CLI reference](./tooling/cli.md) for everything it produces.

```bash
cd my-app
npm run dev       # start the server — covara dev creates/updates tables automatically
```

`npm run dev` runs [`covara dev`](./tooling/cli.md#covara-dev), which auto-applies additive schema changes on start (creating your tables on first run), so there's no separate `npm run db:push`. Use `db:push` only for destructive changes or in CI.

## Option 2 — Add to an existing app

### Install

```bash
npm install covara drizzle-orm @libsql/client zod
```

`drizzle-orm`, `zod`, and (for the client hooks) `react` are peer dependencies — install the versions your project uses.

### 1. Define your schema

```typescript
// src/schema.ts
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";

export const usersTable = sqliteTable("users", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  email: text("email").notNull().unique(),
  name: text("name").notNull(),
  role: text("role").default("user"),
  createdAt: integer("createdAt", { mode: "timestamp" }),
});
```

### 2. Set up the database

```typescript
// src/db.ts
import { drizzle } from "drizzle-orm/libsql";
import { createClient } from "@libsql/client";

const client = createClient({ url: "file:./data.db" });
export const db = drizzle(client);
```

### 3. Create the API

```typescript
// src/main.ts
import { createCovara } from "covara";
import { startServer } from "covara/node";
import { usersTable } from "./schema.js";
import { db } from "./db.js";

const app = createCovara({ cors: true }).resource(usersTable, {
  id: usersTable.id,
  db,
  auth: { public: true },
});

const server = await startServer(app, { port: 3000 });
console.log(`Server running on http://localhost:${server.port}`);
```

That's it. You now have a full REST API:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/users` | List users (paginated, filtered, ordered) |
| `GET` | `/api/users/:id` | Get a single user |
| `POST` | `/api/users` | Create a user |
| `PATCH` | `/api/users/:id` | Update a user (partial) |
| `PUT` | `/api/users/:id` | Replace a user |
| `DELETE` | `/api/users/:id` | Delete a user |
| `GET` | `/api/users/count` | Count users (filtered) |
| `GET` | `/api/users/aggregate` | [Aggregation queries](./core/aggregations.md) |
| `GET` | `/api/users/aggregate/subscribe` | [Live aggregation (SSE)](./realtime/aggregate-subscriptions.md) |
| `GET` | `/api/users/subscribe` | [Real-time subscription (SSE)](./realtime/subscriptions.md) |
| `GET` | `/api/users/search` | [Full-text search](./core/search.md) (when configured) |
| `POST` | `/api/users/batch` | [Batch create](./core/batch.md) |
| `PATCH` | `/api/users/batch` | Batch update |
| `DELETE` | `/api/users/batch` | Batch delete |
| `POST` | `/api/users/rpc/:name` | [RPC procedures](./core/procedures.md) |

Health endpoints (`/healthz`, `/readyz`) and the OpenAPI spec (under `/__covara`) are mounted by default. See [Generated endpoints](./core/crud.md) for the full reference.

## The `createCovara` factory

`createCovara(options)` returns a `CovaraApp` (which extends `Hono`) with sensible defaults: RFC 7807 error handling, health endpoints, OpenAPI generation, and security headers.

```typescript
const app = createCovara({
  basePath: "/api",         // resource mount prefix (default: "/api")
  cors: true,               // or a hono/cors config object
  auth: { router, middleware }, // result of useAuth()
  middleware: [],           // extra Hono middleware applied to all routes
  observability: true,      // request/subscription metrics
  health: true,             // /healthz + /readyz (default: enabled)
  adminUI: true,            // admin dashboard at /__covara (default: disabled)
  openapi: true,            // OpenAPI spec at /__covara (default: enabled)
})
  .resource(usersTable, { id: usersTable.id, db })             // mounts at /api/users
  .resource("/people", usersTable, { id: usersTable.id, db }); // custom path
```

`.resource()` is chainable and infers the mount path from the table name unless you pass one explicitly. Full option reference: **[Resources & the app factory](./core/resources-and-app.md)**.

## Using a plain Hono app

`useResource` returns an ordinary `Hono` router, so you can compose everything yourself instead of using the factory:

```typescript
import { Hono } from "hono";
import { useResource, errorHandler, notFoundHandler } from "covara";

const app = new Hono();
app.onError(errorHandler);
app.notFound(notFoundHandler);

app.route("/api/users", useResource(usersTable, { id: usersTable.id, db }));
```

## Connect the client

```typescript
// client.ts
import { getOrCreateClient } from "covara/client";

export const client = getOrCreateClient({
  baseUrl: location.origin,
  credentials: "include",
  offline: true, // optimistic updates + offline queue
});
```

```tsx
// App.tsx
import { useAuth, useLiveList } from "covara/client/react";

function App() {
  const { isAuthenticated } = useAuth<User>();
  if (!isAuthenticated) return <LoginPage />;
  return <UserList />;
}

function UserList() {
  const { items } = useLiveList<User>("/api/users", { orderBy: "name:asc" });
  return {items.map((u) => {u.name})};
}
```

The list updates in real time as anyone mutates `/api/users`. Continue with the **[Client library](./client/overview.md)**.

## Next steps

- **[Tutorial](./tutorial.md)** — build a complete real-time todo app, server and client.
- **[Resources](./core/resources-and-app.md)** — every configuration option in depth.
- **[Authentication](./auth/overview.md)** — add login, sessions, scopes.
- **[Deployment](./deployment/node.md)** — ship to Node or Cloudflare Workers.

---

## Aggregate subscriptions


`GET /aggregate/subscribe` streams an [aggregation](../core/aggregations.md) result and **recomputes + re-emits it whenever the resource is mutated**. Because the result is recomputed from the database each time, it stays exact for any `groupBy`/`having` combination — there is no incremental-aggregation drift.

This is recompute-on-change, not row tracking — a fundamentally different model from [row subscriptions](./subscriptions.md).

## React

```tsx
import { useLiveAggregate } from "covara/client/react";

function TodoStats() {
  const { groups, isLive } = useLiveAggregate("/api/todos", {
    groupBy: ["completed"],
    count: true,
  });
  const completed = groups.find((g) => g.key?.completed)?.count ?? 0;
  return {completed} completed {isLive ? "🟢" : "…"};
}
```

## Imperative client

```typescript
const todos = client.resource<Todo>("/api/todos");

const sub = todos.subscribeAggregate(
  { groupBy: ["status"], count: true, sum: ["amount"] },
  {
    onData: (result) => console.log(result.groups),
    onConnectionChange: (connected) => console.log("live:", connected),
  }
);

sub.unsubscribe();
```

## Semantics

- **On connect** the server emits `connected`, then one `aggregate` event with the current snapshot (even when the resource is empty).
- **Scope-aware skipping.** Each subscription carries its compiled read [scope](../auth/scopes.md) + `filter` and is handed the changed rows — the new row for inserts, new **and** previous state for updates, and the deleted rows' prior content for deletes. It **skips the recompute when no changed row is in its scope**, so a per-user aggregate like `userId==<me>` does **not** recompute on other users' inserts, updates, or deletes. This keeps cost bounded with many concurrent per-user subscriptions. Unscoped/global aggregates always recompute.
- **Safe fallbacks.** Raw-SQL/external [invalidations](./mutation-tracking.md) and cross-process notifications fall back to an unconditional recompute (row data isn't shipped over pub/sub). Skipping is applied only when provably safe; the result dedup below is the correctness backstop, so over-recomputing never yields a wrong result.
- **Debounce + dedup.** Bursts of mutations coalesce into a single recompute (`sse.aggregateDebounceMs`, default **150 ms**). An event is suppressed when the recomputed result matches the previous one under an **order-independent** comparison (group order is normalized, since `GROUP BY` has no stable `ORDER BY`).
- **Cross-process.** In multi-process deployments, mutations fan out to watchers via the [KV](../platform/kv.md) pub/sub channel (the same KV that powers row subscriptions).
- **No resume.** The read scope and `filter` are resolved once at connect and reused for the connection's life. Aggregate subscriptions don't support `resumeFrom`/catchup — a reconnect simply re-emits the current snapshot.

## Server tuning

```typescript
useResource(todos, {
  db,
  id: todos.id,
  sse: { aggregateDebounceMs: 150 },
});
```

## How it works internally

`registerAggregateWatcher(resource, cb)` registers a local watcher; the mutation push paths call `notifyAggregateWatchers(resource, changedRows?)` (local + cross-process via the `covara:aggregate` KV channel). Each watcher decides whether to recompute based on its scope and the changed rows.

## Related

- [Aggregations](../core/aggregations.md) · [Subscriptions](./subscriptions.md) · [Mutation tracking](./mutation-tracking.md)
- [React hooks](../client/react-hooks.md) · [KV store](../platform/kv.md)

---

## Changelog


The changelog is the backbone of Covara's [subscriptions](./subscriptions.md). Every mutation — through a generated endpoint, an [RPC procedure](../core/procedures.md), or a [tracked](./mutation-tracking.md) custom route — appends an entry with a **monotonic sequence number**. Subscriptions read the changelog to deliver ordered, resumable deltas.

## Why it exists

- **Reliable delivery.** Clients track their last received `seq`. On reconnect they resume from it, so no events are silently lost.
- **Gap detection.** If the rolling window has advanced past a client's `seq` (it was offline too long), the server sends an `invalidate` event and the client refetches from a consistent snapshot.
- **Decoupling.** Producers (any mutation path) and consumers (any subscription) communicate only through sequence numbers, which is what makes [cross-instance fan-out](../deployment/workers.md#scaling-across-instances) work over a shared [KV](../platform/kv.md).

## Entry shape

```typescript
interface ChangelogEntry {
  resource: string;          // e.g. "todos"
  type: "create" | "update" | "delete";
  objectId: string;          // affected id, or "*" for raw-SQL/bulk mutations
  object?: unknown;          // new/updated row (absent for invalidate-only entries)
  previousObject?: unknown;  // prior state for updates/deletes
  timestamp: number;
  seq: number;               // monotonic sequence number
}
```

Entries with `objectId: "*"` (raw SQL, batch, external mutations) carry no row detail, so subscribers receive an `invalidate` rather than a precise `added`/`changed`/`removed`.

## Storage & rolling window

The changelog keeps a configurable maximum number of recent entries (a rolling window) in the [KV store](../platform/kv.md). Older entries age out; a client resuming from a sequence below the window's floor gets `invalidate` instead of a precise replay.

Subscription storage is **sharded per resource** (`covara:subs:byres:<resource>` plus a `covara:subs:resources` index, with subscription IDs embedding their resource as `<uuid>:<resource>`), so a mutation only loads the mutated resource's subscriptions rather than scanning all of them.

## Programmatic access

```typescript
import { changelog } from "covara";
```

The `changelog` export exposes the append/read primitives the framework uses internally; most applications never touch it directly and instead rely on [`trackMutations`](./mutation-tracking.md) and the generated endpoints to populate it.

## Related

- [Subscriptions](./subscriptions.md) · [Mutation tracking](./mutation-tracking.md) · [KV store](../platform/kv.md)
- [Subscriptions contract](../contracts/subscriptions.md) — ordering, resume, and delivery guarantees

---

## Mutation tracking


`trackMutations` wraps a Drizzle database so that **every mutation — even from custom routes — records to the [changelog](./changelog.md), pushes to [subscribers](./subscriptions.md), and invalidates the query cache** automatically. Generated resource endpoints already do this; `trackMutations` extends it to your own code.

```typescript
import { drizzle } from "drizzle-orm/libsql";
import { trackMutations } from "covara";
import * as schema from "./schema";

const baseDb = drizzle(/* ... */);

export const db = trackMutations(baseDb, {
  todos: { table: schema.todosTable, id: schema.todosTable.id },
  users: { table: schema.usersTable, id: schema.usersTable.id },
});

await db.insert(schema.todosTable).values({ title: "New" }).returning();
// ^ recorded in the changelog, subscribers notified
```

## How it works

A `Proxy` intercepts mutations at two fidelity levels:

| Pattern | `previousObject` | Subscription event |
|---------|------------------|--------------------|
| `db.insert(t).values(d).returning()` | n/a | `added` |
| `db.update(t).set(d).where(...).returning()` | captured | `changed` |
| `db.delete(t).where(...)` | captured | `removed` |
| `db.run(sql\`INSERT ...\`)` / `db.execute(...)` | no | `invalidate` |
| `db.batch([...])` | no | `invalidate` (per detected statement) |
| `recordExternalMutation(...)` | no | `invalidate` |

Builder-pattern mutations get full row-level events; raw SQL and batch statements are detected by introspecting compiled SQL and recorded as a coarse `invalidate` (`objectId: "*"`).

## Configuration

```typescript
const trackedDb = trackMutations(baseDb, tables, {
  onMutation: (entry) => {},                 // builder-pattern mutations
  onRawSqlMutation: (resource, type) => {},  // raw SQL mutations
  skipTables: ["audit_logs", "sessions"],
  trackTransactions: true,    // default true
  capturePreviousState: true, // default true
  pushToSubscriptions: true,  // default true
  cache: { enabled: true, ttl: 60000 },      // query cache (below)
});
```

### Table registration

```typescript
trackMutations(baseDb, {
  todos: { table: todosTable, id: todosTable.id },
  users: { table: usersTable, id: usersTable.id, resourceName: "api-users" }, // custom name
});
```

## In procedures

The `ctx.db` passed to [procedure handlers](../core/procedures.md) is automatically tracked for the current resource. For multi-table procedures, pass a pre-wrapped tracked db as `config.db` (it won't be double-wrapped). See [Procedures](../core/procedures.md#multi-table-tracking).

## Custom routes

```typescript
import { requireUser } from "covara";

app.post("/api/custom-action", async (c) => {
  const user = requireUser(c);
  const [todo] = await db.insert(todosTable).values({ title: "x", userId: user.id }).returning();
  return c.json(todo); // tracked, subscribers notified
});
```

## Transactions (commit-gated)

```typescript
await db.transaction(async (tx) => {
  const [todo] = await tx.insert(todosTable).values({ title: "Todo" }).returning();
  await tx.update(usersTable).set({ todoCount: sql`todoCount + 1` }).where(eq(usersTable.id, userId));
});
```

Side effects (changelog entries, subscription pushes, cache invalidations) are **buffered and only emitted after commit**. If the callback throws and rolls back, buffered effects are discarded — subscribers never see an event for state that was never persisted. Likewise, a failed mutation records nothing.

## Disable tracking temporarily

```typescript
await db.withoutTracking(async (db) => {
  await db.insert(auditLogsTable).values({ action: "login" }); // not tracked
});
```

## Notifying external writers

When something outside the tracked db mutates a table — a cron job, another service, a manual edit, or a CDC pipeline — call `recordExternalMutation`. It appends a changelog entry, invalidates the cache, and sends subscribers an `invalidate`:

```typescript
import { recordExternalMutation } from "covara";

await recordExternalMutation("todos", "update", { objectId: "todo-1" });
await recordExternalMutation("todos", "delete"); // objectId defaults to "*"
```

This is the portable alternative to database-specific change data capture. For cross-instance fan-out, initialize a distributed [KV](../platform/kv.md).

## Query caching

Cache `SELECT` queries with automatic invalidation on mutation:

```typescript
const db = trackMutations(baseDb, tables, {
  cache: {
    enabled: true,
    ttl: 60000,
    keyPrefix: "cache:",
    tables: { todos: { ttl: 30000 }, users: { enabled: false } },
  },
});
```

**Join-aware invalidation:** a cached query is tagged with **every** table it references (including joined tables), so a mutation to any of them invalidates the result — not just the `FROM` table.

```typescript
import { invalidateCache, invalidateAllCache } from "covara";
await invalidateCache("todos");
await invalidateAllCache();
```

## Avoiding double-tracking

When both `trackMutations` and `useResource` operate on the same table, `useResource` already records its own changelog entries. Use `withoutTracking` for internal DB calls in hooks that shouldn't be tracked separately.

## API reference

```typescript
function trackMutations<TDb>(db: TDb, tables: Record<string, TableRegistration>, config?: TrackMutationsConfig): TrackedDatabase<TDb>;

interface TableRegistration { table: Table; id: AnyColumn; resourceName?: string }

interface TrackedDatabase<TDb> extends TDb {
  withoutTracking<T>(fn: (db: TDb) => Promise<T>): Promise<T>;
}
```

## Related

- [Changelog](./changelog.md) · [Subscriptions](./subscriptions.md) · [Procedures](../core/procedures.md)
- [Track-mutations contract](../contracts/track-mutations.md)

---

## Subscriptions


Covara delivers real-time updates over **Server-Sent Events (SSE)**, backed by a [changelog](./changelog.md) so delivery is reliable and resumable. Every resource exposes `GET /subscribe`.

```mermaid
sequenceDiagram
  participant C as Client
  participant S as Server
  participant L as Changelog
  C->>S: GET /subscribe?filter=...
  S-->>C: connected (seq N)
  S-->>C: existing events (snapshot)
  Note over C,S: any mutation anywhere
  S->>L: append entry (seq N+1)
  L-->>S: notify matching subscriptions
  S-->>C: added / changed / removed (seq N+1)
  Note over C,S: disconnect → reconnect
  C->>S: GET /subscribe?resumeFrom=N+1
  S-->>C: events since N+1 (or invalidate on gap)
```

## React (recommended)

```tsx
import { useLiveList } from "covara/client/react";

function UserList() {
  const { items, status, statusLabel, mutate } = useLiveList<User>(
    "/api/users",
    { filter: 'status=="active"' }
  );
  // status: "loading" | "live" | "reconnecting" | "offline" | "error"
  return (
    <>
      Status: {statusLabel}
      {items.map((u) => {u.name})}
    </>
  );
}
```

See [Live queries](../client/live-queries.md) and [React hooks](../client/react-hooks.md).

## Low-level client API

```typescript
const users = client.resource<User>("/api/users");

const sub = users.subscribe(
  { filter: 'status=="active"' },
  {
    onAdded: (user, meta) => {}, // meta.optimisticId set if from an optimistic create
    onChanged: (user) => {},
    onRemoved: (id) => {},
    onConnected: (seq) => {},
    onDisconnected: () => {},
    onInvalidate: () => {},
    onError: (err) => {},
  }
);

sub.reconnect();
sub.resumeFrom(lastSeq);
sub.unsubscribe();
```

## Event types

| Type | Payload | Meaning |
|------|---------|---------|
| `existing` | `{ seq, object }` | One per existing item on connect (snapshot). |
| `added` | `{ seq, object }` | A new item entered the filter. |
| `changed` | `{ seq, object }` | An item was updated (still in filter). |
| `removed` | `{ seq, objectId }` | An item was deleted or left the filter. |
| `invalidate` | `{ seq, reason }` | Refetch — sequence gap, auth change, or backpressure. |

When an update moves an item across the filter boundary: enters → `added`, stays → `changed`, leaves → `removed`.

## Hybrid fetch + subscribe

Sending every existing item on connect is wasteful for large sets. The hybrid model fetches the initial page via `GET`, then subscribes with `skipExisting=true` so only deltas stream. `useLiveList` does this automatically.

Manual:

```typescript
const { items } = await users.list({ limit: 20, orderBy: "name" });
const sub = users.subscribe(
  { skipExisting: true, knownIds: items.map((i) => i.id) },
  { onAdded: () => {}, onChanged: () => {}, onRemoved: () => {} }
);
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `skipExisting` | boolean | Don't send `existing` events on connect. |
| `knownIds` | comma-separated | IDs the client already has, registered for change tracking. |

With `skipExisting` and no `knownIds`, the server queries matching IDs itself to register them.

## Subscription modes (paginated views)

With a `limit`, you must decide how new items from **other** clients interact with the visible page. `subscriptionMode` controls it:

| Mode | New items | Updated items | Removed | Use case |
|------|-----------|---------------|---------|----------|
| `strict` | only your own creates | cached only | cached | Tables, admin dashboards |
| `sorted` | shown in sort order | cached only | cached | Collaborative lists, kanban |
| `append` | shown at end | cached only | cached | Chat, activity logs |
| `prepend` | shown at start | cached only | cached | Notifications, feeds |
| `live` | all | all | all known | Real-time dashboards |

**Default:** `strict` when `limit` is set, `live` otherwise.

`subscriptionMode` controls how a paginated list **renders** server-pushed changes; the subscription itself is scoped by your `filter` + auth scope (not by the loaded page window), so each client receives in-scope events and the chosen mode decides what to show.

```tsx
useLiveList<Task>("/api/tasks", { limit: 20, subscriptionMode: "sorted", orderBy: "priority:desc" });
useLiveList<Message>("/api/messages", { limit: 50, subscriptionMode: "append", orderBy: "createdAt:asc" });
```

## Relations in events

Pass `include` to receive related data on `added`/`changed`:

```bash
GET /api/todos/subscribe?include=category,tags
```

```tsx
const { items } = useLiveList<TodoWithRelations>("/api/todos", { include: "category,tags", orderBy: "position" });
```

When you optimistically change a foreign key, the stale relation is cleared immediately and refilled when the server confirms. For instant UI, look the relation up from locally cached data (`todo.category ?? categories.find(c => c.id === todo.categoryId)`).

## Mutations from custom routes

Mutations through generated endpoints record to the changelog automatically. For custom Hono routes, wrap the db with [`trackMutations`](./mutation-tracking.md):

```typescript
const db = trackMutations(baseDb, { todos: { table: todosTable, id: todosTable.id } });

app.post("/api/custom-action", async (c) => {
  const [todo] = await db.insert(todosTable).values({ title: "x" }).returning();
  return c.json(todo); // subscribers notified
});
```

## Reconnection

The subscription manager reconnects with exponential backoff + jitter, heartbeats to detect dead connections, and cleans up on page unload. On reconnect it resumes from the last sequence; if too many changes occurred (a gap), the server sends `invalidate` and the client refetches.

```typescript
users.subscribe({ resumeFrom: lastSeq });
```

## Backpressure

Each connection has a bounded outbound queue. When a slow consumer fills it, the resource's policy applies instead of unbounded buffering:

```typescript
useResource(todos, {
  db,
  id: todos.id,
  sse: {
    maxQueueBytes: 65536,         // high-water mark (default 64 KB)
    onBackpressure: "invalidate", // "invalidate" (default) | "disconnect" | "drop"
    heartbeatMs: 30000,
    scopeRecheckMs: 30000,        // re-resolve each sub's auth scope this often (default 30s; 0 disables)
    maxSubscriptionsPerUser: 50,
    maxSubscriptionsPerIP: 100,
    maxTotalSubscriptions: 10000,
  },
});
```

- `invalidate` — send one `invalidate` so the client refetches from a consistent state.
- `disconnect` — close; the client reconnects and resumes from its last sequence.
- `drop` — skip the event for this connection (it may miss updates until the next sync).

## Auth

Subscriptions respect [auth scopes](../auth/scopes.md) (`auth.subscribe`). If a user's auth expires, the server sends `invalidate` with reason `"Authentication expired"`.

A subscription's scope is otherwise resolved once at connect. To catch **out-of-band** permission changes (e.g. losing org membership without any row mutation), each subscription periodically re-resolves its scope every `sse.scopeRecheckMs` (default 30s, `0` disables) and emits `removed`/`added` for rows that left/entered scope. This reflects changes the scope resolver recomputes on each call (e.g. resolvers that query current membership/roles); a resolver reading only static fields off the connect-time user still requires a reconnect. See the [subscriptions contract](../contracts/subscriptions.md#scope-changes).

## Cross-instance fan-out

Subscriptions work across instances when every instance shares a distributed [KV](../platform/kv.md) (Redis or Durable Object KV) initialized with `initializeKV`, which auto-wires cross-process event fan-out. See [Scaling across instances](../deployment/workers.md#scaling-across-instances).

## Related

- [Changelog](./changelog.md) · [Mutation tracking](./mutation-tracking.md) · [Aggregate subscriptions](./aggregate-subscriptions.md)
- [Live queries](../client/live-queries.md) · [Subscriptions contract](../contracts/subscriptions.md)

---

## Admin UI


Covara ships a built-in admin dashboard served at `/__covara/ui`. It's **disabled by default** — enable it by passing `adminUI` to [`createCovara`](../core/resources-and-app.md).

```typescript
const app = createCovara({
  adminUI: {
    title: "My App Admin",
    metricsCollector,
    security: {
      mode: isProduction() ? "production" : "development",
      auth: { disabled: !isProduction() },
    },
    dataExplorer: { enabled: true, readOnly: false, maxLimit: 100, excludeFields: { users: ["passwordHash"] } },
    kvInspector: { enabled: true, kv: getGlobalKV(), readOnly: false },
    userManager: { /* listUsers, getUser, createUser, updateUser, deleteUser */ },
    sessionManager: { /* listSessions, revokeSession, ... */ },
  },
});
```

`adminUI: true` enables it with defaults; an object configures the panels below.

## Panels

| Panel | What it shows |
|-------|---------------|
| **Dashboard** | Overview: request/error stats, subscription counts, health. |
| **Resources** | Every registered resource, its columns, config, and generated endpoints. |
| **Data explorer** | Browse/filter/edit rows per resource (read-only or read-write), with excluded fields. Bypasses resource auth scopes. |
| **API explorer** | Try endpoints interactively. Runs as the verified admin and bypasses resource auth scopes. |
| **Filter tester** | Build and validate [RSQL filters](../core/filtering.md) against a resource. |
| **Requests** | Live request [metrics](./middleware.md) (recent, slow, by path). |
| **Subscriptions** | Active SSE [subscriptions](../realtime/subscriptions.md). |
| **Changelog** | Recent [changelog](../realtime/changelog.md) entries. |
| **Tasks** | [Background task](../platform/tasks.md) queue, status, DLQ. |
| **Users** | Manage users (via `userManager` callbacks). |
| **Sessions** | List and revoke [sessions](../auth/sessions.md) (via `sessionManager`). |
| **KV inspector** | Inspect the [KV store](../platform/kv.md). |
| **Errors / audit** | Error log and admin audit entries. |

## Security

```typescript
security: {
  mode: "development" | "staging" | "production",
  auth: { disabled: !isProduction() },
}
```

In development you can leave auth disabled for convenience; in **production, protect it** (the UI gates on the configured auth and serves its own self-only CSP regardless of your global [security headers](../auth/security-headers.md)). `dataExplorer.readOnly` and `kvInspector.readOnly` let you expose a safe read-only view in staging/production.

### Scope bypass

Both the Data explorer and the API explorer **bypass the per-resource [auth scopes](../auth/scopes.md)** so an admin sees and edits every row, not just their own. The Data explorer queries the database directly. The API explorer forwards the request to the real resource endpoints with a non-secret marker header (`x-covara-admin-bypass`); the resource layer then **re-verifies that the forwarded request's authenticated user is an admin** before honoring it. "Admin" is decided by the same `security` config that gates the UI (`requireRole` / `authorization` / `authorize`, or the admin `apiKey`) — no separate credential.

Because the marker carries no secret, a leaked or guessed marker is useless to a non-admin: the request still runs under normal scope enforcement. Bypass also requires that an admin predicate is registered (it is, whenever you mount the admin UI via `createCovara`); standalone `useResource` mounts never bypass. Every bypassed API-explorer request is recorded in the admin **audit** log (`api_explorer_execute`). Locking down the UI's auth in production therefore also locks down scope bypass.

> An admin can also opt into the bypass on a direct API call by sending the `x-covara-admin-bypass: 1` header — it only takes effect for users the admin predicate accepts, and is audited. With `apiKey` admin auth the marker is honored when the request carries that key; with role/`authorize`-based auth it is honored when the authenticated user passes the same check.

### User impersonation

Where scope bypass lets an admin see *everything*, **impersonation** is the inverse: it runs requests **as a specific user, under that user's per-operation [auth scopes](../auth/scopes.md)** — a "see (and act) exactly as they would" tool. Click **Impersonate** on a user in the Users panel and a global amber badge ("Impersonating …") appears across the API Explorer, Filter Tester, and Data Explorer; the **✕** on the badge clears it. Near filter inputs a contextual badge shows the scope that user's request would carry (e.g. `appending filter userId==123`), resolved from the resource's `auth` config for the relevant operation.

Impersonation is **full read-write** — mutations execute and are attributed to the impersonated user — so use it deliberately; every impersonated request is recorded in the admin **audit** log (`impersonate_execute` / `data_explorer_list`) carrying *both* the real admin id and the impersonated user id.

Security model (mirrors scope bypass): the API Explorer forwards a non-secret marker header `x-covara-impersonate: <userId>`. The resource layer honors it **only when the forwarded request's real authenticated user passes the admin predicate**, then swaps the effective user to the target for scope resolution and write attribution. A leaked/forged marker from a non-admin is inert. Impersonation **replaces** scope bypass and never stacks with it — impersonating an admin grants only that admin's scope, never full bypass. Impersonation requires the admin UI's `userManager` to be configured (so the target user can be loaded); without it, impersonation is inert.

## Wiring live data

The UI reads from the same [metrics collector](./middleware.md) and [KV](../platform/kv.md) your app uses. Pass a `metricsCollector` (from `createMetricsCollector`) so the Requests/Dashboard panels show real traffic, and `getGlobalKV()` to the KV inspector. The `userManager`/`sessionManager` callbacks bridge the Users/Sessions panels to your tables and auth adapter — see the [example app](https://github.com/kahveciderin/covara/tree/master/example) for a complete wiring.

## Health endpoints

`createCovara` also mounts `/healthz` and `/readyz` (configurable via the `health` option). See [Health checks](../platform/health.md).

## Related

- [Middleware](./middleware.md) · [OpenAPI](./openapi.md) · [Health checks](../platform/health.md) · [KV store](../platform/kv.md)

---

## CLI


The `covara` CLI scaffolds projects, runs a dev loop that streams schema changes to your database, manages database connection profiles, and browses/imports/exports data.

## `covara create`

```bash
npx covara create my-app                          # Node + SQLite (default), backend only
npx covara create my-app --frontend react         # + a live React SPA, served by the backend
npx covara create my-app --template cloudflare    # Cloudflare Workers + D1
npx covara create my-app --db postgres            # PostgreSQL
```

| Flag | Values | Default |
|------|--------|---------|
| `--template` | `node`, `cloudflare` | `node` |
| `--db` | `sqlite`, `postgres` | `sqlite` |
| `--frontend` | `react`, `none` | `none` |
| `--no-install` | skip dependency install | — |

Generated projects are deploy-ready. Alongside your source and schema, the scaffolder writes:

- **Node:** a `Dockerfile` and `docker-compose.yml` (app + Redis, plus a Postgres service when `--db postgres`) and a `.dockerignore`.
- **Cloudflare:** a complete `wrangler.toml` — `nodejs_compat`, a `[[d1_databases]]` binding, a commented `[[kv_namespaces]]` block, and the `CovaraKVDurableObject` [Durable Object KV](../deployment/durable-object-kv.md) binding + migration.
- A GitHub Actions CI workflow (`.github/workflows/ci.yml`) that installs, lints, tests, and builds.
- **Node:** a typed [`createEnv`](../deployment/environment-variables.md) schema in `src/env.ts` — the generated server reads config via `env.X`, never `process.env`.
- `.env.example` documenting the expected [environment variables](../deployment/environment-variables.md).
- An `AGENTS.md` orienting AI coding agents — project layout, how resources map to endpoints, the commands, and links to these docs plus the machine-readable [`llms.txt`](https://kahveciderin.github.io/covara/llms.txt) / [`llms-full.txt`](https://kahveciderin.github.io/covara/llms-full.txt).

```bash
cd my-app
npm run dev       # start the server — covara dev creates/updates tables automatically
```

`npm run dev` (which runs [`covara dev`](#covara-dev)) auto-applies additive schema changes on start, so it creates your tables on first run — there's no separate `npm run db:push`. Run `db:push` yourself only for destructive changes or in CI.

### `--frontend react`

Scaffolds a [live React SPA](../client/react-hooks.md) (under `frontend/`) wired to the generated `todos` resource with `useLiveList`, served by the backend itself — **one process, one port, no separate build step**:

- **`npm run dev`** runs a single process that serves the SPA with **Vite HMR** *and* the API (`/api`) and admin UI (`/__covara`) on the same origin (no proxy), while [`covara dev`](#covara-dev) live-applies schema changes and regenerates the typed client into `frontend/src/generated/api-types.ts`.
- **`npm run build`** builds the SPA into `dist/public/` and compiles the backend into `dist/`, so `dist/` is a self-contained deployable; **`npm start`** serves the built SPA with an SPA fallback that excludes `/api` and `/__covara`.
- On **Cloudflare**, the SPA is served via Wrangler [`[assets]`](https://developers.cloudflare.com/workers/static-assets/) with `run_worker_first` for `/api` + `/__covara`; run `npm run dev:web` for Vite HMR alongside `wrangler dev`.

The starter uses the generic typed hook with a hand-written `Todo` interface so it compiles before any codegen; run `npm run types` (or just `npm run dev`) to generate the full typed client and switch to `createTypedClient`.

## `covara generate`

Scaffold incrementally inside an existing project.

```bash
npx covara generate resource invoices   # writes a Drizzle table + a registration snippet
npx covara generate migration           # runs drizzle-kit generate (pass -- to forward args)
```

| Command | What it does |
|---------|--------------|
| `generate resource <name>` | Adds a Drizzle table and a `.resource(...)` registration snippet. |
| `generate migration` | Runs [`drizzle-kit generate`](https://orm.drizzle.team/kit-docs/overview) (forward args after `--`). |

## `covara dev`

The continuous development loop. It runs your server under `tsx watch`, watches your Drizzle schema, and on every save **auto-applies additive changes** to the database (new tables, columns, indexes) so you never push by hand. Destructive changes (dropping/renaming a column, narrowing a type) are **not** auto-applied — they're printed with a hint to run `covara push --force`. With `--types-out`, it also regenerates the [typed client](../client/typegen.md) after each successful change.

```bash
npx covara dev                                   # auto-detects the server entry
npx covara dev src/main.ts --types-out frontend/src/api-types.ts
npx covara dev --no-server                       # only watch + push schema
```

| Flag | Default |
|------|---------|
| `[entry]` / `--entry` | auto-detected (`src/main.ts`, `src/index.ts`, …) |
| `--types-out <path>` | off (skip type regen) |
| `--server-url <url>` | `http://localhost:$PORT` |
| `--profile <name>` | active profile |
| `--no-server` | run only the schema watcher |

> Loading TypeScript: schema-aware commands (`dev`, `push`, `studio`, `data`, `import`/`export`) run a worker via your project's `tsx`, so the framework stays dependency-light and your `.ts` schema/config load natively. `tsx` ships in scaffolded projects.

## Schema & database

```bash
npx covara push                 # apply schema (additive auto; prompts on destructive)
npx covara push --force         # apply even destructive changes (non-interactive)
npx covara migrate              # apply migration files (drizzle-kit migrate)
npx covara studio               # open Drizzle Studio for the active profile
```

`push` computes the diff with [`drizzle-kit`](https://orm.drizzle.team/kit-docs/overview) and classifies it: additive diffs apply immediately; destructive diffs (with possible data loss) require confirmation or `--force`.

### Connection profiles — `covara db`

Named profiles let you switch between local, staging, and remote databases (libsql/Turso URL + token, or a Postgres URL). Profiles live in `.covara/config.json`; the active one (or `DATABASE_URL`/`DB_FILE_NAME`) is used by every schema/data command, and an explicit `--profile <name>` or `--url <url>` overrides it.

```bash
npx covara db add local --url 'file:./dev.db'
npx covara db add prod  --url 'libsql://app.turso.io' --token "$TURSO_TOKEN"
npx covara db use prod
npx covara db list        # * marks the active profile
npx covara db current
npx covara push --profile local
```

## Data

```bash
npx covara data todos --limit 20                 # browse rows (JSON)
npx covara export todos --out todos.csv --format csv
npx covara import todos --file todos.jsonl       # json | jsonl | csv
npx covara seed                                  # run src/db/seed.ts via tsx
```

## Other

```bash
npx covara run todos.markDone '{"id":"abc"}'     # invoke an RPC on a running server
npx covara types --out src/generated/api-types.ts --server-url http://localhost:3000
npx covara env set DB_FILE_NAME dev.db           # manage the project .env
npx covara env list
```

| Command | What it does |
|---------|--------------|
| `run <resource>.<rpc> [json]` | POSTs to a running server's RPC route (`--base`/`--server-url` to override). |
| `types [--out <path>]` | Generates the [TypeScript client types](../client/typegen.md) from a running API. |
| `env <list\|get\|set\|remove>` | Reads/writes the project `.env`. |

## Related

- [Quick Start](../quick-start.md) · [Type generation](../client/typegen.md)
- [Node deployment](../deployment/node.md) · [Cloudflare Workers](../deployment/workers.md) · [Databases](../deployment/databases.md)

---

## Error handling


Covara uses consistent, typed errors end to end. The server emits [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807); the client surfaces them as a `TransportError` with status helpers.

## Problem Details format

All errors use `Content-Type: application/problem+json`:

```json
{
  "type": "/__covara/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "users with id '123' not found",
  "code": "NOT_FOUND",
  "resource": "users",
  "id": "123"
}
```

## Error types

| Type | Status | Description |
|------|--------|-------------|
| `not-found` | 404 | Resource not found |
| `validation-error` | 400 | Invalid input |
| `unauthorized` | 401 | Authentication required |
| `forbidden` | 403 | Insufficient permissions |
| `rate-limit-exceeded` | 429 | Too many requests |
| `batch-limit-exceeded` | 400 | Batch size exceeded |
| `filter-parse-error` | 400 | Invalid filter syntax |
| `conflict` | 409 | Resource conflict |
| `precondition-failed` | 412 | [ETag](../core/optimistic-locking.md) mismatch |
| `cursor-invalid` / `cursor-expired` | 400 | Bad [pagination cursor](../core/pagination.md) |
| `idempotency-mismatch` | 409 | Idempotency key reused |
| `internal-error` | 500 | Server error |

## Error classes

```typescript
import {
  NotFoundError, ValidationError, UnauthorizedError, ForbiddenError,
  RateLimitError, BatchLimitError, FilterParseError, ConflictError,
  PreconditionFailedError, ResourceError,
} from "covara";

throw new NotFoundError("users", "123");
throw new ValidationError("Email is required", { field: "email" });
throw new ForbiddenError("Cannot delete admin users");
throw new ConflictError("Email already in use", { email });
```

All classes extend Hono's `HTTPException` and self-render as `application/problem+json`, so throwing them from any handler, [hook](../core/procedures.md), or [procedure](../core/procedures.md) produces the correct response.

```typescript
hooks: {
  onBeforeCreate: async (ctx, data) => {
    if (data.role === "admin" && !ctx.user?.isAdmin)
      throw new ForbiddenError("Only admins can create admin users");
    return data;
  },
  onBeforeDelete: async (ctx, id) => {
    if (id === ctx.user?.id) throw new ForbiddenError("Cannot delete your own account");
  },
}
```

## Error handlers

`createCovara` wires error handling automatically. With a plain Hono app, register the handlers yourself:

```typescript
import { Hono } from "hono";
import { errorHandler, notFoundHandler } from "covara";

const app = new Hono();
app.onError(errorHandler);
app.notFound(notFoundHandler);
```

The handler formats RFC 7807, sets the content type, adds `Retry-After` for rate limits, includes the request ID, and logs with structured JSON. **Log severity follows status:** `5xx` are logged at `error`, `4xx` (validation, not-found, precondition, rate-limit, auth) at `warn`, so expected client errors don't drown out genuine faults. Each record includes `requestId`, `method`, `path`, `status`, and the message (plus the stack in debug mode).

Zod validation errors include field details:

```json
{
  "type": "/__covara/problems/validation-error",
  "status": 400,
  "errors": [{ "field": "email", "message": "Invalid email format" }]
}
```

## Client: `TransportError`

```typescript
import { TransportError } from "covara/client";

try {
  await users.get("nope");
} catch (error) {
  if (error instanceof TransportError) {
    error.status; error.code; error.type; error.title; error.detail;
    if (error.isNotFound()) {}
    else if (error.isUnauthorized()) {}
    else if (error.isForbidden()) {}
    else if (error.isValidationError()) showFieldErrors(error.details);
    else if (error.isRateLimited()) console.log("retry after", error.retryAfter);
    else if (error.isServerError()) {}
  }
}
```

Set a global handler for `401`s and offline-sync failures:

```typescript
client.setAuthErrorHandler(() => redirectToLogin());
const client = getOrCreateClient({ baseUrl: "/api", onError: (e) => errorTracker.capture(e) });
```

In React, wire `useAuth`'s `logout` into `setAuthErrorHandler`; `useLiveList` then handles auth errors via the global handler. See [Client auth](../client/auth.md).

## Related

- [Middleware](./middleware.md) · [Optimistic locking](../core/optimistic-locking.md) · [Client overview](../client/overview.md)

---

## Middleware


Covara ships several Hono middleware components. All are standard `MiddlewareHandler`s — apply with `app.use("*", ...)` or pass to `createCovara({ middleware: [...] })`.

Published subpaths: `covara/middleware/observability`, `/middleware/rateLimit`, `/middleware/error`, `/middleware/logging`, `/middleware/securityHeaders`. Versioning and idempotency live at `@/middleware/versioning` and `@/middleware/idempotency` in source and aren't yet package subpaths.

[Security headers](../auth/security-headers.md) and [error handling](./error-handling.md) have their own pages.

## Structured logging

Leveled JSON logging through a pluggable sink:

```typescript
import { getLogger, setLogger, createLogger } from "covara";

getLogger().info("server started", { port: 3000 });

setLogger(createLogger({
  level: "debug",
  sink: (record) => myTransport.write(record),
  base: { service: "api" },
}));

const reqLog = getLogger().child({ requestId });
reqLog.warn("slow query", { ms: 812 });
```

Levels: `debug | info | warn | error`. The default level comes from `COVARA_LOG_LEVEL` (falling back to `debug` in debug mode, else `info`). The default sink writes one JSON object per line to the matching `console` method; each record carries `level`, `time` (ISO 8601), `msg`, and your fields.

## Observability

```typescript
import { observabilityMiddleware, createMetricsCollector } from "covara/middleware/observability";

const metrics = createMetricsCollector({ maxMetrics: 1000 });

app.use("*", observabilityMiddleware({
  slowQueryThresholdMs: 500,
  requestIdHeader: "x-request-id",
  traceIdHeader: "traceparent",
  metrics: { onRequest: metrics.onRequest, onSubscription: metrics.onSubscription, onError: metrics.onError },
}));

const stats = metrics.getStats();           // totals, avg duration, error rate, req/min
const slow = metrics.getSlow(1000);
const byPath = metrics.getByPath("/api/users");
```

With `createCovara`, pass `observability: true` (defaults) or an `ObservabilityConfig`. Request tracing reads/propagates the `traceparent` header and invokes an optional `onSpan` hook with per-request timing.

| Collector method | Description |
|------------------|-------------|
| `record` / `onRequest` | Record a request metric |
| `getRecent(n)` | N most recent metrics |
| `getByPath(path)` | Metrics for a path |
| `getSlow(thresholdMs)` | Slow requests |
| `getRequestMetrics(filter?)` | Match a partial filter |
| `getSubscriptionMetrics()` / `getErrorMetrics()` | Subscription / error metrics |
| `getStats()` | Aggregate stats |
| `clear()` | Reset |

The [admin UI](./admin-ui.md) renders these metrics live.

## Versioning

```typescript
import { versioningMiddleware, wrapWithVersion, checkMinimumVersion, COVARA_VERSION } from "@/middleware/versioning";

app.use("*", versioningMiddleware({ headerName: "X-Covara-Version" }));

wrapWithVersion({ users: [] });                 // { data: {...}, version: "1.0.0", timestamp: "..." }
checkMinimumVersion("0.9.0", "1.0.0");          // { compatible, clientVersion, ... }
```

The framework also reads the request's API version into `c.get("apiVersion")`.

## Idempotency

```typescript
import { idempotencyMiddleware } from "@/middleware/idempotency";
import { createMemoryKV } from "covara/kv";

app.use("*", idempotencyMiddleware({
  storage: createMemoryKV(),       // any KVAdapter (Redis in production)
  ttlMs: 86_400_000,
  methods: ["POST", "PATCH", "PUT"],
  headerName: "idempotency-key",
  onStoreError: "proceed",         // "proceed" (default) | "fail"
}));
```

When a request carries an `Idempotency-Key`, the middleware returns the cached response if the key (and body) was seen before, otherwise processes and caches it.

`onStoreError` controls behavior when the KV is unreachable at lookup time:

- `"proceed"` (default) — log a warning and continue **without** replay protection (favors availability).
- `"fail"` — return RFC 7807 `503` so the client retries (favors correctness).

A failure while *caching* the response is always logged and swallowed; the response is still returned.

## Rate limiting

```typescript
import { createRateLimiter, createSlidingWindowRateLimiter } from "covara/middleware/rateLimit";
import { getClientIP, getUser } from "covara";

app.use("*", createRateLimiter({
  windowMs: 60_000,
  maxRequests: 100,
  keyGenerator: (c) => getUser(c)?.id ?? getClientIP(c),
  skip: (c) => c.req.path === "/healthz",
  // store: kvRateLimitStore, // distributed; default is in-memory
}));
```

`createSlidingWindowRateLimiter` is a sliding-window variant. Resources also accept a `rateLimit: { windowMs, maxRequests }` config directly — see [Resources](../core/resources-and-app.md#ratelimit). Provide a distributed `store` (KV/Redis) for multi-instance deployments.

## Related

- [Security headers](../auth/security-headers.md) · [Error handling](./error-handling.md) · [Admin UI](./admin-ui.md)
- [Optimistic locking](../core/optimistic-locking.md) · [KV store](../platform/kv.md)

---

## Observability storage


The admin dashboard's **audit log**, **request/error logs**, and **metrics** are append-only logs. By default they live in a per-process ring buffer (exactly as before), but they're now backed by a pluggable `ObservabilityLogAdapter` so you can make them durable and shared across instances.

## Three layers

1. **Zero-config (default).** Each log uses a self-falling-back hybrid adapter. With no [KV store](../platform/kv.md) configured it behaves identically to the old in-memory ring buffer. If you `setGlobalKV(...)` before `createCovara`, audit/request/error logs are persisted to KV automatically (shared across instances) — no extra wiring.
2. **Per-store injection.** Pass your own adapters (e.g. one backed by your database) via `AdminUIConfig.observability`:

   ```typescript
   createCovara({
     adminUI: {
       observability: {
         auditAdapter: myDbAuditAdapter,   // implements ObservabilityLogAdapter
         requestAdapter,
         errorAdapter,
       },
     },
   });
   ```
   Metrics storage is selected with `createMetricsCollector({ storage: "kv" })` (default `"memory"`, to keep the hot request path cheap).
3. **Write-only tap.** `setAdminAuditSink(fn)` still works for fire-and-forget forwarding (e.g. ship every admin action to your SIEM). It runs *alongside* the adapter; it is write-only — for read/query/export persistence, implement `ObservabilityLogAdapter`.

## The adapter interface

```typescript
interface ObservabilityLogAdapter<TEntry> {
  append(entry: TEntry): void | Promise<void>;   // never throws into the audited action
  querySync(query?: LogQuery): TEntry[];          // sync local-mirror read
  query(query?: LogQuery): Promise<TEntry[]>;     // authoritative (consults KV)
  export(opts?: { limit?: number }): Promise<TEntry[]>;
  count(): Promise<number>;
  countSync(): number;
  clear(): void | Promise<void>;
}
```

Built-ins: `createInMemoryLogAdapter({ maxEntries, order })` and `createKVLogAdapter({ keyPrefix, maxEntries, order })` (modeled on the [changelog](../realtime/changelog.md): a monotonic-seq sorted set, capped via `zrem`, wrapping an in-memory mirror).

## Cross-process behavior

In KV mode the adapter keeps a local mirror so the synchronous reads the dashboard uses on render (`querySync`, counters, metric aggregates) always work — but that mirror only reflects entries written by **this** process. Authoritative cross-instance reads go through the async `query()`/`export()` path; the audit export endpoints use it. This is the same tradeoff the changelog makes.

## What is and isn't covered

These previously memory-only stores are now KV-pluggable: the **admin audit log**, **request/error logs**, **metrics**, the **admin auth rate-limit** counter, and the **API-key** and **verification-token** stores (`createKVApiKeyStore` / `createKVVerificationTokenStore`).

Intentionally left per-process: the **SSE subscription counters** (they account for *this* instance's live connections — KV would leak counts on a crash) and the **OIDC discovery/JWKS caches** (self-healing performance caches; a lost entry just triggers a re-fetch). The in-memory KV and storage backends are, of course, the intended in-memory implementations.

## Related

- [Admin UI](./admin-ui.md) · [KV store](../platform/kv.md) · [Changelog](../realtime/changelog.md)

---

## OpenAPI


Covara generates an OpenAPI 3.0 spec from your resource definitions. With `createCovara`, the router is mounted at `/__covara` by default and resources are auto-discovered as you register them.

```typescript
const app = createCovara()
  .resource(postsTable, { id: postsTable.id, db })
  .resource(usersTable, { id: usersTable.id, db });

// GET /__covara/openapi.json   OpenAPI 3.0 spec
// GET /__covara/openapi.yaml   YAML variant
// GET /__covara/schema         Covara schema (used by typegen)
```

## Manual setup

```typescript
import { createCovaraRouter } from "covara/openapi";

app.route("/__covara", createCovaraRouter({
  title: "My API",
  version: "1.0.0",
  description: "A Covara-powered API",
  servers: [{ url: "https://api.example.com" }],
}));
```

Generate a spec object programmatically:

```typescript
import { generateOpenAPISpec, type RegisteredResource } from "covara/openapi";

const resources: RegisteredResource[] = [
  { name: "posts", path: "/api/posts", schema: postsTable },
  { name: "users", path: "/api/users", schema: usersTable },
];
const spec = generateOpenAPISpec(resources, { title: "My API", version: "1.0.0" });
```

## What's documented

For each resource: list/get/create/update/replace/delete, count, aggregate, subscribe, the batch routes, and one path per configured [RPC procedure](../core/procedures.md).

- **Schemas** are derived from Drizzle columns (types, `required`, `nullable`); enum-backed columns emit an `enum` list.
- **Filter operators** — the `filter` parameter description enumerates the supported [RSQL operators](../core/filtering.md), with your `customOperators` appended so consumers can discover them.
- **Subscriptions** — `GET /subscribe` is documented with a `text/event-stream` response and the event `type` values (`existing`, `added`, `changed`, `removed`, `invalidate`), plus `filter`/`include` params.
- **ETag** — when [`etag`](../core/optimistic-locking.md) is configured, responses document the `ETag` header, `If-Match`/`If-None-Match` params, the `304` (GET), and the `412` (PATCH/PUT/DELETE).
- **Responses** — standard list/count/aggregate shapes and the RFC 7807 [error format](./error-handling.md).
- **Security schemes** — generated when auth is configured.

```typescript
generateOpenAPISpec(resources, {
  securitySchemes: {
    bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
    apiKey: { type: "apiKey", in: "header", name: "X-API-Key" },
  },
});
```

## Swagger UI

```typescript
import { swaggerUI } from "@hono/swagger-ui";
app.get("/docs", swaggerUI({ url: "/__covara/openapi.json" }));
```

The `/__covara/schema` endpoint is what [type generation](../client/typegen.md) consumes.

## Related

- [Type generation](../client/typegen.md) · [Admin UI](./admin-ui.md) · [Resources](../core/resources-and-app.md)

---

## Tutorial: a real-time todo app


This tutorial builds a complete app end to end: authenticated users with private todos, categories and tags (relations), image uploads, full-text search, and a React UI that updates in real time with optimistic mutations. It mirrors the project under [`example/`](https://github.com/kahveciderin/covara/tree/master/example) in the repo.

By the end you'll have used: [resources](./core/resources-and-app.md), [auth scopes](./auth/scopes.md), [relations](./core/relations.md), [lifecycle hooks](./core/procedures.md), [file storage](./platform/storage.md), [search](./core/search.md), [live subscriptions](./realtime/subscriptions.md), and [live aggregations](./realtime/aggregate-subscriptions.md).

## 1. Schema

```typescript
// src/db/schema.ts
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";

export const usersTable = sqliteTable("users", {
  id: text("id").primaryKey(),
  email: text("email").notNull().unique(),
  name: text("name").notNull(),
  passwordHash: text("passwordHash").notNull(),
  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
});

export const categoriesTable = sqliteTable("categories", {
  id: text("id").primaryKey(),
  userId: text("userId").notNull(),
  name: text("name").notNull(),
  color: text("color"),
  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
});

export const todosTable = sqliteTable("todos", {
  id: text("id").primaryKey(),
  userId: text("userId").notNull(),
  title: text("title").notNull(),
  description: text("description"),
  completed: integer("completed", { mode: "boolean" }).default(false),
  position: integer("position").notNull(),
  categoryId: text("categoryId"),
  imageId: text("imageId"),
  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
  updatedAt: integer("updatedAt", { mode: "timestamp" }).notNull(),
});

export const tagsTable = sqliteTable("tags", {
  id: text("id").primaryKey(),
  userId: text("userId").notNull(),
  name: text("name").notNull(),
});

export const todoTagsTable = sqliteTable("todo_tags", {
  todoId: text("todoId").notNull(),
  tagId: text("tagId").notNull(),
});

export const filesTable = sqliteTable("files", {
  id: text("id").primaryKey(),
  userId: text("userId").notNull(),
  key: text("key").notNull(),
  filename: text("filename").notNull(),
  contentType: text("contentType").notNull(),
  size: integer("size").notNull(),
  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
});
```

## 2. Database

```typescript
// src/db/db.ts
import { drizzle } from "drizzle-orm/libsql";
import { createClient } from "@libsql/client";
import { env } from "../env"; // your createEnv schema — see Environment variables

const client = createClient({ url: env.DB_FILE_NAME });
export const db = drizzle(client);
```

Push the schema with [`drizzle-kit`](https://orm.drizzle.team/kit-docs/overview): `npx drizzle-kit push`.

## 3. Authentication

We use the [Passport adapter](./auth/sessions.md) with a session store, plus [`useAuth`](./auth/overview.md) to mount `/login`, `/signup`, `/logout`, and `/me`.

```typescript
// src/auth.ts
import { eq } from "drizzle-orm";
import { randomUUID } from "node:crypto";
import {
  useAuth,
  createPassportAdapter,
  hashPassword,
  verifyPassword,
  ValidationError,
} from "covara";
import { db } from "./db/db";
import { usersTable } from "./db/schema";

const authAdapter = createPassportAdapter({
  getUserById: async (id) => {
    const [user] = await db.select().from(usersTable).where(eq(usersTable.id, id)).limit(1);
    return user ?? null;
  },
});

export const auth = useAuth({
  adapter: authAdapter,
  login: {
    validateCredentials: async (email, password) => {
      const [user] = await db.select().from(usersTable).where(eq(usersTable.email, email)).limit(1);
      if (!user || !(await verifyPassword(password, user.passwordHash))) return null;
      return { id: user.id, email: user.email, name: user.name };
    },
  },
  signup: {
    createUser: async ({ email, password, name }) => {
      const existing = await db.select().from(usersTable).where(eq(usersTable.email, email)).limit(1);
      if (existing.length > 0) throw new ValidationError("Email already registered");
      const [user] = await db
        .insert(usersTable)
        .values({
          id: randomUUID(),
          email,
          name: name ?? "User",
          passwordHash: await hashPassword(password),
          createdAt: new Date(),
        })
        .returning();
      return { id: user.id, email: user.email, name: user.name };
    },
  },
});
```

`hashPassword`/`verifyPassword` are Covara's built-in scrypt helpers — see [Passwords](./auth/passwords.md).

## 4. Resources

Now the heart of the app. Every resource scopes reads/writes to the current user with [RSQL scopes](./auth/scopes.md), and `todos` declares [relations](./core/relations.md) to categories, files, and tags.

```typescript
// src/main.ts
import { randomUUID } from "node:crypto";
import { eq, max } from "drizzle-orm";
import {
  createCovara,
  rsql,
  UnauthorizedError,
  initializeKV,
  initializeStorage,
  useFileResource,
} from "covara";
import { startServer } from "covara/node";
import { db } from "./db/db";
import { auth } from "./auth";
import {
  usersTable, todosTable, categoriesTable, tagsTable, todoTagsTable, filesTable,
} from "./db/schema";

await initializeKV({ type: "memory", prefix: "todo-app" });
initializeStorage({ type: "local", local: { basePath: "./.tmp/uploads", baseUrl: "/uploads" } });

const app = createCovara({ auth, cors: true })
  .resource("/categories", categoriesTable, {
    id: categoriesTable.id,
    db,
    auth: {
      read: async (user) => rsql`userId==${user?.id}`,
      create: async (user) => (user ? rsql`*` : rsql``),
      update: async (user) => rsql`userId==${user?.id}`,
      delete: async (user) => rsql`userId==${user?.id}`,
    },
    generatedFields: [categoriesTable.id, categoriesTable.userId, categoriesTable.createdAt],
    hooks: {
      onBeforeCreate: async (ctx, data) => {
        if (!ctx.user) throw new UnauthorizedError("Must be logged in");
        return { ...data, id: randomUUID(), userId: ctx.user.id, createdAt: new Date() };
      },
    },
  })
  .resource("/tags", tagsTable, {
    id: tagsTable.id,
    db,
    auth: {
      read: async (user) => rsql`userId==${user?.id}`,
      create: async (user) => (user ? rsql`*` : rsql``),
      update: async (user) => rsql`userId==${user?.id}`,
      delete: async (user) => rsql`userId==${user?.id}`,
    },
    generatedFields: [tagsTable.id, tagsTable.userId],
    hooks: {
      onBeforeCreate: async (ctx, data) => {
        if (!ctx.user) throw new UnauthorizedError("Must be logged in");
        return { ...data, id: randomUUID(), userId: ctx.user.id };
      },
    },
  })
  .resource("/todos", todosTable, {
    id: todosTable.id,
    db,
    pagination: { defaultLimit: 100, maxLimit: 500 },
    search: {
      enabled: true,
      fields: { title: { weight: 2.0 }, description: { weight: 1.0 } },
    },
    auth: {
      read: async (user) => rsql`userId==${user?.id}`,
      create: async (user) => (user ? rsql`*` : rsql``),
      update: async (user) => rsql`userId==${user?.id}`,
      delete: async (user) => rsql`userId==${user?.id}`,
      subscribe: async (user) => rsql`userId==${user?.id}`,
    },
    generatedFields: [todosTable.id, todosTable.userId, todosTable.position, todosTable.createdAt, todosTable.updatedAt],
    relations: {
      category: {
        resource: "categories", schema: categoriesTable, type: "belongsTo",
        foreignKey: todosTable.categoryId, references: categoriesTable.id,
      },
      image: {
        resource: "files", schema: filesTable, type: "belongsTo",
        foreignKey: todosTable.imageId, references: filesTable.id,
      },
      tags: {
        resource: "tags", schema: tagsTable, type: "manyToMany",
        foreignKey: todosTable.id, references: tagsTable.id,
        through: { schema: todoTagsTable, sourceKey: todoTagsTable.todoId, targetKey: todoTagsTable.tagId },
      },
    },
    hooks: {
      onBeforeCreate: async (ctx, data) => {
        if (!ctx.user) throw new UnauthorizedError("Must be logged in");
        const [maxPos] = await db
          .select({ max: max(todosTable.position) })
          .from(todosTable)
          .where(eq(todosTable.userId, ctx.user.id));
        return {
          ...data, id: randomUUID(), userId: ctx.user.id,
          position: (maxPos?.max ?? -1) + 1, createdAt: new Date(), updatedAt: new Date(),
        };
      },
      onBeforeUpdate: async (_ctx, _id, data) => ({ ...data, updatedAt: new Date() }),
    },
  });
```

A few things worth noting:

- **`generatedFields`** marks columns the server fills in (id, userId, timestamps), so the client never has to send them and they are stripped from inbound payloads.
- **`onBeforeCreate`** is where ownership is stamped — `ctx.user.id` is the authenticated user from the session middleware.
- **`auth.subscribe`** scopes the SSE stream, so a user only sees real-time changes to their own todos.
- **`search`** registers `title`/`description` as searchable; the actual index depends on the [search adapter](./core/search.md) you configure.

## 5. File uploads

Mount a [file resource](./platform/storage.md). It generates upload/download/list/delete endpoints with MIME and size validation.

```typescript
app.route(
  "/api/files",
  useFileResource(filesTable, {
    db,
    schema: filesTable,
    id: filesTable.id,
    allowedMimeTypes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
    maxFileSize: 5 * 1024 * 1024,
    auth: {
      read: async (user) => rsql`userId==${user?.id}`,
      create: async (user) => (user ? rsql`*` : rsql``),
      delete: async (user) => rsql`userId==${user?.id}`,
    },
  })
);

await startServer(app, { port: 3000 });
```

## 6. The React client

```tsx
// frontend/src/App.tsx
import { getOrCreateClient } from "covara/client";
import {
  useAuth, useLiveList, useLiveAggregate, useSearch, useFileUpload,
} from "covara/client/react";

const client = getOrCreateClient({
  baseUrl: location.origin,
  credentials: "include",
  offline: true,
});

function TodoApp() {
  // Live, paginated list with relations included — updates in real time.
  const { items: todos, status, mutate, hasMore, loadMore } = useLiveList<Todo>("/api/todos", {
    orderBy: "position",
    include: ["category", "image", "tags"],
    limit: 5,
  });

  // Live aggregation across ALL todos (not just the loaded page),
  // recomputed on the server on every change.
  const { groups } = useLiveAggregate("/api/todos", { groupBy: ["completed"], count: true });
  const completed = groups.find((g) => g.key?.completed === true)?.count ?? 0;

  const addTodo = (title: string) => mutate.create({ title }); // optimistic
  const toggle = (t: Todo) => mutate.update(t.id, { completed: !t.completed });

  return (
    
      {todos.map((t) => (
        
          <input type="checkbox" checked={t.completed} onChange={() => toggle(t)} />
          {t.title} {t.category && {t.category.name}}
          <button onClick={() => mutate.delete(t.id)}>×</button>
        
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    
  );
}
```

`mutate.create`/`update`/`delete` apply **optimistically** (instant UI), queue while offline, and reconcile against the server response. Every change streams to all connected clients via the subscription. See [Live queries](./client/live-queries.md) and [Offline](./client/offline.md).

### Type safety end to end

Generate types from the running API and wrap the client to get fully-typed resource accessors and a fluent query builder:

```bash
npx covara types --url http://localhost:3000 --out src/generated/api-types.ts
```

```tsx
import { createTypedClient } from "./generated/api-types";
const typed = createTypedClient(client);

const { items } = useLiveList(
  typed.resources.todos.orderBy("position").include("category", "tags").limit(5)
); // items is fully typed, including the included relations
```

See [Type generation](./client/typegen.md).

## Where to go next

- Add **[optimistic locking](./core/optimistic-locking.md)** to prevent lost updates.
- Add **[background tasks](./platform/tasks.md)** to send a daily digest email.
- Add **[billing](./platform/billing.md)** to gate premium features.
- **[Deploy](./deployment/node.md)** to Node or Cloudflare Workers.