# CalmAPI documentation

> CalmAPI 2 is a backend framework for Node.js and MongoDB where every line of framework code lives in your repo: resources, policies, auth, devtools, blocks and an upgrade path.

---

Source: https://docs.calmapi.dev/

# Why CalmAPI

**CalmAPI 2 is the backend framework you own.** Resources, policies, auth, devtools and an upgrade path for Node.js and MongoDB, with every line of framework code living in your repo.

```bash
npm create calmapi@latest my-api
cd my-api
npm run dev
```

```text
  CalmAPI my-api v0.1.0 (development)

  ➜  API       http://localhost:5001/api
  ➜  OpenAPI   http://localhost:5001/api/openapi.json
  ➜  Devtools  http://localhost:5001/_calm
```

> **Status: 2.0.0-alpha.** APIs may still change before 2.0. Coming from CalmAPI 1.x? Run `npx calmapi@next doctor` inside your 1.x project first, then read [Migrating from 1.x](/migrate-v1).

## What makes it different

### Owned code, nothing hidden in node_modules

`npm create calmapi` copies the framework into your project as `calm/`: around 5,500 lines of plain, commented JavaScript on Express 5 and Mongoose. Read it, step through it in a debugger, change it. When something behaves unexpectedly, the answer is in your editor, not in a minified dependency.

A new project has **two runtime dependencies**: `express` and `mongoose`. The CLI (`calmapi`) and the devtools UI (`@calmapi/devtools`) are dev dependencies and never ship to production.

### Owned, but upgradeable

Copied code usually means "no more updates". CalmAPI keeps a `calm.lock` with a hash of every framework file you started from. `calm upgrade` replaces files you never touched, three-way merges upstream fixes into files you edited, and marks real conflicts for you to resolve. See [Upgrading](/upgrading).

### Declare a field once

One `f.*()` line drives the Mongoose schema, input validation, what the API returns (and to whom), which filters and sorts clients may use, and the OpenAPI document. No DTO classes to keep in sync.

### Secure by default

- Hidden fields never leave the server, not even through populated references.
- Every route has an access policy. Routes without an explicit one default to `authenticated` and `calm doctor` flags them.
- Unknown, read-only and hidden fields in a request body are rejected with `422`, so there is no mass assignment.
- List queries are allowlisted: clients can only filter, sort and search on fields you marked.
- Sessions and password reset tokens are random, opaque and stored as SHA-256 hashes. Passwords use scrypt from `node:crypto`, and common passwords are refused.
- Auth endpoints are rate limited, accounts lock after repeated failed sign-ins, and responses never reveal whether an email is registered.
- `.encrypted()` fields are stored as AES-256-GCM ciphertext, with key rotation.
- Anything but `development` or `test` runs as production. Production refuses to boot without `APP_URL`, and devtools cannot be turned on there.

You can check the result: `calm audit` calls every route as every kind of user on a throwaway database and reports where the API and your policies disagree. See [Security](/security) and [Security audit](/audit).

### Devtools

A local dashboard at `/_calm` shows every request with its MongoDB queries and timings, explain plans, logs, a privacy lens that puts what is stored next to what the API returns, a mail catcher for password reset links, "act as" any user, doctor findings, and who can access what. See [Devtools](/devtools).

### Agent native

Every project ships with `AGENTS.md`. `calm mcp` is an MCP server that gives coding agents tools to inspect routes and resources, scaffold resources, call the API as any user, run tests, doctor and the security audit, and read live requests from the dev server. Everything an agent does (tool calls, file diffs, restarts, crashes, requests) shows up live in devtools, so you can watch it work. See [AI agents](/ai-agents).

### Blocks, shadcn style

`calm add jobs` copies production code into your project: a MongoDB job queue, file storage on disk or S3, realtime events, an audit log, soft delete, two-factor authentication, an MCP server for your API and more. You own that code too, and anyone can publish blocks in the shadcn registry format. See [Blocks](/blocks).

## A resource

```js
// app/resources/post/post.resource.js
import { resource, f } from '#calm';

export default resource('post', {
  fields: {
    title: f.string().required().max(200).searchable().sortable(),
    body: f.text().required(),
    status: f.enum(['draft', 'published']).default('draft').filterable(),
    tags: f.array(f.string()).filterable(),
    author: f.ref('user').owner(),     // set from the session, powers 'owner'
    internalNote: f.string().hidden(), // stored, never returned or accepted
  },
  policy: {
    list: 'public',
    read: 'public',
    create: 'authenticated',
    update: 'owner | admin',
    delete: 'owner | admin',
  },
});
```

That file alone gives you:

| Route | Notes |
|---|---|
| `GET /api/posts` | filters, search, sort, pages, includes: `?status=published&tags[in]=a,b`, `q=hello`, `sort=-createdAt`, `page=2&limit=20`, `include=author`, `fields=title` |
| `GET /api/posts/:id` | `?include=author` populates the author with fields the viewer may see |
| `POST /api/posts` | validated, unknown or read-only fields rejected with 422, owner set automatically, 201 |
| `PATCH /api/posts/:id` | partial update; 403 for users who can read the post, 404 for those who cannot |
| `DELETE /api/posts/:id` | 204 |

Business logic goes in a service, custom endpoints in a routes file:

```js
// app/resources/post/post.service.js
import { ResourceService, hasRole } from '#calm';

export default class PostService extends ResourceService {
  // Applied to every query: visitors see published posts, authors also see their drafts.
  scope({ user } = {}) {
    if (hasRole(user, 'admin')) return {};
    return user ? { $or: [{ status: 'published' }, { author: user.id }] } : { status: 'published' };
  }
}
```

```js
// app/resources/post/post.routes.js (mounted before CRUD, so /featured never hits /:id)
export default (r) => {
  r.post('/:id/publish', { policy: 'owner | admin' }, (ctx) =>
    ctx.service.update(ctx.params.id, { status: 'published' }, ctx));
};
```

Handlers **return** values (`{ data }` responses, `undefined` becomes `204`) and throw `notFound()`, `forbidden()` or `validationError({...})`. Express 5 forwards async errors, so there is no try/catch boilerplate.

## Where to go next

- [Getting started](/getting-started): create a project and make your first requests.
- [Resources and fields](/resources): everything a resource can declare.
- [Policies](/policies): who may do what, and why some errors are 404 instead of 403.
- [Blocks](/blocks): jobs, uploads, realtime, MCP and more, one command each.
- [Quick reference](/quick-reference): the whole API on one page.

---

Source: https://docs.calmapi.dev/getting-started

# Getting started

Create a project, run it, and talk to it with `curl`. This takes about five minutes.

## Requirements

- **Node.js 22.12 or newer** (24 LTS recommended). The CLI refuses to run on older versions.
- **MongoDB** 6 or newer, local or hosted (for example MongoDB Atlas). For a quick local server:

```bash
docker run -d --name mongo -p 27017:27017 mongo:8
```

## Create a project

```bash
npm create calmapi@latest my-api
```

The wizard asks for:

1. **Project folder** (default `my-api`).
2. **Template**: `api` or `minimal` (see below).
3. **MongoDB URI** (default `mongodb://127.0.0.1:27017/<project_name>`), written to `.env`.
4. Whether to **install dependencies** and **initialize git**.

To skip the questions, pass flags after `--` so npm forwards them:

```bash
npm create calmapi@latest my-api -- --yes --template api --db mongodb://127.0.0.1:27017/my_api
```

| Template | What you get |
|---|---|
| `api` (default) | A `user` resource with sign up, login, sessions and password reset under `/api/auth`, an example `post` resource with a service and custom routes, and a test. |
| `minimal` | Just the framework, an `app/routes.js` with `GET /api/hello`, and a test. No `user` resource, so no auth until you add one. |

Every template also contains `calm/` (the framework), `calm.config.js`, `calm.lock`, `.env`, `AGENTS.md`, a `Dockerfile` and an ESLint config. See [Project structure](/project-structure).

## Run it

```bash
cd my-api
npm run dev
```

```text
  CalmAPI my-api v0.1.0 (development)

  ➜  API       http://localhost:5001/api
  ➜  OpenAPI   http://localhost:5001/api/openapi.json
  ➜  Devtools  http://localhost:5001/_calm

  2 resources · 25 routes · 0 blocks · MongoDB connected
```

`npm run dev` runs `calm dev`: development mode, a restart whenever something in `app/`, `calm/`, `calm.config.js`, `server.js` or `.env` changes, and [devtools](/devtools) at `/_calm`. If MongoDB is not reachable, the app retries a few times and then exits with a clear message.

## First requests

The examples below use the `api` template.

### 1. Register

```bash
curl -X POST http://localhost:5001/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","password":"correct-horse-battery"}'
```

```json
{
  "data": {
    "user": {
      "id": "6acb46a57e4a738ebdd998b1",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "roles": ["user"],
      "status": "active",
      "createdAt": "2026-10-11T08:19:49.069Z",
      "updatedAt": "2026-10-11T08:19:49.069Z"
    },
    "token": "calm_M_vAh-pIohIgNEe8gapu1LMoYxlH6oYvepNVGWtYPWk",
    "expiresAt": "2026-11-10T08:19:49.085Z"
  }
}
```

Registering signs you in. The password is never returned, and `roles` cannot be set by the client.

### 2. Log in

```bash
curl -X POST http://localhost:5001/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct-horse-battery"}'
```

The response has the same shape. Keep the token for the next requests:

```bash
TOKEN=calm_GZWY3MMqzg4aRbB80iRCKScHbbnjrLSDu2-sfYER27E
```

### 3. Create a post

```bash
curl -X POST http://localhost:5001/api/posts \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Hello CalmAPI","body":"My first post","tags":["intro","news"],"status":"published"}'
```

```json
{
  "data": {
    "id": "6acb46a57e4a738ebdd998b4",
    "title": "Hello CalmAPI",
    "slug": "hello-calmapi",
    "body": "My first post",
    "status": "published",
    "tags": ["intro", "news"],
    "author": "6acb46a57e4a738ebdd998b1",
    "publishedAt": "2026-10-11T08:19:49.447Z",
    "createdAt": "2026-10-11T08:19:49.448Z",
    "updatedAt": "2026-10-11T08:19:49.448Z"
  }
}
```

The status is `201`. `author` was set from your session, and `slug` and `publishedAt` were filled in by `post.service.js`. Sending `slug` yourself is refused, because it is read-only:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "requestId": "5c397446-0c18-4cfe-99be-d08c78419bec",
    "details": { "slug": "Is read-only", "likes": "Unknown field" }
  }
}
```

### 4. List with filters

```bash
curl -g "http://localhost:5001/api/posts?status=published&tags[in]=intro,news&sort=-createdAt&include=author&fields=title,author" \
  -H "Authorization: Bearer $TOKEN"
```

`-g` stops curl from reading `[in]` as a glob pattern.

```json
{
  "data": [
    {
      "id": "6acb46a57e4a738ebdd998b4",
      "title": "Hello CalmAPI",
      "author": {
        "id": "6acb46a57e4a738ebdd998b1",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "roles": ["user"],
        "status": "active",
        "createdAt": "2026-10-11T08:19:49.069Z",
        "updatedAt": "2026-10-11T08:19:49.069Z"
      },
      "createdAt": "2026-10-11T08:19:49.448Z",
      "updatedAt": "2026-10-11T08:19:49.448Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20, "pages": 1 }
}
```

You see the author's `email` and `roles` because the author is you. Anyone else gets the author without them: the `user` resource marks them `.visibleTo('owner | admin')`. Without a token, the list only contains published posts, because `post.service.js` scopes every query.

Ask for something that is not allowed and you get a `400` that explains why:

```bash
curl -g "http://localhost:5001/api/posts?body=x&sort=body&limit=500"
```

```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query",
    "requestId": "86f489d3-d343-4d90-a614-86bdca30b700",
    "details": {
      "body": "Not filterable. Filterable fields: slug, status, tags",
      "sort": "Cannot sort by \"body\". Sortable: id, title, publishedAt, createdAt, updatedAt",
      "limit": "Must be an integer between 1 and 100"
    }
  }
}
```

The full query language is in [Querying](/querying).

## Open the devtools

Visit `http://localhost:5001/_calm`. Every request you just made is there with its MongoDB queries, timings and logs. Ask for a password reset (`POST /api/auth/password/forgot`) and the email shows up in the **Mail** panel, link included.

## Add your own resource

```bash
npx calm make resource product name:string!+searchable price:number! status:enum:draft,live=draft --service
```

```text
✔ Created resource product at /api/products
  + app/resources/product/product.resource.js
  + app/resources/product/product.service.js
  + test/products.test.js
```

The dev server restarts and `/api/products` is live with all five CRUD routes. Open the resource file to adjust fields and policies, then:

```bash
npx calm routes    # every route with its policy
npx calm doctor    # security and correctness checks
npx calm audit     # every route as every role, on a throwaway database
npm test           # node --test, needs MongoDB
```

## Next steps

- [Project structure](/project-structure): what each file and folder is for.
- [Resources and fields](/resources): every field type and modifier.
- [Policies](/policies): who may list, read, create, update and delete.

---

Source: https://docs.calmapi.dev/project-structure

# Project structure

A CalmAPI project is a plain Node.js (ESM) app. The framework is in `calm/`, your code is in `app/`.

```text
my-api/
├── calm/                     the framework (yours, tracked by calm.lock)
├── app/
│   ├── resources/
│   │   ├── post/
│   │   │   ├── post.resource.js    fields + access policy (required)
│   │   │   ├── post.service.js     business logic (optional)
│   │   │   └── post.routes.js      custom endpoints (optional)
│   │   └── user/
│   │       └── user.resource.js
│   ├── blocks/               blocks added with `calm add` (and your own plugins)
│   └── routes.js             app-wide custom routes (optional)
├── test/
│   └── posts.test.js         node:test, uses createTestApp
├── server.js                 starts the app
├── calm.config.js            config overrides (no secrets)
├── calm.lock                 framework and block file hashes, used by `calm upgrade`
├── .env / .env.example       secrets and environment
├── .calm/                    activity log written by calm dev and calm mcp (git-ignored)
├── AGENTS.md / CLAUDE.md     instructions for AI coding agents
├── Dockerfile / .dockerignore
├── eslint.config.js
└── package.json
```

## calm/

The framework itself, copied from the `calmapi` package when the project was created. It is your code: read it, debug it, change it. `calm upgrade` merges upstream fixes into it without discarding your edits (see [Upgrading](/upgrading)).

| File | What it does |
|---|---|
| `index.js` | Everything `#calm` exports |
| `app.js` | `createApp()`: loads config, resources and blocks, builds the Express app, starts and stops it |
| `config.js` | Defaults, `.env` and `calm.config.js` loading, validation at boot |
| `loader.js` | Finds `app/resources/*`, `app/blocks/*` and `app/routes.js`; `definePlugin()` |
| `resource/resource.js` | `resource()`, Mongoose compilation, input validation, output serialization |
| `resource/fields.js` | The `f.*()` field builders and value validation |
| `resource/policy.js` | Policy parsing and evaluation, `hasRole()`, `isOwner()` |
| `resource/query.js` | The list query language (filters, search, sort, pagination, include, fields) |
| `resource/routes.js` | The five CRUD routes |
| `resource/service.js` | `ResourceService` |
| `http/router.js` | The route builder, request context (`ctx`), item authorization, responses |
| `http/middleware.js` | Request ids, security headers, CORS, rate limiting, JSON guard, access log |
| `auth/` | Register, login, sessions, password change and reset, lockout, password rules; scrypt hashing; tokens |
| `security/` | Field encryption (`encryption.js`), the exposure matrix (`exposure.js`) and the `calm audit` engine (`audit.js`) |
| `errors.js` | `CalmError`, helpers and the mapping of every error to a safe response |
| `events.js`, `mail.js`, `logger.js`, `context.js` | Event bus, mailer, structured logger, per-request context |
| `openapi.js`, `doctor.js`, `testing.js` | OpenAPI 3.1 generator, runtime checks, test helpers |
| `devtools/index.js` | The devtools collector and API behind `/_calm` (development only) |

## app/resources

One folder per resource. The folder name is the resource name, and files are named after the folder:

- `<name>.resource.js` (required) default-exports `resource('<name>', { fields, policy })`. See [Resources and fields](/resources).
- `<name>.service.js` (optional) default-exports a class that extends `ResourceService`. See [Services and hooks](/services).
- `<name>.routes.js` (optional) default-exports `(r) => { ... }`. Its routes are mounted under the resource path, before the CRUD routes. See [Custom routes](/routes).

A folder without a `.resource.js` file is ignored. Create resources with `npx calm make resource`, which also writes a test.

## app/blocks

Blocks added with `calm add` land here as `app/blocks/<name>/index.js` (some also add resources, `app/jobs/` or `app/notifications/`). Every folder with an `index.js` that default-exports `definePlugin({ name, setup })` is loaded at boot, so this is also the place for your own blocks, for example an event listener. `npx calm make block <name>` starts one. See [Building your own block](/building-blocks) for the plugin API.

## app/routes.js

Routes that do not belong to a resource, mounted under `/api`:

```js
// app/routes.js
export default (r) => {
  r.get('/hello', { policy: 'public', summary: 'Say hello' }, (ctx) => ({
    message: `Hello from ${ctx.config.app.name}`,
  }));
};
```

## server.js

```js
import { createApp } from '#calm';

try {
  const app = await createApp({ root: import.meta.dirname });
  await app.listen();
} catch (err) {
  console.error(err.code === 'CALM_CONFIG' ? `\n${err.message}\n` : err);
  process.exit(1);
}
```

`npm start` runs it (production mode unless `NODE_ENV` says otherwise), `npm run dev` runs it through `calm dev`.

## calm.config.js and .env

`calm.config.js` overrides the defaults in `calm/config.js`. Secrets (database URI, API keys) belong in `.env`, which is git-ignored. See [Configuration](/configuration).

```js
import { defineConfig } from '#calm';

export default defineConfig({
  pagination: { defaultLimit: 20, maxLimit: 100 },
  auth: { sessionTtlDays: 30, resetTokenTtlMinutes: 30 },
  mail: { from: 'My API <no-reply@example.com>' },
});
```

## calm.lock

Written by `calm create` and updated by `calm add` and `calm upgrade`. Commit it.

```json
{
  "lockfileVersion": 1,
  "calmapi": "2.0.0-alpha.0",
  "template": "api",
  "core": {
    "calm/app.js": "sha256:585bd812cfc3d1343684effb382612d0074b82c7da27ede3673bb4f76df5e4a2",
    "calm/auth/index.js": "sha256:b4633aa522492d2f0065ba052660ca6f12fd813d7c90a824c7f0375ba2b130d1"
  },
  "blocks": {
    "@calmapi/jobs": {
      "version": "1.0.0",
      "source": "@calmapi (bundled)",
      "files": { "app/blocks/jobs/index.js": "sha256:..." }
    }
  }
}
```

`core` holds the hash of each framework file as it was shipped, which is how `calm upgrade` knows whether you edited a file and `calm doctor` reports local changes. `blocks` records what `calm add` installed.

## AGENTS.md and CLAUDE.md

`AGENTS.md` tells AI coding agents (Claude Code, Codex, Cursor, Copilot) how this project is laid out and which rules to follow. `CLAUDE.md` points Claude Code to it. See [AI agents](/ai-agents).

## #calm and #app imports

`package.json` declares [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), so you never write `../../../calm`:

```json
{
  "imports": {
    "#calm": "./calm/index.js",
    "#calm/*": "./calm/*",
    "#app/*": "./app/*"
  }
}
```

```js
import { resource, f, ResourceService, notFound } from '#calm';     // the public API
import { createTestApp } from '#calm/testing.js';                    // any framework file
import { seed } from '#calm/seed.js';
import { defineJob } from '#app/blocks/jobs/index.js';               // your own code
```

Subpath imports need the `.js` extension. Inside services and routes, reach other resources through `this.service('name')` or `ctx.services.name` instead of importing their models.

### What #calm exports

| Export | Use |
|---|---|
| `resource`, `f`, `Field` | Declare resources and fields |
| `ResourceService` | Base class for services |
| `definePlugin` | Declare a plugin (what blocks export) |
| `createApp`, `defineConfig` | Build the app, type-friendly config |
| `CalmError`, `badRequest`, `unauthorized`, `forbidden`, `notFound`, `conflict`, `validationError`, `tooManyRequests` | Errors (see [Errors](/errors)) |
| `hasRole`, `isOwner`, `evaluatePolicy`, `parsePolicy` | Policy helpers |
| `matchesFilter` | Whether a record matches a MongoDB filter, in memory |
| `serialize`, `validateInput`, `standardSchema`, `resourceJSONSchema` | Apply a resource's output and input rules yourself, or describe it as JSON Schema |
| `Reply` | What `ctx.reply()` returns |
| `createToken`, `hashToken` | Random tokens with a prefix, and their SHA-256 for storage |
| `hashPassword`, `verifyPassword` | scrypt helpers |
| `isEncrypted` | Whether a stored value is `.encrypted()` ciphertext |
| `maskToken`, `providerPayloads` | Push helpers: a masked device token, the payload each provider receives |
| `currentRequest` | The current request's context from anywhere (AsyncLocalStorage) |

Blocks import only from `#calm`: the other files in `calm/` are internals that can change between versions.

## How the app boots

`createApp()` does the following, in order:

1. Load `.env`, `calm.config.js` and the defaults; fail fast on invalid config.
2. Load `app/resources/*` and `app/blocks/*`, then run each block's `setup()` with its settings (`blocks.<name>` in `calm.config.js` merged over the block's defaults).
3. Compile every resource into a Mongoose model and create its service.
4. Set up auth, then register routes: auth, block routes, `app/routes.js`, then for each resource its custom routes followed by its CRUD routes.
5. Build the Express app. `listen()` then connects to MongoDB, builds indexes, runs start hooks and prints the banner.

---

Source: https://docs.calmapi.dev/resources

# Resources and fields

A resource is a model, its API and its rules in one file. You declare fields once with `f.*()`, and CalmAPI derives the Mongoose schema, input validation, output visibility, the allowed list queries and the OpenAPI schema from them.

```js
// app/resources/product/product.resource.js
import { resource, f } from '#calm';

export default resource('product', {
  fields: {
    name: f.string().required().max(120).searchable().sortable(),
    price: f.number().required().min(0).filterable().sortable(),
    cost: f.number().hidden(),                       // stored, never returned
    status: f.enum(['draft', 'live']).default('draft').filterable(['eq', 'in']),
    category: f.ref('category').filterable(),
    tags: f.array(f.string().max(30)).max(10).default([]).filterable(),
    owner: f.ref('user').owner(),                    // set from the session
    supplierNote: f.string().visibleTo('owner | admin'),
  },
  policy: {
    list: 'authenticated',
    read: 'authenticated',
    create: 'authenticated',
    update: 'owner | admin',
    delete: 'owner | admin',
  },
});
```

Every record also gets `id`, `createdAt` and `updatedAt` (unless `timestamps: false`). These names are reserved: declaring a field called `id`, `_id`, `createdAt`, `updatedAt` or `__v` throws at boot.

## Field types

| Builder | Stored as | Accepts | Notes |
|---|---|---|---|
| `f.string()` | String | strings | Trimmed by default (`.trim(false)` to keep spaces) |
| `f.text()` | String | strings | Like `string`, not trimmed; for long text |
| `f.email()` | String | valid email | Trimmed and lowercased |
| `f.url()` | String | `http(s)://` URLs | Other schemes (`javascript:`) are rejected |
| `f.password()` | String | strings, 8 to 128 chars | Hashed with scrypt, never returned, cannot be changed with PATCH |
| `f.number()` | Number | finite numbers | `"5"` is rejected: no silent coercion of JSON strings |
| `f.integer()` | Number | whole numbers | |
| `f.boolean()` | Boolean | `true`, `false` | |
| `f.date()` | Date | ISO strings or epoch milliseconds | Returned as ISO strings |
| `f.enum(['a', 'b'])` | String | one of the values | |
| `f.id()` | ObjectId | 24-char hex id | An id that is not a reference |
| `f.ref('category')` | ObjectId | 24-char hex id | Reference to another resource, can be included |
| `f.array(f.string())` | Array | arrays | Every item is validated with the inner field |
| `f.object({ city: f.string() })` | Subdocument | objects | Unknown keys are rejected, no `_id` |
| `f.json()` | Mixed | any JSON | Not validated; only the `exists` filter applies |

`f.ref()` checks that the value is a well-formed id, not that the record exists. If that matters, check it in a service hook (`beforeCreate`).

```js
fields: {
  address: f.object({
    street: f.string().required(),
    city: f.string().required(),
    zip: f.string().pattern(/^\d{5}$/, 'Must be 5 digits'),
  }),
  coordinates: f.array(f.number()).min(2).max(2),
  launchedAt: f.date().min('2020-01-01'),
  settings: f.json().default({}),
}
```

## Modifiers

| Modifier | Effect |
|---|---|
| `.required(message?)` | Must be present on create (unless it has a default). Empty strings and `null` are rejected. |
| `.optional()` | Undo `required()` |
| `.default(value)` | Default value, or a function: `.default(() => new Date())`. Object defaults are cloned per record. |
| `.min(n, message?)` / `.max(n, message?)` | String length, number value, date bound or array item count |
| `.pattern(regex, message?)` | Strings must match |
| `.trim(on = true)`, `.lowercase()`, `.uppercase()` | Normalize strings before validation and storage |
| `.unique()` | Unique index; a duplicate answers `409 CONFLICT` |
| `.index()` | Plain index |
| `.check(fn, message?)` | Custom rule, sync or async: return `true`, or an error message string |
| `.schema(standardSchema)` | Validate with Zod, Valibot, ArkType or any [Standard Schema](https://standardschema.dev) library |
| `.describe(text)`, `.example(value)` | Description and example in the OpenAPI document |
| `.encrypted()` | Stored as AES-256-GCM ciphertext, decrypted on read (see [Encrypted fields](#encrypted-fields)) |
| `.pii()` | Marks personal data for `calm doctor`, the exposure matrix and the privacy block (see [Personal data](#personal-data)) |

```js
fields: {
  sku: f.string().required().uppercase().pattern(/^[A-Z0-9-]{4,20}$/, 'Use 4 to 20 letters, digits or dashes').unique(),
  quantity: f.integer().min(0).check((n) => n % 6 === 0 || 'Sold in packs of 6'),
}
```

## Visibility and write rules

These decide what clients may send and what they get back. They apply to every response, including populated references, [realtime events](/blocks/realtime-sse) and [MCP tools](/blocks/mcp-server).

| Modifier | Returned | Accepted from clients | Typical use |
|---|---|---|---|
| `.hidden()` | never | never (422) | Internal data your service sets: costs, storage keys, flags |
| `.writeOnly()` | never | yes | Secrets the client sends but must not read back |
| `.readOnly()` | yes | never (422) | Values your service computes: slugs, totals, timestamps |
| `.immutable()` | yes | on create only (422 on update) | Email, account type |
| `.writableBy(policy)` | yes | only users matching the policy | `roles: ...writableBy('admin')` |
| `.visibleTo(policy)` | only to users matching the policy, per record | yes | `email: ...visibleTo('owner \| admin')` |

Hidden and write-only fields can never be filtered, sorted, selected with `?fields=` or included. Your service still sees them: hooks receive the full record (except password hashes), and API responses are serialized again on the way out.

`visibleTo` and `writableBy` take the same tokens as [policies](/policies), evaluated against each record. With `'owner'`, it means the owner of *that* record:

```js
// app/resources/user/user.resource.js (from the api template)
export default resource('user', {
  owner: '_id', // a user owns their own record
  fields: {
    name: f.string().required().max(100).searchable().sortable(),
    email: f.email().required().unique().immutable().filterable().visibleTo('owner | admin'),
    password: f.password().required(),
    roles: f.array(f.enum(['user', 'admin'])).default(['user']).writableBy('admin').visibleTo('owner | admin').filterable(),
    status: f.enum(['active', 'disabled']).default('active').writableBy('admin').filterable(),
    avatarUrl: f.url(),
  },
  policy: { list: 'admin', read: 'owner | admin', create: 'admin', update: 'owner | admin', delete: 'admin' },
});
```

## Encrypted fields

`.encrypted()` encrypts a value before it reaches MongoDB and decrypts it when it is read, so database dumps and backups only hold ciphertext while the API, your services and hooks see the plain value:

```js
fields: {
  nationalId: f.string().required().encrypted().visibleTo('owner | admin'),
  webhookSecret: f.string().encrypted().hidden(),
}
```

It needs `CALM_ENCRYPTION_KEYS` (create it with `npx calm keygen --write`). Encryption is about storage, not about who reads the field, so combine it with `.visibleTo()` or `.hidden()`. Ciphertext cannot be queried: an encrypted field cannot also be `.filterable()`, `.sortable()`, `.searchable()`, `.unique()`, `.index()` or `.owner()`, and `f.ref()` and `f.id()` fields cannot be encrypted. Keys and rotation are covered in [Security](/security#encryption-at-rest).

## Personal data

Mark fields that hold personal data with `.pii()`:

```js
fields: {
  nickname: f.string().max(50).pii(),
  licensePlate: f.string().pii().visibleTo('owner | admin'),
  shippingNotes: f.text().pii(),
}
```

`.pii()` does not change what the API accepts or returns. It tells the tools that look at your data:

- The [exposure matrix](/security#exposure-matrix), which [`calm audit`](/audit) tests your API against, flags the field as personal data. The devtools **Security** panel marks it `pii` and highlights it when anyone can read it.
- `calm doctor` warns when anyone can read it (`pii-public`), and notes when every signed-in user can read it on a resource with an owner (`pii-users`). Fix it with `.visibleTo('owner | admin')` or `.hidden()`.
- The [privacy](/blocks/privacy) block removes it when an account is deleted and the records it owned are anonymized.

Fields whose name already says personal data (`email`, `phone`, `address`, `iban`, `salary`, `dateOfBirth`...) are flagged without it. `.pii()` covers the names a pattern cannot guess.

## Query modifiers

| Modifier | Lets clients |
|---|---|
| `.filterable(ops?)` | Filter with `?field=value` and `?field[op]=value`. Without `ops`, the defaults for the type apply (see [Querying](/querying#operators)). |
| `.sortable()` | Sort with `?sort=field` or `?sort=-field`. Also adds an index. |
| `.searchable()` | Be matched by `?q=text` (case-insensitive substring) |

Anything not marked cannot be used in a query: the request fails with `400` instead of silently scanning private data.

## Relations

| Modifier | Effect |
|---|---|
| `f.ref('user').owner()` | Marks the record's owner. Set to the signed-in user on create, read-only and indexed. Powers the `'owner'` policy. One per resource. |
| `.populate()` | Always populate this reference on reads, as if every request had `?include=<field>` |

A populated reference is serialized with the **target** resource's rules for the current viewer, so including `author` never leaks the author's email or password hash. Only fields that could ever be returned are loaded from the database in the first place.

For the `user` resource itself, `owner: '_id'` in the resource options says "a user owns their own record".

## Resource options

```js
resource('product-category', {
  fields: { ... },
  policy: { ... },
  path: '/categories',           // default: '/product-categories'
  collection: 'categories',      // default: 'product_categories'
  timestamps: true,              // createdAt / updatedAt (default true)
  defaultSort: '-createdAt',     // default; '_id' when timestamps is false
  crud: ['list', 'read'],        // which CRUD routes exist: true (all, default), false, or a list
  indexes: [{ fields: { status: 1, createdAt: -1 } }, { fields: { name: 'text' } }],
  owner: '_id',                  // owner field when it is not an f.ref('user').owner() field
  description: 'Product groups', // used in MCP tool descriptions (mcp-server block)
  schemaPlugins: [myMongoosePlugin],
});
```

Names are normalized: `resource('ProductCategory')` and `resource('product-category')` both become `product-category`, served at `/api/product-categories`, stored in `product_categories`, and reachable as `ctx.services.productCategory` or `ctx.services['product-category']`.

Any other key is kept in `def.options`, where [blocks](/blocks) can read it: `softDelete: true` ([soft-delete](/blocks/soft-delete)), `audit: false` ([audit-log](/blocks/audit-log)), `webhooks: false` ([webhooks](/blocks/webhooks)), `onOwnerDelete` and `personalFields` ([privacy](/blocks/privacy)).

## The CRUD routes

| Route | Action | Success | Body |
|---|---|---|---|
| `GET /api/products` | `list` | `200` | `{ data: [...], meta: { total, page, limit, pages } }` |
| `GET /api/products/:id` | `read` | `200` | `{ data }` |
| `POST /api/products` | `create` | `201` | `{ data }` |
| `PATCH /api/products/:id` | `update` | `200` | `{ data }` (partial update) |
| `PUT /api/products/:id` | `update` | `200` | alias of PATCH, hidden from OpenAPI |
| `DELETE /api/products/:id` | `delete` | `204` | empty |

Errors follow one shape (see [Errors](/errors)): `401` when a signed-in user is required, `403` or `404` depending on what the user may see (see [Policies](/policies#401-403-or-404)), `404` for malformed or unknown ids, `422` for invalid bodies and `409` for duplicates on unique fields.

On update, `null` clears an optional field; sending `null` for a required field is a `422`.

## Unknown fields are rejected

Bodies are checked against the fields, so clients cannot write what you did not declare:

```bash
curl -X POST http://localhost:5001/api/products -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Hammer","price":"20","cost":1,"owner":"6acb46a57e4a738ebdd998b9","role":"admin"}'
```

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "requestId": "8a3c1f4e-6d6b-4a0e-9a57-1f2f5b3a9c11",
    "details": {
      "price": "Must be a number",
      "cost": "Is read-only",
      "owner": "Is read-only",
      "role": "Unknown field"
    }
  }
}
```

The messages per field are:

| Message | Cause |
|---|---|
| `Unknown field` | Not declared (set `unknownFields: 'strip'` in config to drop them silently instead) |
| `Is read-only` | `hidden()`, `readOnly()` or an `owner()` field |
| `Cannot be changed after creation` | `immutable()` field in an update |
| `You are not allowed to set this field` | `writableBy()` policy not met |
| `Use POST /api/auth/password (or the reset flow) to change passwords` | Password field in an update |
| `Is required`, `Must be ...`, your own messages | Validation rules |

`id`, `createdAt` and `updatedAt` in a body are ignored, so a client can send back a record it received.

## Standard Schema

Use any [Standard Schema](https://standardschema.dev) validator (Zod 3.24+, Valibot, ArkType...) for rules the built-ins do not cover. It runs after the built-in checks, and its output replaces the value, so transforms work:

```js
import { z } from 'zod'; // npm install zod

fields: {
  website: f.string().schema(z.string().url().endsWith('.org')),
  slug: f.string().schema(z.string().transform((s) => s.toLowerCase().replace(/\s+/g, '-'))),
}
```

Custom routes accept a Standard Schema as their `input` too (see [Custom routes](/routes#validating-input)). The other way round, `standardSchema(def, mode)` exposes a resource's own input rules as a Standard Schema, for scripts or tests that should validate exactly like the API:

```js
import { standardSchema } from '#calm';
import product from '#app/resources/product/product.resource.js';

const result = await standardSchema(product, 'create')['~standard'].validate({ name: 'Saw' });
// { issues: [{ message: 'Is required', path: ['price'] }] }
```

## OpenAPI

The running app serves an OpenAPI 3.1 document at `/api/openapi.json`, generated from fields, policies and route options. Each resource has three schemas (`Product`, `ProductCreate`, `ProductUpdate`); hidden and write-only fields never appear in the output schema. Write it to a file with `npx calm openapi`, or add the [api-docs](/blocks/api-docs) block for an interactive reference.

---

Source: https://docs.calmapi.dev/policies

# Policies

A policy says who may perform an action. Every CRUD action and every custom route has one, and the same rules drive field visibility, [realtime events](/blocks/realtime-sse) and [MCP tool calls](/blocks/mcp-server).

```js
export default resource('post', {
  fields: { ... , author: f.ref('user').owner() },
  policy: {
    list: 'public',
    read: 'public',
    create: 'authenticated',
    update: 'owner | admin',
    delete: 'owner | admin',
  },
});
```

## Tokens

| Token | Allows |
|---|---|
| `'public'` | Anyone, signed in or not |
| `'authenticated'` | Any signed-in user |
| `'owner'` | The record's owner (the resource's `.owner()` field). On `create` it always passes: you become the owner. |
| `'admin'`, `'editor'`, any other word | Users whose `roles` array contains that role |
| `'none'` | Nobody. The route still exists and answers 401, 403 or 404; to remove CRUD routes use the resource's `crud` option. |
| `(ctx) => boolean` | Your own rule (sync or async) |

Aliases: `'auth'` and `'user'` mean `'authenticated'`, `'self'` means `'owner'`, `'nobody'` means `'none'`, and `'role:editor'` is the same as `'editor'`.

## Combining

Alternatives are combined with `|`: the action is allowed if **any** of them allows it. You can also pass an array, which is how you mix strings and functions:

```js
const isPublished = ({ doc }) => doc?.status === 'published';

policy: {
  read: ['owner | editor | admin', isPublished],
}
```

Functions receive `{ user, action, doc, req }`. `doc` is the stored record for routes with an `:id`, and `undefined` for collection routes (`list`, `create`, custom routes without `:id`). Name your functions: the name is what `calm routes` and devtools display.

There is no "and". When you need one, write a function, or narrow what users can see with the service's [scope()](/services#scope).

## Defaults

Leave an action out and it gets a default:

| Action | Default |
|---|---|
| `list`, `read` | `'authenticated'` |
| `create`, `update`, `delete` | `'owner \| admin'` when the resource has an owner field, `'admin'` otherwise |

Custom routes without a `policy` option default to `'authenticated'`. Both cases work, but `calm doctor` warns about them (`policy-defaulted`, `route-policy`) so the intent is written down.

## Owner scoping on lists

`'owner'` on `list` does not reject anyone who is signed in: it **filters**. `list: 'owner | admin'` lets admins list everything and everyone else only their own records:

```js
// app/resources/note/note.resource.js
export default resource('note', {
  fields: { text: f.string().required(), author: f.ref('user').owner() },
  policy: { list: 'owner', read: 'owner', create: 'authenticated', update: 'owner', delete: 'owner' },
});
```

```text
GET /api/notes   as Alice   -> only Alice's notes
GET /api/notes   as Bob     -> only Bob's notes
GET /api/notes   signed out -> 401
```

The same applies to custom routes without `:id`: with `policy: 'owner'`, `ctx.scope` is `'owner'` and service calls that receive `ctx` only see the user's records.

## 401, 403 or 404

For routes with an `:id`, CalmAPI first loads the record (through the service's `scope()`), then applies the policy with the record in hand. The answer is chosen so that private ids are never confirmed to people who cannot see them:

| Situation | Status |
|---|---|
| The route needs a signed-in user and there is no valid session | `401 UNAUTHORIZED` |
| The id is malformed, does not exist, or `scope()` hides it from this user | `404 NOT_FOUND` |
| The user may read the record but not do this (for example edit someone else's post) | `403 FORBIDDEN` |
| The user may not even read the record | `404 NOT_FOUND` |
| Collection routes (`list`, `create`, custom without `:id`): signed in but not allowed | `403 FORBIDDEN` |

With the post resource above, Bob gets `403` when he tries to edit Alice's published post (he can read it), but `404` for her notes, which he cannot read at all.

## Field-level policies

`.visibleTo(policy)` and `.writableBy(policy)` take the same tokens and are evaluated per record:

```js
fields: {
  email: f.email().required().visibleTo('owner | admin'),          // others do not see it
  roles: f.array(f.enum(['user', 'editor', 'admin'])).writableBy('admin'),
  internalRating: f.integer().visibleTo('editor | admin').writableBy('editor | admin'),
}
```

- A field a viewer may not see is left out of the response, including when the record is populated into another one with `?include=`.
- A field a user may not write answers `422` with `You are not allowed to set this field`. On create, `'owner'` passes (the creator becomes the owner).

## Roles

Roles are strings in the user's `roles` array. The `api` template allows `user` and `admin`; add your own to the enum in `user.resource.js`:

```js
roles: f.array(f.enum(['user', 'editor', 'admin'])).default(['user']).writableBy('admin').visibleTo('owner | admin').filterable(),
```

Then use them in policies (`'editor | admin'`) and in code with `hasRole(ctx.user, 'editor')` from `#calm`.

Users cannot give themselves roles: `roles` is `writableBy('admin')`, and `calm doctor` reports an error if the user resource has a writable `roles` field without a `writableBy` rule. To make your first admin, sign up normally, then:

```bash
npx calm admin ada@example.com            # add the admin role
npx calm admin ada@example.com --revoke   # remove it
```

After that, admins can change roles through `PATCH /api/users/:id`.

## Function policies in practice

```js
// Only the author, and only while the post is a draft.
const ownDraft = ({ user, doc }) => Boolean(user && doc && String(doc.author) === user.id && doc.status === 'draft');

// Only users with a verified flag (a boolean field you added to user.resource.js).
const verified = ({ user }) => user?.verified === true;

policy: {
  update: ['admin', ownDraft],
  create: [verified],
}
```

A function that returns `true` allows the action outright, without owner scoping. On `list` there is no `doc`, so filter lists with `scope()` in the service instead.

## Checking policies

```bash
npx calm routes
```

```text
  METHOD  PATH                           POLICY         FROM
  POST    /api/auth/login                public         calm/auth/index.js
  GET     /api/posts/featured            public         app/resources/post/post.routes.js
  POST    /api/posts/:id/publish         owner | admin  app/resources/post/post.routes.js
  GET     /api/posts                     public         app/resources/post/post.resource.js
  PATCH   /api/posts/:id                 owner | admin  app/resources/post/post.resource.js
  GET     /api/users                     admin          app/resources/user/user.resource.js
```

Defaulted policies are shown as `authenticated (default)`. The devtools **Routes** panel shows the same, with a filter for routes whose policy is not explicit.

To see the result of all your rules at once, open the devtools **Security** panel: the [exposure matrix](/security#exposure-matrix) lists, for each resource, what anonymous visitors, signed-in users, owners, each custom role and admins may do, and which fields each of them can read and write. Then check that the running API agrees:

```bash
npx calm audit
```

[`calm audit`](/audit) calls every route as every one of those personas on a throwaway database, and reports each answer that does not match the policy, owner-only lists that return other people's records, and fields that leak to someone who should not see them.

---

Source: https://docs.calmapi.dev/services

# Services and hooks

Every resource has a service: an instance of `ResourceService` that does all reads and writes. CRUD routes, custom routes, blocks and jobs go through it, so logic you put here applies everywhere.

Create `app/resources/<name>/<name>.service.js` (or pass `--service` to `calm make resource`) and override only what you need: hooks for small tweaks, whole methods for full control.

```js
// app/resources/post/post.service.js (from the api template)
import { ResourceService, hasRole } from '#calm';

export default class PostService extends ResourceService {
  // Every query goes through scope(): visitors see published posts, authors also see
  // their own drafts, admins see everything.
  scope({ user } = {}) {
    if (hasRole(user, 'admin')) return {};
    if (user) return { $or: [{ status: 'published' }, { author: user.id }] };
    return { status: 'published' };
  }

  async beforeCreate(data) {
    return {
      ...data,
      slug: await this.uniqueSlug(data.title),
      publishedAt: data.status === 'published' ? new Date() : undefined,
    };
  }

  async beforeUpdate(data, existing) {
    if (data.status === 'published' && existing.status !== 'published') data.publishedAt = new Date();
    return data;
  }

  /** Used by POST /api/posts/:id/publish (post.routes.js). */
  async publish(id, ctx) {
    return this.update(id, { status: 'published' }, ctx);
  }

  async uniqueSlug(title) {
    const base = title.toLowerCase().normalize('NFKD').replace(/[^\w\s-]/g, '').trim().replace(/[\s_-]+/g, '-').slice(0, 80) || 'post';
    let slug = base;
    for (let i = 2; await this.model.exists({ slug }); i++) slug = `${base}-${i}`;
    return slug;
  }
}
```

The class must `export default` and extend `ResourceService`, otherwise the app refuses to boot with a clear message.

## Methods

All methods take the request context `ctx` as their last argument. Pass it along: it carries the user and the owner scope.

| Method | Returns |
|---|---|
| `list({ filter, sort, skip, limit, populate }, ctx)` | `{ items, total }` |
| `get(id, { populate }, ctx)` | the record, or throws `notFound()` |
| `find(filter, ctx)` | an array of records |
| `findOne(filter, ctx)` | a record or `null` |
| `create(data, ctx)` | the created record |
| `update(id, data, ctx)` | the updated record (throws `notFound()` if it is not visible) |
| `remove(id, ctx)` | the deleted record (throws `notFound()` if it is not visible) |

Records are plain objects (Mongoose `lean()`) with `_id`. Every service method (`list`, `get`, `find`, `findOne`, `create`, `update`, `remove`) and every hook works with the whole record, `hidden()` and `writeOnly()` fields included. Password hashes are never included. Return records from a resource route and they are serialized for you (see [Custom routes](/routes#auto-serialization)).

Services trust their input: they do not run field validation or policies. The CRUD routes validate the body before calling `create` and `update`. When you call a service from your own route, validate with the route's `input` option first.

Useful properties: `this.model` (the Mongoose model), `this.def` (the resource definition), `this.app`, `this.log`, `this.events`, `this.name`.

## Hooks

| Hook | Called | Return |
|---|---|---|
| `scope(ctx)` | before every query | a Mongo filter (`{}` for no restriction) |
| `beforeCreate(data, ctx)` | after validation, before insert. The owner field is already set. | the data to insert |
| `afterCreate(doc, ctx)` | after insert | nothing |
| `beforeUpdate(data, existing, ctx)` | before the update, with the current record | the changes to apply |
| `afterUpdate(doc, previous, ctx)` | after the update | nothing |
| `beforeDelete(doc, ctx)` | before delete. Throw to prevent it. | nothing |
| `afterDelete(doc, ctx)` | after delete | nothing |

`before*` hooks are the place to set `hidden()` and `readOnly()` fields, which clients cannot send:

```js
export default class ProductService extends ResourceService {
  async beforeCreate(data) {
    return { ...data, cost: data.price / 2 };           // cost is .hidden()
  }

  async beforeDelete(doc) {
    const orders = await this.service('order').find({ product: doc._id });
    if (orders.length) throw conflict('This product has orders and cannot be deleted');
  }
}
```

(`conflict` is imported from `#calm`, like every [error helper](/errors).)

## scope()

`scope(ctx)` returns a filter that is added to **every** query the service makes: lists, reads, updates, deletes, and the record lookup that authorizes `/:id` routes. A record outside the scope does not exist for that user: it is a `404`.

```js
// Multi-tenancy: everyone only ever sees their organization's data.
scope({ user } = {}) {
  return user ? { org: user.org } : { _id: null }; // signed out: nothing
}
```

`scope()` also applies to calls without a user, which are treated like anonymous visitors. For trusted internal work (jobs, scripts, migrations) pass `{ system: true }` as the context: `scope()` is skipped and the call sees every record.

```js
await ctx.app.service('post').update(id, { status: 'archived' }, { system: true });
```

Service methods return whole records, hidden fields included (password hashes excepted): they are server-side data. Routes serialize them with the resource rules before anything is sent.

## filterFor()

`this.filterFor(ctx, extra)` builds the full filter for a request: your `scope()`, the owner filter when the policy is `'owner'`, and `extra`. Use it whenever you query `this.model` yourself, so custom queries obey the same rules:

```js
async countPublished(ctx) {
  return this.model.countDocuments(this.filterFor(ctx, { status: 'published' }));
}
```

Mongoose casts ids in `find` and `countDocuments`, but not in `aggregate`. In an aggregation pipeline, convert ids yourself. Mongoose's `strictQuery` is on, so conditions on fields the resource does not declare are dropped from filters rather than matching nothing.

## Calling other services

```js
// inside a service
const author = await this.service('user').get(post.author, {}, ctx);

// inside a route handler
const categories = await ctx.services.category.find({}, ctx);
const sub = ctx.services['product-category'];   // or ctx.services.productCategory
```

Go through services rather than importing another resource's model: you keep its scope, hooks and events.

## Overriding whole methods

When hooks are not enough, override the method and call `super`:

```js
async list(query, ctx) {
  const result = await super.list(query, ctx);
  this.log.debug('Listed products', { total: result.total });
  return result;
}
```

## Events

After each write, the service emits an event on the app's in-process bus:

| Event | Payload |
|---|---|
| `<resource>.created` | `{ doc, resource, user }` |
| `<resource>.updated` | `{ doc, previous, resource, user }` |
| `<resource>.deleted` | `{ doc, resource, user }` |
| `auth.registered`, `auth.login`, `auth.password_changed`, `auth.password_reset_requested` | `{ user }` |
| `auth.password_reset` | `{ userId }` |
| `security.login_failed`, `security.account_locked`, `security.forbidden`... | Depends on the event: failed sign-ins, lockouts, bad tokens, rejected writes, `403`s, rate limits (see [Security events](/security#security-events)) |

`user` is the signed-in user who made the change, or `null`. Blocks add their own (`job.completed`, `job.failed`, `<resource>.restored`).

Listeners run after the write, asynchronously. They never break a request: an exception is logged. Patterns are an exact name, `'post.*'` or `'*'`. Register listeners in a small plugin in `app/blocks/` (any folder there with an `index.js` is loaded at boot):

```js
// app/blocks/notifications/index.js
import { definePlugin } from '#calm';

export default definePlugin({
  name: 'notifications',
  setup(calm) {
    calm.on('post.created', async ({ doc, user }) => {
      calm.log.info(`New post "${doc.title}" by ${user?.name ?? 'system'}`);
    });
  },
});
```

`app.events.on()` returns a function that removes the listener, which is handy in tests. For work that must survive a restart or be retried, use the [jobs](/blocks/jobs) block, whose jobs can be triggered by these events.

---

Source: https://docs.calmapi.dev/routes

# Custom routes

CRUD covers most endpoints. For everything else, add routes with the route builder: in `app/resources/<name>/<name>.routes.js` (mounted under the resource path) or in `app/routes.js` (mounted under `/api`).

```js
// app/resources/post/post.routes.js (from the api template)
export default (r) => {
  r.get('/featured', { policy: 'public', summary: 'Latest published posts' }, async (ctx) => {
    const { items } = await ctx.service.list({ filter: { status: 'published' }, sort: { publishedAt: -1 }, limit: 5 }, ctx);
    return items; // raw documents are serialized with the post visibility rules
  });

  r.post('/:id/publish', { policy: 'owner | admin', summary: 'Publish a draft' }, (ctx) => ctx.service.publish(ctx.params.id, ctx));
};
```

This adds `GET /api/posts/featured` and `POST /api/posts/:id/publish`.

## The route builder

`r.get`, `r.post`, `r.put`, `r.patch` and `r.delete` take `(path, options, handler)`; `options` can be left out. Paths are relative to the resource path (or to `/api` in `app/routes.js`) and use Express syntax (`/:id`, `/:id/comments/:commentId`).

| Option | Default | Meaning |
|---|---|---|
| `policy` | `'authenticated'` | Who may call it ([Policies](/policies)). Always set it: `calm doctor` warns when it is missing. |
| `input` | none | Validate the JSON body: an object of `f.*()` fields or a Standard Schema. The result is `ctx.body`. |
| `status` | `200` | Status code for a returned value |
| `summary`, `description`, `tags` | | OpenAPI documentation |
| `middleware` | `[]` | Express middleware run before the handler (after a quick sign-in check), for example an upload parser |
| `rateLimit` | none | `'auth'` for the auth limiter, or `{ windowMs, max }` for a limit on this route only |
| `hidden` | `false` | Leave the route out of OpenAPI and `calm routes` |
| `scope` | none | A permission name for credentials that carry scopes, such as `'reports:export'` for [API keys](/blocks/api-keys#custom-route-scopes) |
| `meta` | `{}` | Anything [blocks](/building-blocks#routes) read from the route in their guards: `{ audit: true }` |

## The handler context

Handlers receive `ctx`:

| Property | What it is |
|---|---|
| `ctx.user` | The signed-in user (with `id` as a string), or `null` |
| `ctx.params`, `ctx.query` | Route parameters and query string |
| `ctx.body` | The validated body when `input` is set, otherwise the raw JSON body |
| `ctx.doc` | For resource routes with `:id`: the record, loaded and authorized (see below) |
| `ctx.service` | This resource's service (resource routes only) |
| `ctx.services` | Every service: `ctx.services.post`, `ctx.services['product-category']` |
| `ctx.scope` | `'owner'` when the policy matched through `owner`, else `null` |
| `ctx.reply(data, { status, meta, headers })` | Build a response with a custom status, `meta` or headers |
| `ctx.serialize(doc, resourceName?)` | Apply a resource's visibility rules to a raw record |
| `ctx.req`, `ctx.res` | The Express request and response |
| `ctx.app`, `ctx.config`, `ctx.log`, `ctx.events` | The app, its config, the logger (every line is tagged with the request id) and the event bus |
| `ctx.session`, `ctx.requestId` | The current session `{ id, expiresAt }` and the request id |
| `ctx.auth` | How the request signed in: `{ via: 'session', scopes: ['*'], id }`, `{ via: 'api-key', scopes, id }` with the [api-keys](/blocks/api-keys) block, or `null` |
| `ctx.push` | [Push notifications](/push-notifications): `ctx.push.send({ to, title, body })` |

Blocks can add more: `ctx.notify()` with [notifications](/blocks/notifications), `ctx.flags` with [feature-flags](/blocks/feature-flags).

## Return values

| Handler returns | Response |
|---|---|
| a value | `200` (or `status`) with `{ "data": value }` |
| `undefined` | `204 No Content` |
| `ctx.reply(data, { status: 201, meta, headers })` | that status, `{ data, meta }` and headers |
| `ctx.reply(undefined, { status: 202 })` | that status with an empty body |
| throws `notFound()`, `forbidden()`, `badRequest()`... | the [error response](/errors) |

```js
import { badRequest, notFound } from '#calm';

export default (r) => {
  r.get('/stats', { policy: 'admin', summary: 'Post counts by status' }, async (ctx) => {
    const [drafts, published] = await Promise.all([
      ctx.service.model.countDocuments({ status: 'draft' }),
      ctx.service.model.countDocuments({ status: 'published' }),
    ]);
    return { drafts, published };                       // 200 { data: { drafts, published } }
  });

  r.post('/import', { policy: 'admin', status: 202 }, async (ctx) => {
    if (!Array.isArray(ctx.body?.items)) throw badRequest('items must be an array');
    ctx.app.background(() => ctx.service.importMany(ctx.body.items)); // your method, runs after the response
    return { queued: ctx.body.items.length };            // 202 { data: { queued } }
  });

  r.get('/by-slug/:slug', { policy: 'public' }, async (ctx) => {
    const post = await ctx.service.findOne({ slug: ctx.params.slug }, ctx);
    if (!post) throw notFound('Post not found');
    return post;                                          // serialized automatically
  });
};
```

Errors thrown in async handlers reach the error handler by themselves (Express 5), so there is no `try/catch` and no `next`.

You can still write to `ctx.res` directly (file downloads, redirects, streams); CalmAPI does not send a second response. Prefer returning values when you can: you get serialization and a consistent shape for free.

## Routes with :id

In a resource's routes file, a path parameter named exactly `id` gets the same treatment as the CRUD routes: the record is loaded through the service's `scope()`, the policy is checked with the record in hand (so `'owner'` means the owner of *this* record), and the answer is `401`, `403` or `404` [as for CRUD](/policies#401-403-or-404). The record is in `ctx.doc`:

```js
r.post('/:id/discount', { policy: 'owner' }, async (ctx) => {
  if (ctx.doc.price < 1) throw badRequest('Too cheap to discount');
  return ctx.service.update(ctx.doc._id, { price: ctx.doc.price - 1 }, ctx);
});
```

`ctx.doc` does not contain `hidden()` fields; load them explicitly when you need one (`ctx.service.model.findById(ctx.doc._id).select('+key').lean()`). Name a parameter differently (`:postId`) when you do not want this behavior.

## Validating input

`input` validates the body before your handler runs. Invalid bodies get a `422` with per-field details, unknown fields included:

```js
import { f } from '#calm';

r.post('/quote', {
  policy: 'public',
  input: { qty: f.integer().required().min(1), coupon: f.string().max(20) },
}, (ctx) => ({ total: ctx.body.qty * 3 }));
```

```json
{ "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "requestId": "...", "details": { "qty": "Must be at least 1" } } }
```

A Standard Schema works too:

```js
import { z } from 'zod';

r.post('/contact', {
  policy: 'public',
  input: z.object({ email: z.string().email(), message: z.string().min(10).max(2000) }),
  rateLimit: { windowMs: 60_000, max: 5 },
}, async (ctx) => {
  await ctx.app.mailer.send({ to: 'team@example.com', subject: 'Contact form', text: `${ctx.body.email}\n\n${ctx.body.message}` });
});
```

## Auto-serialization

Raw records returned from a **resource** route (a record, an array of records, or the `data` of `ctx.reply()`) are serialized with that resource's visibility rules: hidden, write-only and `visibleTo` fields are removed for the current user. This is a safety net, so `return ctx.service.find(...)` never leaks a private field.

It does not look inside other shapes. When you return `{ file, upload }`, or records of another resource, or anything from `app/routes.js` or a block, serialize explicitly:

```js
// app/routes.js
r.get('/me/summary', { policy: 'authenticated' }, async (ctx) => {
  const posts = await ctx.services.post.find({ author: ctx.user.id }, ctx);
  return {
    user: await ctx.serialize(ctx.user, 'user'),
    posts: await Promise.all(posts.map((p) => ctx.serialize(p, 'post'))),
  };
});
```

## Order: custom routes before CRUD

Routes are registered in this order: auth routes, block routes, `app/routes.js`, then for each resource its custom routes followed by its CRUD routes. That is why `GET /api/posts/featured` works: it is registered before `GET /api/posts/:id`, which would otherwise treat `featured` as an id.

If two routes have the same method and path, the first one wins and the app logs a warning at boot.

## Middleware

Express middleware in `middleware` runs after a cheap check that rejects signed-out users when the policy needs a user, and after the [guards](/building-blocks#guards) of your blocks, so an upload parser never runs for anonymous requests or requests a guard refuses. This is how the [storage-local](/blocks/storage-local) block handles uploads:

```js
r.post('/upload', {
  policy: 'authenticated',
  status: 201,
  summary: 'Upload a file (multipart/form-data, field "file")',
  middleware: [uploadMiddleware('file')],
}, async (ctx) => {
  const file = ctx.req.file;
  if (!file) throw badRequest('Send the file as multipart/form-data in a field named "file"');
  return ctx.service.create({ originalName: file.originalname, mimeType: file.mimetype, size: file.size, key: file.filename }, ctx);
});
```

## App-wide routes

`app/routes.js` is for endpoints that do not belong to a resource. Paths are relative to `/api`:

```js
// app/routes.js
export default (r) => {
  r.get('/hello', { policy: 'public', summary: 'Say hello' }, (ctx) => ({
    message: `Hello from ${ctx.config.app.name}`,
    time: new Date().toISOString(),
  }));

  r.get('/dashboard', { policy: 'authenticated' }, async (ctx) => {
    const { total } = await ctx.services.post.list({ limit: 1 }, ctx);
    return { posts: total };
  });
};
```

There is no `ctx.service`, `ctx.doc` or auto-serialization here: use `ctx.services.<name>` and `ctx.serialize(doc, '<name>')`.

---

Source: https://docs.calmapi.dev/querying

# Querying

`GET /api/<resources>` accepts filters, search, sorting, pagination, includes and field selection. Only what you declared on the fields is allowed, so clients can never filter on private data or send raw MongoDB operators.

```text
GET /api/products?status=live&price[gte]=10&price[lt]=50&tags[in]=tools,garden
                 &q=saw&sort=-price,name&page=2&limit=20
                 &include=category&fields=name,price,category
```

```json
{
  "data": [{ "id": "...", "name": "Saw (large)", "price": 30, "category": { "id": "...", "name": "Tools" }, "createdAt": "...", "updatedAt": "..." }],
  "meta": { "total": 41, "page": 2, "limit": 20, "pages": 3 }
}
```

With curl, add `-g` so the square brackets are not read as globs: `curl -g "http://localhost:5001/api/products?price[gte]=10"`.

## Filters

Mark a field `.filterable()` to allow `?field=value` (equality) and `?field[op]=value`:

```js
price: f.number().filterable(),                      // default operators for numbers
status: f.enum(['draft', 'live']).filterable(['eq', 'in']), // only these two
```

```text
?status=live                      status equals "live"
?price[gte]=10&price[lt]=50       10 <= price < 50 (operators on one field combine)
?status[in]=draft,live            one of (comma separated, 1 to 100 values)
?tags=garden                      array contains "garden"
?tags[all]=garden,tools           array contains both
?category[exists]=false           field is missing
?id[in]=6acb46a5...,6acb46a6...   by id (eq, in, nin)
```

### Operators

| Operator | Meaning |
|---|---|
| `eq` (or no operator) | equals |
| `ne` | not equal |
| `gt`, `gte`, `lt`, `lte` | greater or less than (numbers and dates) |
| `in`, `nin` | in / not in a comma separated list |
| `all` | array contains all values |
| `exists` | `true`/`false` (or `1`/`0`) |

Default operators by field type, when you call `.filterable()` without a list:

| Field types | Operators |
|---|---|
| `string`, `text`, `email`, `url`, `enum` | `eq ne in nin exists` |
| `number`, `integer` | `eq ne gt gte lt lte in nin exists` |
| `date` | `eq ne gt gte lt lte exists` |
| `boolean` | `eq ne exists` |
| `id`, `ref` | `eq ne in nin exists` |
| `array` | `eq in nin all exists` |
| `json` | `exists` |

Values are converted to the field's type and checked: numbers must be numbers, booleans `true`/`false`/`1`/`0`, dates anything `new Date()` understands (`2026-01-31`, ISO timestamps), ids 24 hex characters, enum values must be in the list, and `email` values are lowercased. The query string is parsed flat (Express `simple` parser), so nested objects or `$` operators cannot be injected.

## Search

`?q=text` searches every `.searchable()` field with a case-insensitive substring match. The text is escaped, so `?q=(a+)+$` searches for those characters literally. It is limited to 100 characters, and a resource without searchable fields answers `400`.

```js
name: f.string().searchable(),
description: f.text().searchable(),
```

Search uses regular expressions, which cannot use a normal index. That is fine for thousands of records; for large collections, add a text index (`indexes: [{ fields: { name: 'text' } }]`) and a custom route that uses `$text`.

## Sorting

`?sort=` takes a comma separated list; prefix a field with `-` for descending:

```text
?sort=-price,name
```

You can sort by `.sortable()` fields, `id`, and `createdAt`/`updatedAt` (when timestamps are on). Without `sort`, the resource's `defaultSort` applies (`-createdAt` by default). `_id` is always added as a final tie-breaker, so pagination is stable.

## Pagination

| Parameter | Default | Rules |
|---|---|---|
| `page` | `1` | integer, 1 or more |
| `limit` | `pagination.defaultLimit` (20) | integer from 1 to `pagination.maxLimit` (100) |

Every list response has `meta: { total, page, limit, pages }`. Change the defaults in `calm.config.js`:

```js
export default defineConfig({ pagination: { defaultLimit: 25, maxLimit: 200 } });
```

## Include references

`?include=` populates `f.ref()` fields (and arrays of refs), comma separated. It works on lists and on `GET /:id`:

```text
GET /api/posts?include=author
GET /api/products/6acb46a5...?include=category,owner
```

The included record is serialized with the **target** resource's rules for the current viewer: a visitor including `author` sees the author's name, not their email, roles or password hash. Fields marked `.populate()` are always included. Hidden refs cannot be included.

## Pick fields

`?fields=name,price` returns only those fields (plus `id`, `createdAt` and `updatedAt`). Unknown, hidden and write-only fields are rejected.

## Errors

Anything not allowed fails the whole request with `400 BAD_REQUEST` and one message per parameter, so mistakes are never silently ignored:

```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query",
    "requestId": "86f489d3-d343-4d90-a614-86bdca30b700",
    "details": {
      "cost": "Not filterable. Filterable fields: name, price, status, owner",
      "status[ne]": "Operator \"ne\" not allowed on status. Allowed: eq, in",
      "sort": "Cannot sort by \"cost\". Sortable: id, name, price, createdAt, updatedAt",
      "limit": "Must be an integer between 1 and 100"
    }
  }
}
```

Unknown query parameters are rejected the same way. If your frontend adds its own parameters (cache busters, tracking), strip them before calling the API, or handle them in a custom route.

## From code

Inside services and routes, the same options are available as plain objects:

```js
const { items, total } = await ctx.service.list(
  { filter: { status: 'published' }, sort: { publishedAt: -1 }, skip: 0, limit: 5, populate: [{ path: 'author', select: 'name' }] },
  ctx,
);
```

Code is trusted: filters there are not restricted to filterable fields. When you populate by hand, always pass a `select` (or serialize the result) so private fields of the referenced record are not exposed. `calm doctor` warns about `populate()` calls without one.

---

Source: https://docs.calmapi.dev/authentication

# Authentication

Projects created from the `api` template have accounts, sessions and password flows under `/api/auth`. The code is in `calm/auth/`, so you can read and change every decision. For two-factor authentication, add the [totp](/blocks/totp) block.

Auth turns on when `config.auth.enabled` is `true` (the default) **and** the project has a `user` resource with an `email` field and an `f.password()` field. The `minimal` template has no `user` resource and therefore no auth.

## Endpoints

| Method and path | Policy | Body | Success |
|---|---|---|---|
| `POST /api/auth/register` | public, rate limited | user fields (`name`, `email`, `password`...) | `201 { data: { user, token, expiresAt } }` |
| `POST /api/auth/login` | public, rate limited | `{ email, password }` | `200 { data: { user, token, expiresAt } }` |
| `POST /api/auth/logout` | authenticated | | `204`, ends this session |
| `POST /api/auth/logout-all` | authenticated | | `204`, ends every session of the user |
| `GET /api/auth/me` | authenticated | | `200 { data: user }` |
| `PATCH /api/auth/me` | authenticated | profile fields | `200 { data: user }` |
| `POST /api/auth/password` | authenticated, rate limited | `{ currentPassword, newPassword }` | `204`, other sessions end |
| `POST /api/auth/password/forgot` | public, rate limited | `{ email }` | `202`, always the same answer |
| `POST /api/auth/password/reset` | public, rate limited | `{ token, password }` | `204`, every session ends |
| `GET /api/auth/sessions` | authenticated | | `200 { data: [session...] }` |
| `DELETE /api/auth/sessions/:sessionId` | authenticated | | `204` |
| `POST /api/auth/devices` | authenticated | `{ token, platform, name?, appVersion?, locale? }` | `201 { data: device }`, registers a device for [push notifications](/push-notifications#registering-devices) |
| `GET /api/auth/devices` | authenticated | | `200 { data: [device...] }` |
| `DELETE /api/auth/devices/:deviceId` | authenticated | | `204` |
| `POST /api/auth/devices/unregister` | authenticated | `{ token }` | `204`, stops push notifications to the device holding that token |
| `POST /api/auth/devices/opened` | authenticated | `{ pushId?, data? }` | `204`, reports a tapped notification (emits `push.opened`) |

### Register

```bash
curl -X POST http://localhost:5001/api/auth/register -H 'Content-Type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","password":"correct-horse-battery"}'
```

```json
{
  "data": {
    "user": { "id": "6acb46a57e4a738ebdd998b1", "name": "Ada Lovelace", "email": "ada@example.com", "roles": ["user"], "status": "active", "createdAt": "2026-10-11T08:19:49.069Z", "updatedAt": "2026-10-11T08:19:49.069Z" },
    "token": "calm_M_vAh-pIohIgNEe8gapu1LMoYxlH6oYvepNVGWtYPWk",
    "expiresAt": "2026-11-10T08:19:49.085Z"
  }
}
```

The body is validated against the `user` resource, like `POST /api/users`, but with no signed-in user: fields protected by `writableBy('admin')` (`roles`, `status`) are rejected with `422`. A duplicate email is `409 CONFLICT`. A password shorter than 8 characters, a common one, or one that contains the user's email or name is `422` (see [Password rules](#password-rules)). Set `auth.register: false` to close sign-ups (`403`).

### Login

```bash
curl -X POST http://localhost:5001/api/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct-horse-battery"}'
```

Same response shape as register. A wrong email and a wrong password both answer `401` with `Invalid email or password`, after the same amount of work, so the response does not reveal whether an account exists. A user whose `status` is `disabled` (or `deleting`, while the [privacy](/blocks/privacy) block erases the account) gets `403`. After 5 failed attempts for the same email, sign-ins for it answer `429` for 15 minutes (see [Account lockout](#account-lockout)).

With the [totp](/blocks/totp) block, users who turned on two-factor authentication get `{ mfaRequired: true, mfaToken, methods, expiresAt }` instead of a session, and finish with `POST /api/auth/2fa/verify`.

### Use the token

Send it as a bearer token on every request:

```bash
curl http://localhost:5001/api/auth/me -H "Authorization: Bearer calm_M_vAh-pIohIgNEe8gapu1LMoYxlH6oYvepNVGWtYPWk"
```

Only the `Authorization` header is read: tokens in query strings or cookies are ignored. A malformed, expired or revoked token answers `401 Session is invalid or has expired` on **every** route, public ones included, so clients notice a dead session instead of silently browsing as a visitor.

### Profile

`PATCH /api/auth/me` updates your own user with the `user` resource rules: `email` is immutable, `roles` and `status` are admin only, and the password cannot be changed here (use `/api/auth/password`).

```bash
curl -X PATCH http://localhost:5001/api/auth/me -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Ada King"}'
```

### Change password

```bash
curl -X POST http://localhost:5001/api/auth/password -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"currentPassword":"correct-horse-battery","newPassword":"a-much-longer-passphrase"}'
```

`204` on success. A wrong current password is `422` with `details.currentPassword`. Every other session of the user is revoked; the current one stays signed in.

### Sessions

```bash
curl http://localhost:5001/api/auth/sessions -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": [
    { "id": "6acb46a57e4a738ebdd998b3", "current": true, "createdAt": "2026-10-11T08:19:49.389Z", "lastUsedAt": "2026-10-11T08:19:49.388Z", "expiresAt": "2026-11-10T08:19:49.388Z", "ip": "127.0.0.1", "userAgent": "curl/8.5.0" },
    { "id": "6acb46a57e4a738ebdd998b2", "current": false, "createdAt": "2026-10-11T08:19:49.087Z", "lastUsedAt": "2026-10-11T08:19:49.085Z", "expiresAt": "2026-11-10T08:19:49.085Z", "ip": "127.0.0.1", "userAgent": "curl/8.5.0" }
  ]
}
```

`DELETE /api/auth/sessions/:sessionId` revokes one of your sessions (for a "sign out other devices" screen), `POST /api/auth/logout-all` revokes all of them. Ending a session also stops [push notifications](/push-notifications#devices-follow-sessions) to the devices it registered.

## Password reset

1. The user asks for a reset link:

   ```bash
   curl -X POST http://localhost:5001/api/auth/password/forgot -H 'Content-Type: application/json' -d '{"email":"ada@example.com"}'
   ```

   ```json
   { "data": { "message": "If that email is registered, a reset link is on its way." } }
   ```

   The answer (`202`) is identical whether or not the email exists, and the work happens in the background so timing does not tell either.

2. CalmAPI emails a link to `auth.resetUrl` (default `${APP_URL}/reset-password`) with a `token` query parameter. The link is valid for `auth.resetTokenTtlMinutes` (30). In development the email lands in the devtools **Mail** panel; in production you need a mail block ([Resend](/blocks/mail-resend) or [SMTP](/blocks/mail-smtp)).

3. Your frontend's reset page reads the token and posts the new password:

   ```bash
   curl -X POST http://localhost:5001/api/auth/password/reset -H 'Content-Type: application/json' \
     -d '{"token":"reset_f9l4o-ANKiqUMnW512f5ksuDjZLNh1GwNJSDXCIRGwc","password":"a-brand-new-password"}'
   ```

   `204` on success. Every session of the user is revoked and other pending reset links stop working. An unknown, expired or already used token answers:

   ```json
   { "error": { "code": "INVALID_TOKEN", "message": "This reset link is invalid or has expired", "requestId": "..." } }
   ```

## Rate limits

Register, login, password change, forgot and reset share the **auth** limiter: 10 requests per 15 minutes per client IP and endpoint (`rateLimit.auth`). Every `/api` route also has a **global** limit of 300 requests per minute per IP (`rateLimit.global`). Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; over the limit you get `429 RATE_LIMITED` with `Retry-After`.

Limits are counted per process in memory. Behind a proxy set `TRUST_PROXY` so the real client IP is used, and with several instances add [rate-limit-mongo](/blocks/rate-limit-mongo). Rate limiting is off in tests (`mode: 'test'`).

## Account lockout

Rate limits count requests per IP. Lockout counts failed sign-ins per account, so guesses spread over many IPs still hit it. After 5 failed sign-ins for the same email within 15 minutes, that email is locked for 15 minutes. While it is locked, every sign-in answers `429`, even with the right password:

```json
{ "error": { "code": "RATE_LIMITED", "message": "Too many failed sign-in attempts. Try again in 15 minutes.", "requestId": "..." } }
```

- Attempts are counted per email address whether or not an account exists, so a lock does not reveal which emails are registered.
- A successful sign-in clears the count, and so does a password reset.
- Attempts are stored in `calm_login_attempts`, keyed by a hash of the email, and expire on their own (TTL index).
- A failed sign-in emits `security.login_failed`, a new lock `security.account_locked`, and a sign-in during a lock `security.locked_login_attempt` (see [Security events](/security#security-events)).

Change the numbers with `auth.lockout` (see [Configuration](#configuration)); `maxAttempts: 0` turns lockout off.

## Password rules

`f.password()` fields accept 8 to 128 characters. There are no composition rules ("one digit, one symbol"), but passwords that are easy to guess are refused with `422`:

| Rule | Message |
|---|---|
| One of the most common leaked passwords (`password123`, `qwerty123`, `iloveyou`...) | `This password is too common, choose another one` |
| One repeated character or a straight run (`aaaaaaaa`, `23456789`, `abcdefghij`) | `This password is too easy to guess` |
| Contains the part of the email before the `@` (when it has 4 or more characters) | `Your password must not contain your email address` |
| Contains a word of the user's name (4 or more characters) | `Your password must not contain your name` |

The first two rules apply wherever a password field is validated. The email and name rules apply on register, password change and reset. The list of common passwords is in `calm/auth/password-policy.js`; add your own words (your product name, for example) there.

## Configuration

```js
// calm.config.js
export default defineConfig({
  auth: {
    enabled: true,
    register: true,               // false: no public sign-up
    sessionTtlDays: 30,
    resetTokenTtlMinutes: 30,
    resetUrl: 'https://app.example.com/reset-password', // default: APP_URL + /reset-password
    password: { logN: 15, r: 8, p: 3 },                 // scrypt cost
    lockout: { maxAttempts: 5, windowMinutes: 15, lockMinutes: 15 }, // per account, 0 disables
  },
  rateLimit: { auth: { windowMs: 15 * 60_000, max: 10 } },
});
```

## Design choices

- **Opaque session tokens, not JWT.** A token is 32 random bytes (`calm_...`). Only its SHA-256 hash is stored (collection `calm_sessions`), so a database leak does not leak usable sessions. There is no signing secret to configure, rotate or leak, and logout really ends a session. The price is one indexed lookup per request.
- **scrypt from `node:crypto`.** No native addon to compile. Parameters follow the OWASP cheat sheet (N=2^15, r=8, p=3) and are stored inside each hash, so raising `auth.password` later upgrades users transparently the next time they log in.
- **No account enumeration.** Login spends the same time for unknown emails, forgot always answers the same, and lockout counts unknown emails like real ones.
- **Single-use reset tokens.** Random, hashed at rest (collection `calm_password_resets`), claimed atomically, short-lived, and they revoke every session when used.
- **Expiry is automatic.** Both collections have TTL indexes, so MongoDB deletes expired sessions and tokens itself. `lastUsedAt` is refreshed at most every 5 minutes.
- **Disabled accounts stop at once.** Setting `status: 'disabled'` rejects their existing sessions on the next request.

## In your code

`ctx.user` is the signed-in user (the stored record with `id` as a string, without the password hash), `ctx.session` is `{ id, expiresAt }`. The auth service is available as `app.auth.service` (for example `app.auth.service.createSession(user)` in a script). Events: `auth.registered`, `auth.login`, `auth.password_changed`, `auth.password_reset_requested`, `auth.password_reset`, plus the [`security.*` events](/security#security-events) for failed sign-ins, lockouts and bad tokens.

Two-factor authentication is available as the [totp](/blocks/totp) block, passwordless sign-in by email as the [magic-link](/blocks/magic-link) block, and API keys for scripts as the [api-keys](/blocks/api-keys) block. They plug into login with the `loginChallenge` hook, the shared [auth service helpers](/building-blocks#the-auth-service) (lockout, disabled accounts, `completeLogin`) and `calm.authenticate` for other credentials, which you can use for your own sign-in methods too. There are no social logins built in. Since `calm/auth/` is your code, you can add them, and the session model stays the same.

---

Source: https://docs.calmapi.dev/push-notifications

# Push notifications

`app.push` sends notifications to your users' phones and browsers. Apps register a device token once, and your code sends to a user, not to tokens.

In development nothing leaves your machine. Every notification lands in the devtools **Push** panel, drawn the way an iPhone, an Android phone and a desktop browser would show it, next to the exact payload Apple, Google, Expo and the browser receive. [Simulated devices](#simulated-devices) answer like real phones that are offline, muted or uninstalled, so you see what your app does in the cases that usually only show up in production. When you are ready, add a [transport block](#delivering-for-real) and the same code delivers for real.

To send one notification to the inbox, the phone and the mailbox at once, with per-user preferences and quiet hours, use the [notifications](/blocks/notifications) block on top of `app.push`.

## Send a notification

```js
// app/resources/order/order.routes.js
r.post('/:id/ship', { policy: 'admin' }, async (ctx) => {
  const order = await ctx.service.update(ctx.params.id, { status: 'shipped' }, ctx);
  await ctx.push.send({
    to: order.customer,                  // a user id: every device they registered
    title: 'Your order shipped',
    body: 'It arrives Thursday between 9 and 12.',
    url: `/orders/${order.id}`,          // opened on tap, also sent as data.url
    data: { orderId: String(order.id) },
  });
  return order;
});
```

`ctx.push` is available in routes and services, `app.push` everywhere else (jobs get `{ app }`, plugins get `calm.push`).

`send()` resolves to `{ id, status, devices, results }`:

| `status` | Meaning |
|---|---|
| `captured` | Recorded in devtools (and `t.pushes` in tests), not delivered: development or tests without a transport |
| `sent` | Accepted for every device: by the transport, or by the simulator for [simulated devices](#simulated-devices) |
| `partial` | Some devices failed. The delivery log in devtools says which and why. |
| `failed` | No device received it, or there is no transport in production |
| `no-devices` | The user has no registered devices |

An invalid message throws a `422` with the field errors, like any other validation error. Delivery problems never throw: a push should not fail the request that triggered it. They are in the result, the log and devtools.

## Who receives it

| Option | Sends to |
|---|---|
| `to` | A user id (or an array of them): every device those users registered |
| `deviceIds` | Specific devices by id |
| `tokens` | Raw device tokens, with `platform` (`ios`, `android` or `web`, default `android`). Use this when you keep tokens yourself. |

## The message

| Field | Type | Notes |
|---|---|---|
| `title` | string, up to 250 | About 36 characters show on an iPhone, 40 on Android, 45 in a browser |
| `subtitle` | string | iPhone only, under the title |
| `body` | string, up to 2000 | About 4 lines on an iPhone, one line (46 characters) on a collapsed Android notification |
| `image` | https URL | A picture in the expanded notification. iOS needs a notification service extension in the app. |
| `icon` | https URL | Browser notifications |
| `url` | string | Where a tap should go (`/orders/42` or `myapp://orders/42`), added to `data.url` |
| `badge` | integer, 0 or more | The number on the iPhone app icon |
| `sound` | string or `false` | `default` unless the message is silent. `false` for none. |
| `channel` | string | Android notification channel id |
| `category` | string | iOS category, for notification actions |
| `group` | string | iOS thread: notifications with the same group are stacked together |
| `collapseId` | string, up to 64 | A newer notification with the same id replaces the older one on the device (APNs `apns-collapse-id`, FCM `collapse_key` and `tag`, Expo `collapseId` and `tag`, Web Push `tag`) |
| `priority` | `high` or `normal` | `high` (default) is shown right away, `normal` may wait to save battery |
| `ttl` | seconds | How long the provider keeps trying an offline device |
| `silent` | boolean | No banner and no sound: the app wakes in the background with `data`, which is then required |
| `data` | object | Delivered to the app, never shown. FCM only carries strings, so other values are sent as JSON text. |

A message needs a `title` or a `body`, or `silent: true` with `data`.

Payloads are limited to 4 KB by every provider. Devtools shows the size of each one and warns before a provider would reject it.

## Registering devices

Apps register their push token after sign in, with the user's session:

| Endpoint | Body | Returns |
|---|---|---|
| `POST /api/auth/devices` | `{ token, platform, name?, appVersion?, locale? }` | `201 { data: device }` |
| `GET /api/auth/devices` | | `200 { data: [device...] }`, your devices |
| `DELETE /api/auth/devices/:deviceId` | | `204` |
| `POST /api/auth/devices/unregister` | `{ token }` | `204`, turns notifications off for the device holding that token |
| `POST /api/auth/devices/opened` | `{ pushId?, data? }` | `204`, reports that the user tapped a notification (emits `push.opened`) |

`platform` is `ios`, `android` or `web`. Tokens are never returned in full (`a3f9c2…b7d3f8`). Registering a token that is already known moves it to the current user and session, which is what you want when someone signs out and another person signs in on the same phone. Tokens starting with `sim_` are reserved for simulated devices (`422`).

Apps know their own token, not the device id, so a "notifications" switch in the app's settings calls `POST /api/auth/devices/unregister` with the token to turn them off, and `POST /api/auth/devices` to turn them back on.

With Expo:

```js
import * as Notifications from 'expo-notifications';
import { Platform } from 'react-native';

const { data: token } = await Notifications.getExpoPushTokenAsync({ projectId });
await fetch(`${API_URL}/api/auth/devices`, {
  method: 'POST',
  headers: { authorization: `Bearer ${session}`, 'content-type': 'application/json' },
  body: JSON.stringify({ token, platform: Platform.OS === 'ios' ? 'ios' : 'android' }),
});
```

With Firebase (Android, iOS or the web), send the token from `getToken()` the same way.

Devices are stored in the `calm_devices` collection. They are not a resource, so there are no CRUD routes for them beyond the ones above, and tokens never appear in other API responses. When a provider says a token stopped working (the app was uninstalled), the device is removed for you.

### Devices follow sessions

A device belongs to the session that registered it. When that session ends, the phone stops getting notifications, so nobody keeps receiving someone else's notifications after they signed out:

- Signing out (`/auth/logout`), signing out everywhere, revoking a session, a password change (other sessions end) and a password reset remove the devices of those sessions.
- Devices of sessions that expired are skipped and removed the next time you send to them. The delivery log says so.
- `GET /api/auth/devices` shows `signedIn: true` for devices bound to a session.

There is nothing to call on sign out. Devices registered with another credential (an [API key](/blocks/api-keys)) are not bound to a session and stay until they are removed. `config.auth.devicesFollowSessions` (default `true`) controls the removal at sign out.

## In development: the Push panel

Open **Push** in [devtools](/devtools#push). For every notification:

![The devtools Push panel: a notification shown on an iPhone lock screen and in the Android notification shade, with a warning that the body is cut off on Android](/images/devtools-push.webp)

- **Preview**: the iPhone lock screen, the Android notification shade and a desktop browser notification, closed or expanded, at real device widths and type sizes, so text cuts off where a phone cuts it.
- **Payloads**: the exact JSON for APNs, FCM, Expo and Web Push, with its size against the 4 KB limit.
- **Warnings**: a title or body that will be cut off, data that looks sensitive (`password`, `token`, `secret`...), non-string data for FCM, payloads a provider would reject.
- **Delivery**: what happened on each device, step by step: which transport took it (or the simulator), the provider's answer, the receipt that came later, whether it was shown on the lock screen, and a link to the request that sent it.

**New notification** composes one with a live preview and sends it through the same `app.push.send()` your code uses. **Send again** reopens a sent one in the composer, and **Copy as code** gives you the `ctx.push.send()` call for it.

Agents see the same notifications with the [`calm_pushes`](/ai-agents#calm-mcp-tools-for-coding-agents) tool.

### Simulated devices

No phone yet, or no phone that is offline right now? **Devices** (in the Push panel) adds devices to any user, as many as you like: an iPhone, an Android phone and a browser, each with its own behavior. A simulated device answers like a real phone would, and is never sent to a real provider, even when a transport is installed. In production, simulated devices are skipped.

| Behavior | What happens |
|---|---|
| Delivers | Accepted, then shown on the device's lock screen |
| Offline | Accepted, and shown when the device comes back online (**Bring online**) |
| Notifications off | Accepted and never shown. Providers cannot tell, and neither can your server. |
| App uninstalled | The provider answers `DeviceNotRegistered`: the device is removed |
| Invalid token | The provider answers `InvalidRegistration` (malformed, or replaced by a new token): the device is removed |
| Rate limited | The provider answers `MessageRateExceeded`: too many notifications to this device |

Change a device's behavior at any time from its row. Each device can also:

- **Send test**: send it a notification right from devtools.
- **Rotate** its token: the provider gives the app a new token and the old one stops working. The app registers the new one, and the old device fails once on the next send and is removed, just as your server would find out in production.
- **Uninstall app**: the next send fails with `DeviceNotRegistered` and removes the device.
- **Remove**: unregister it, as the app would when the user turns notifications off.

Click a simulated device to open it as a phone: its own lock screen with every notification it received, newest first, and which ones are waiting (offline) or hidden (notifications off). **Bring online** shows the waiting ones, **Clear** empties the lock screen, and tapping a notification opens it: the app "goes to" its `url`, and `push.opened` is emitted with `{ id, device, url, data }`, the event your app would report. The lock screen follows new notifications live, so keep it open while you trigger them from your app.

### Your own phone

To try a real device in development, install a [transport block](#delivering-for-real), then either let your app register its token, or paste the token in devtools: **Devices**, **Add device**, **Real token** (for example the Expo push token your app logs). Real devices go through the transport and arrive on your phone. Their rows show which transport each one goes through.

## Delivering for real

Add the block that matches how your app receives notifications:

| Block | Use it for |
|---|---|
| [`push-expo`](/blocks/push-expo) | Expo and React Native apps using `expo-notifications` |
| [`push-fcm`](/blocks/push-fcm) | Native Android and iOS apps and web apps using the Firebase SDK (iOS goes through FCM's APNs integration) |

```bash
npx calm add push-expo
npx calm add push-fcm      # both, if some devices register Expo tokens and others native ones
```

Several transports can be active at once. Each device goes to the transport that takes its token: push-expo takes Expo push tokens, push-fcm the native ones, so one `send()` reaches both kinds of apps.

With a transport installed:

- **Development** delivers to real tokens, so you can test on your own phone. Simulated devices stay in devtools.
- **Tests** keep capturing notifications in `t.pushes` and never call the provider.
- **Production** delivers, removes tokens the provider reports as gone, and logs failures.

In production without a transport, nothing is sent: `send()` returns `failed` and an error is logged.

### Your own transport

A transport is an object with a `name`, a `send(message, devices, { id })` method that returns one result per device, and optionally `accepts(device)` to take only the tokens it understands:

```js
import { definePlugin, providerPayloads } from '#calm';

export default definePlugin({
  name: 'push-onesignal',
  setup(calm) {
    calm.push.use({
      name: 'onesignal',
      accepts: (device) => device.token.startsWith('onesignal:'),
      async send(message, devices) {
        return Promise.all(devices.map(async (device) => {
          const payload = providerPayloads(message, device.token).fcm.payload; // or apns, expo, web
          // deliver it ...
          return { ok: true, id: 'provider-message-id' };
          // or { ok: false, error: 'reason', unregistered: true } to remove the device
        }));
      },
    });
  },
});
```

`devices` holds `{ id, user, token, platform, name }` for real devices only. `providerPayloads()` builds the same payloads devtools shows. A device goes to the first transport whose `accepts()` says yes, otherwise to a transport without `accepts()`. Import from `#calm` only: `providerPayloads` and `maskToken` are exported there.

When the provider reports later (a receipt), call `app.push.receipt(pushId, deviceId, { ok, error, unregistered, transport })` with the `id` your `send()` received. It lands in the same delivery log, removes the device when `unregistered` is `true`, and emits `push.receipt`.

## Testing

Notifications are captured in tests, with everything devtools shows:

```js
test('shipping an order notifies the customer', async () => {
  const customer = await t.signup();
  await t.post('/auth/devices', { token: 'test-token-1', platform: 'ios' }, customer);
  const order = await createOrder(customer);

  await t.post(`/orders/${order.id}/ship`, {}, admin);

  const push = t.pushes.at(-1);
  assert.equal(push.message.title, 'Your order shipped');
  assert.equal(push.devices[0].platform, 'ios');
  assert.deepEqual(push.warnings.filter((w) => w.level !== 'info'), []);
});
```

Each record has `message`, `devices` (tokens masked), `payloads`, `warnings`, `status` and `log`.

Simulated devices work in tests too, and answer at once. Create one directly to see what your code does when a phone was uninstalled:

```js
test('an uninstalled app removes the device', async () => {
  const user = await t.signup();
  await t.app.push.devices.create({ user: user.id, platform: 'ios', token: 'sim_ios_test1', simulated: true, behavior: 'uninstalled' });

  const res = await t.app.push.send({ to: user.id, title: 'Hello' });
  assert.equal(res.status, 'failed');
  assert.equal(await t.app.push.devices.countDocuments({ user: user.id }), 0);
});
```

## Events

| Event | When | Payload |
|---|---|---|
| `push.sent` | A send finished with any status but `failed` | `{ id, status, devices }` |
| `push.failed` | No device received it | `{ id, status, devices }` |
| `push.receipt` | A provider reported later (Expo receipts, the simulator) | `{ id, device, ok, error, unregistered }` |
| `push.opened` | The app reported a tap (`POST /api/auth/devices/opened`), or a notification was tapped on a simulated phone | `{ id, user, device, url, data, simulated }`. `data` comes from the client: only act on the user's own records |
| `push.simulated` | A simulated device showed a notification, kept it waiting (offline) or hid it (notifications off) | `{ id, device, state }` |

Use them for metrics or an audit trail:

```js
calm.on('push.failed', ({ id, devices }) => calm.log.warn('Push failed', { id, devices }));
```

## Good practice

- **Send an id, not the content.** Payloads travel through Apple, Google or a browser vendor and are shown on a lock screen. Put `{ orderId }` in `data` and let the app fetch the details from your API. Devtools warns about keys that look sensitive.
- **Lead with the point.** A closed Android notification shows one line of the body.
- **Send to many users from a [job](/blocks/jobs)**, not from the request.
- **Let people turn notifications off**: per device with `POST /api/auth/devices/unregister`, or per type and with quiet hours through the [notifications](/blocks/notifications) block's preferences.

---

Source: https://docs.calmapi.dev/errors

# Errors

Every error that leaves the API has the same shape, whatever caused it:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "requestId": "5c397446-0c18-4cfe-99be-d08c78419bec",
    "details": { "price": "Must be a number", "role": "Unknown field" }
  }
}
```

| Key | Always | Meaning |
|---|---|---|
| `code` | yes | Stable, machine readable. Switch on this in clients. |
| `message` | yes | Human readable and safe to show |
| `requestId` | yes | Same as the `X-Request-Id` response header. Search logs and devtools by it. |
| `details` | sometimes | One message per field or query parameter |

## Codes

| Status | Code | When |
|---|---|---|
| 400 | `BAD_REQUEST` | Invalid list query, a JSON body nested too deep or with too many values (`jsonLimits`), or `badRequest()` from your code |
| 400 | `INVALID_JSON` | The body is not valid JSON |
| 400 | `INVALID_TOKEN` | Password reset token unknown, expired or used |
| 401 | `UNAUTHORIZED` | No valid session where one is needed, or wrong login |
| 403 | `FORBIDDEN` | Signed in but not allowed |
| 404 | `NOT_FOUND` | Unknown route, malformed id, missing record, or a record the user may not see |
| 409 | `CONFLICT` | Duplicate value on a `.unique()` field |
| 413 | `PAYLOAD_TOO_LARGE` | Body larger than `bodyLimit` (1 MB) |
| 422 | `VALIDATION_ERROR` | Body failed validation; see `details` |
| 429 | `RATE_LIMITED` | Too many requests (see `Retry-After`), or a sign-in for a locked account |
| 500 | `INTERNAL_ERROR` | Anything unexpected |

## Throwing errors

Import the helpers from `#calm` and throw. Express 5 forwards errors from async handlers, so there is no `try/catch` or `next(err)`:

```js
import { badRequest, unauthorized, forbidden, notFound, conflict, validationError, tooManyRequests, CalmError } from '#calm';

throw badRequest('items must be an array');                          // 400 BAD_REQUEST
throw badRequest('Invalid date range', { to: 'Must be after from' }); // with details
throw unauthorized();                                                 // 401 "Authentication required"
throw forbidden('Only the organizer can cancel this event');          // 403
throw notFound('Invoice not found');                                  // 404
throw conflict('This product has orders', { product: 'In use' });     // 409
throw validationError({ email: 'Already invited' });                  // 422 "Validation failed"
throw tooManyRequests();                                              // 429
throw new CalmError(402, 'PAYMENT_REQUIRED', 'Upgrade your plan to add more projects');
```

| Helper | Signature | Default message |
|---|---|---|
| `badRequest` | `(message?, details?)` | `Bad request` |
| `unauthorized` | `(message?)` | `Authentication required` |
| `forbidden` | `(message?)` | `You do not have permission to do this` |
| `notFound` | `(message?)` | `Resource not found` |
| `conflict` | `(message?, details?)` | `Resource already exists` |
| `validationError` | `(details, message?)` | `Validation failed` |
| `tooManyRequests` | `(message?)` | `Too many requests, slow down` |
| `new CalmError` | `(status, code, message, details?)` | |

Messages of `CalmError`s are sent to clients as they are, so write them for your users.

## What other errors become

Errors that are not `CalmError`s are translated in `calm/errors.js`:

| Thrown | Response |
|---|---|
| Malformed JSON body | `400 INVALID_JSON` |
| Body over `bodyLimit` | `413 PAYLOAD_TOO_LARGE` |
| Other `400` errors from Express middleware | `400 BAD_REQUEST` with their message |
| Mongoose `CastError` on `_id` | `404 NOT_FOUND` |
| Mongoose `CastError` on another path | `422 VALIDATION_ERROR` with `{ <path>: "Invalid value for <path>" }` |
| Mongoose `ValidationError` | `422 VALIDATION_ERROR` with one message per path |
| MongoDB duplicate key (`E11000`) | `409 CONFLICT`, `"email already exists"`, details `{ email: "Already taken" }` |
| Anything else | `500 INTERNAL_ERROR`, `"Something went wrong"` |

## Nothing internal leaks

For a `500`, the client only ever gets `Something went wrong`. The real message and stack trace go to the log (with the request id) and to devtools:

```js
r.get('/boom', { policy: 'public' }, () => {
  throw new Error('db password is hunter2');
});
```

```json
{ "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong", "requestId": "0b7e6f3c-5f8e-4d7b-9a43-2c1f8d7e6a10" } }
```

In **development** mode only, `500` responses also include the original error, which saves a trip to the terminal:

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong",
    "requestId": "0b7e6f3c-5f8e-4d7b-9a43-2c1f8d7e6a10",
    "debug": { "message": "db password is hunter2", "stack": "Error: db password is hunter2\n    at ..." }
  }
}
```

The devtools **Requests** panel shows the same error with a clickable stack trace.

## Request ids

Every response has an `X-Request-Id` header. A client can send its own (letters, digits, `.`, `_`, `-`, up to 128 characters) to correlate logs across services; otherwise a UUID is generated. Every log line written during the request carries it, including your own `ctx.log.info(...)` calls.

## Handling errors in clients

```js
const res = await fetch('/api/posts', { method: 'POST', headers, body: JSON.stringify(post) });
if (!res.ok) {
  const { error } = await res.json();
  if (error.code === 'VALIDATION_ERROR') showFieldErrors(error.details);
  else if (error.code === 'UNAUTHORIZED') redirectToLogin();
  else toast(`${error.message} (ref ${error.requestId})`);
}
```

`204` responses have no body; do not call `res.json()` on them.

---

Source: https://docs.calmapi.dev/configuration

# Configuration

Configuration comes from three places, merged in this order:

1. The defaults in `calm/config.js` (listed below).
2. `calm.config.js` in your project.
3. Overrides passed to `createApp({ config })`, which is what tests use.

Before that, `.env` is loaded into `process.env` (with Node's built-in `process.loadEnvFile`). Keep secrets in `.env` and the environment; keep `calm.config.js` for behavior, and commit it.

## calm.config.js

```js
import { defineConfig } from '#calm';

export default defineConfig({
  pagination: { defaultLimit: 20, maxLimit: 100 },
  auth: { sessionTtlDays: 30, resetTokenTtlMinutes: 30 },
  mail: { from: 'My API <no-reply@example.com>' },
});
```

It can also export a function of the environment and mode:

```js
export default defineConfig(({ env, mode }) => ({
  bodyLimit: mode === 'production' ? '256kb' : '5mb',
  cors: { origins: env.CORS_ORIGINS?.split(',') ?? ['http://localhost:3000'] },
}));
```

`defineConfig` returns its argument unchanged; it only helps editors autocomplete. Nested objects are merged key by key, so `auth: { register: false }` keeps the other auth defaults. Arrays are replaced.

## Mode

The mode is `NODE_ENV`, and **defaults to `production`** when `NODE_ENV` is not set. `calm dev` sets `development`, tests use `test`.

| | development | test | production |
|---|---|---|---|
| Devtools at `/_calm` | on | off | off, cannot be enabled |
| CORS without `CORS_ORIGINS` | any origin (`*`) | any origin | no origin |
| `APP_URL` | optional | optional | **required** |
| Log format | pretty | pretty, silent | JSON lines |
| `Strict-Transport-Security` header | | | sent |
| Rate limits | on | off | on |
| `500` responses include `debug` | yes | | |

Only `development` and `test` relax the rules. Any other value (`staging`, `preview`, unset) runs as production: CORS needs an explicit list, `APP_URL` is required and devtools stay off. The raw value is available as `config.nodeEnv`.

## Validation at boot

The app refuses to start, with a readable message, when:

- `MONGODB_URI` is not set (`db.uri`);
- the mode is `production` and `APP_URL` is not set.

```text
Invalid configuration:
  - APP_URL must be set in production (used in emails and links)
```

## Every key

| Key | Default | Notes |
|---|---|---|
| `app.name` | `name` in package.json | Banner, emails, OpenAPI title |
| `app.version` | `version` in package.json | |
| `app.url` | `APP_URL`, else `http://localhost:<port>` | Public URL of the API, used in reset links and OpenAPI `servers` |
| `port` | `PORT`, else `5001` | |
| `host` | `HOST`, else all interfaces | |
| `apiPrefix` | `'/api'` | Where every route is mounted |
| `trustProxy` | `TRUST_PROXY`, else `false` | Express `trust proxy`. `'true'`, `'false'`, a hop count (`1`) or a value like `'loopback'` |
| `bodyLimit` | `'1mb'` | Maximum JSON body |
| `jsonLimits` | `{ maxDepth: 20, maxKeys: 10000 }` | Deepest nesting and most values a JSON body may have; more is a `400` (see [Security](/security#json-guard)) |
| `db.uri` | `MONGODB_URI` | Required |
| `db.autoIndex` | `true` | Build indexes declared on fields at startup |
| `db.connectRetries` | `5` | Attempts with exponential backoff (up to 10 s apart) |
| `cors.origins` | `CORS_ORIGINS` (comma separated), else `[]` in production and `'*'` otherwise | Allowed browser origins |
| `cors.credentials` | `false` | Send `Access-Control-Allow-Credentials` (not needed for bearer tokens) |
| `cors.maxAge` | `600` | Preflight cache, in seconds |
| `cors.exposeHeaders` | `[]` | Response headers browsers may read, besides `X-Request-Id`, the rate limit headers, `Retry-After` and `Idempotent-Replayed` |
| `pagination.defaultLimit` | `20` | Page size when `?limit` is absent |
| `pagination.maxLimit` | `100` | Largest `?limit` allowed |
| `unknownFields` | `'reject'` | Unknown body fields are a `422`. Any other value (`'strip'`) drops them silently. |
| `rateLimit.enabled` | `true` (`false` in test mode) | |
| `rateLimit.global` | `{ windowMs: 60000, max: 300 }` | Every `/api` route, per IP |
| `rateLimit.auth` | `{ windowMs: 900000, max: 10 }` | Login, register, password routes, per IP and route |
| `auth.enabled` | `true` | Auth also needs a `user` resource |
| `auth.register` | `true` | `false` closes public sign-up |
| `auth.sessionTtlDays` | `30` | |
| `auth.resetTokenTtlMinutes` | `30` | |
| `auth.resetUrl` | `<app.url>/reset-password` | The page of your frontend that receives `?token=` |
| `auth.password` | `{ logN: 15, r: 8, p: 3 }` | scrypt cost; length rules live on `f.password()` (8 to 128 characters) |
| `auth.lockout` | `{ maxAttempts: 5, windowMinutes: 15, lockMinutes: 15 }` | Per account [lockout](/authentication#account-lockout) after failed sign-ins; `maxAttempts: 0` turns it off |
| `auth.devicesFollowSessions` | `true` | Remove push devices when the session that registered them ends (see [Devices follow sessions](/push-notifications#devices-follow-sessions)) |
| `encryption.keys` | `CALM_ENCRYPTION_KEYS` | Keys for `.encrypted()` fields. Keep them in the environment, not in this file. |
| `openapi.enabled` | `true` | Serve the OpenAPI document |
| `openapi.path` | `'/openapi.json'` | Relative to `apiPrefix` |
| `devtools.enabled` | `true` in development | Forced off in production |
| `log.level` | `LOG_LEVEL`, else `info` (`silent` in tests) | `debug`, `info`, `warn`, `error`, `silent` |
| `log.format` | `json` in production, else `pretty` | |
| `shutdownTimeoutMs` | `10000` | How long open connections may finish on shutdown |
| `mail.from` | `<app.name> <no-reply@localhost>` | Sender for app emails |
| `blocks` | `{}` | Settings per block, merged over the block's defaults: `blocks: { webhooks: { maxEndpointsPerUser: 5 } }`. See each block's page. |
| `plugins` | none | Extra plugins (`definePlugin(...)` objects) besides `app/blocks` |

Read the effective configuration anywhere through `ctx.config` or `app.config`.

## Environment variables

| Variable | Used for |
|---|---|
| `NODE_ENV` | `development` or `test`; anything else (or unset) runs as production |
| `MONGODB_URI` | Database connection string (required) |
| `APP_URL` | Public URL (required in production) |
| `PORT`, `HOST` | Where to listen (default `5001`, all interfaces) |
| `CORS_ORIGINS` | Comma separated allowed origins, for example `https://app.example.com,https://admin.example.com` |
| `TRUST_PROXY` | Set behind a load balancer, usually `1` |
| `LOG_LEVEL` | `debug`, `info`, `warn`, `error`, `silent` |
| `CALM_SKIP_ENV_FILE` | `1` to ignore `.env` |
| `CALM_MAIL_PRINT` | `1` to print email bodies to the console in development |
| `CALM_ENCRYPTION_KEYS` | Keys for `.encrypted()` fields: `k2:<base64>,k1:<base64>`, the first one encrypts. Create with `npx calm keygen --write` (see [Encryption at rest](/security#encryption-at-rest)) |
| `MONGODB_TEST_URI` | Server used by `createTestApp` and `calm audit` (default `mongodb://127.0.0.1:27017`) |
| `CALM_TEST_LOG` | Log level inside tests, for example `info` |
| `CALM_DEBUG` | Print stack traces for CLI errors |

Blocks add their own variables (for example `JOBS_WORKER`, `RESEND_API_KEY`); `calm add` appends them to `.env.example` and `.env`. Blocks declare the variables they read, so `calm doctor` reports required ones that are missing, and the devtools **Blocks** panel shows which are set (never the values of secret ones).

```ini
# .env (never commit it)
MONGODB_URI=mongodb://127.0.0.1:27017/my_api
APP_URL=http://localhost:5001
PORT=5001
# CORS_ORIGINS=https://app.example.com
# TRUST_PROXY=1
# LOG_LEVEL=info
```

---

Source: https://docs.calmapi.dev/devtools

# Devtools

In development, every CalmAPI app serves a dashboard at **`http://localhost:5001/_calm`**. It shows what your API is doing right now: requests with their MongoDB queries, logs, emails, push notifications on simulated phones, routes, resources, data and the blocks you installed, plus a playground to call the API as any user. It also shows what an AI agent is changing in your project, and who can access what.

```bash
npm run dev
# open http://localhost:5001/_calm
```

The collector is part of your app (`calm/devtools/index.js`). The interface is the `@calmapi/devtools` package, a dev dependency of every new project. If it is missing, `/_calm` shows how to install it (`npm install -D @calmapi/devtools`) and the JSON API keeps working.

## Panels

### Requests

A live list of every request (over Server-Sent Events): method, path, status, duration, the user who made it, and how many MongoDB queries it ran. Quick filters show **Errors**, **Slow** requests (300 ms or more) and **N+1** suspects (more than 10 queries). A second view lists **background queries** that ran outside any request (jobs, startup).

Open a request to see:

- **Timeline**: the request and each query as a waterfall, with log lines placed in time.
- **Queries**: every MongoDB command with its filter, duration and document count. Repeated query shapes are flagged. **Explain** runs the query planner and tells you whether an index was used or the collection was scanned (`COLLSCAN`).
- **Request** and **Response**: headers and bodies. Passwords, tokens, keys and other secret-looking values are redacted in both (in responses the first characters of a long value stay, so you can tell them apart), and the `Authorization` header is shortened.
- **Logs**: everything logged during the request, linked by request id.
- **Error**: the original error and stack trace, with links that open the file in VS Code.

From there you can copy the request as `curl`, edit it in the Playground, replay it, or replay it as the user who made it.

Requests that carry an `X-Calm-Agent` header (the [`calm_http`](/ai-agents#calm-mcp-tools-for-coding-agents) tool sends it) are marked as sent by an AI agent, with its name, and the **Agent** filter shows only those.

### Activity

A live feed of what is happening to the project, read from `.calm/activity.jsonl` (see [Watching an agent work](/ai-agents#watching-an-agent-work)): agent tool calls, file changes with their diffs, marked as made by an agent or by you, server restarts and crashes with their error output. Filter by agent, files or server events.

### Logs

A live tail of the app log with level filters, text search and a link from each line to the request that wrote it.

### Mail

In development, nothing is delivered: emails go to this inbox instead, password reset links included. The empty state shows a `curl` command (and a Playground shortcut) to trigger a reset email.

### Push

Every [push notification](/push-notifications) the app sent, live, as it would appear on an iPhone lock screen, in the Android notification shade and as a desktop browser notification. Switch between closed and expanded; previews use real device widths and type sizes, so text is cut off where a phone cuts it. Each notification also shows:

- **Payloads**: the exact JSON for APNs, FCM, Expo and Web Push, with its size against the 4 KB limit.
- **Warnings**: titles and bodies that will be cut off, data keys that look sensitive, non-string data for FCM, payloads a provider would reject.
- **Delivery**: what happened on each device, step by step: the transport that took it (or the simulator), the provider's answer, receipts that came later, whether the phone showed it, and the request that sent it.

**New notification** composes one with a live preview and sends it through `app.push.send()`; **Send again** reopens a sent one in the composer and **Copy as code** gives you the `ctx.push.send()` call.

**Devices** lists every registered device with its user, masked token, the transport it goes through and when it was last seen. **Add device** gives any user as many devices as you like:

- **Simulated** iPhones, Android phones and browsers, each with a behavior: delivers, offline, notifications off, app uninstalled, invalid token or rate limited. They answer like real phones and never reach a real provider. See [Simulated devices](/push-notifications#simulated-devices).
- **Real tokens** pasted from your phone (an Expo or FCM token), delivered through the installed transport.

From a device's row you can change its behavior, send it a test, **Rotate** its token (the old one fails once and is removed, as in production) or **Remove** it. Click a simulated device to open it as a **phone**: its own lock screen with the notifications it received, the ones waiting while it is offline and the ones hidden because notifications are off. **Bring online**, **Uninstall app**, **Clear** and tapping a notification (which emits `push.opened`) are there too, and the lock screen updates live.

Without a transport block, notifications to real devices are only captured here. With [push-expo](/blocks/push-expo) or [push-fcm](/blocks/push-fcm) installed (or both), real devices receive them in development too.

### Routes

Every endpoint grouped by resource, block or source, with its policy and the file that defines it. Filter by policy, and spot routes whose policy is **not explicit**.

### Resources

A diagram of how resources reference each other, then each resource with its policies (defaulted ones highlighted), owner field and fields. Each field shows its type and flags (`hidden`, `readOnly`, `filterable`...) and whether it is readable (R) and writable (W) through the API.

### Data

Browse the documents of each resource with the **privacy lens**: for each record, what MongoDB stores next to what the API returns, and why each missing field is missing (`hidden`, `password`, `visible to owner | admin`...). **View as** switches the viewer between anonymous and any user, so you can check exactly what Alice sees of Bob's records. Password hashes are masked.

**Sample data** adds 10 records that look real to the resource you are looking at: names that look like names, prices like prices, values from enums, dates in the past or the future depending on the field name, and references to records that exist (referenced resources get a few records first). Records are created through the service, so validation and hooks run. When there are no users yet, demo users are created to own the records, and their email and password are shown. From a terminal: [`calm seed`](/cli#calm-seed).

### Blocks

Every block in the app, from [`calm add`](/blocks) or [written here](/building-blocks):

- **Origin**: the address and version it was installed from (`calm.lock`), or "your own block", and the files you changed since installing it.
- **Hooks**: the extension points it uses, such as a guard, an authenticator, named policies, the events it listens to, a push or mail transport, what it provides on `app.ext`, doctor checks and devtools panels.
- **Environment**: each variable it declares, set or missing (missing required ones are flagged, and the panel's badge counts blocks with missing variables). The values of secret variables never leave the server.
- **Options**: its settings after `calm.config.js` overrides, with secret-looking keys redacted.
- **Routes**: every route it adds, with its policy.

### Playground

Send requests to your API with route suggestions and sample bodies built from the resource fields. **Act as** signs you in as any user: devtools creates a real session for them and keeps it in memory for the Playground and replays. It is the quickest way to test policies.

### Doctor

The runtime checks of `calm doctor` (configuration, policies, exposed secrets, personal data exposure, unknown references), grouped by level and updated live. Run `npx calm doctor` in a terminal to add the static checks on your source files. See [Security](/security#what-calm-doctor-checks).

### Security

Who can access what, and what happened:

- **Access**: the [exposure matrix](/security#exposure-matrix), per resource: which actions anonymous visitors, users, owners, custom roles and admins may perform, and which fields each can read and write.
- **Events**: the [security events](/security#security-events) of the dev server, live: failed sign-ins, lockouts, bad tokens, rejected writes, `403`s.
- **Posture**: sessions, password rules, lockout, rate limits, CORS, encryption keys and encrypted fields, JSON limits and security headers.

**Run audit** runs [`calm audit`](/audit) on a throwaway database on the dev server's MongoDB and shows the result in the matrix.

### Block panels

Blocks can add panels, listed under **Blocks** in the sidebar:

| Block | Panel |
|---|---|
| [webhooks](/blocks/webhooks) | Endpoints with their status, the latest deliveries with status codes, errors and next retries, and how many are pending |
| [notifications](/blocks/notifications) | Every notification type with its channels, and the latest inbox entries |
| [api-keys](/blocks/api-keys) | Keys with owner, prefix, scopes, status and last use |
| [feature-flags](/blocks/feature-flags) | Every flag with its rollout, targeting, variants and last change |
| [jobs](/blocks/jobs) | Queue statistics and recent jobs |
| [realtime-sse](/blocks/realtime-sse) | Connected subscribers and pending tickets |
| storage blocks | Their configuration |

Your own block adds one with [`calm.devtools.panel()`](/building-blocks#extension-points).

### Keyboard shortcuts

| Key | Action |
|---|---|
| `/` | Focus the filter |
| `j` / `k` | Next / previous item |
| `Enter` | Open the selected item |
| `Esc` | Close the detail view |
| `1` to `9` | Switch panel |
| `Ctrl + Enter` | Send (Playground, Push) |
| `n` | New notification (Push) |
| `?` | Show the shortcuts |

The theme follows your system, or pick light or dark in the top bar.

## Safety model

Devtools can read your data and create sessions, so it is locked down:

- **Development only.** It is on when the mode is `development` (`calm dev`). In production it is forced off, even if `calm.config.js` turns it on. MongoDB command monitoring is only enabled while devtools is on.
- **This machine only.** Every `/_calm` request must arrive on a loopback socket (`127.0.0.1` or `::1`), with a `Host` header of `localhost`, `127.0.0.1` or `::1`, and without proxy headers (`X-Forwarded-For`, `Forwarded`). Anything else gets a plain `404`, which also defeats DNS rebinding.
- **No cross-site writes.** Requests that change something (act as, explain, clear, run audit, sample data, send a test notification, add or change a device) need an `X-Calm-Devtools: 1` header, which a page on another site cannot send. `/_calm` has no CORS headers, a strict Content-Security-Policy and refuses to be framed.
- **Secrets stay out.** Request and response bodies are stored with secret-looking values redacted, the `Cookie` header is redacted, and the `Authorization` header is shortened. Block environment variables marked secret are never sent to the page.
- **Bounded memory.** It keeps the last 300 requests, 1,000 log lines, 100 emails, 100 push notifications, 200 background queries, 500 activity events and 300 security events. Push records never hold a full device token.

"Act as" is logged (`Devtools: acting as ada@example.com`) and creates an ordinary session that expires like any other.

## For tools and agents

The panels use a small JSON API under `/_calm/api` that you can call from scripts on the same machine (writes need the `X-Calm-Devtools: 1` header):

| Endpoint | Returns |
|---|---|
| `GET /_calm/api/overview` | App, runtime, database, resources, routes, and blocks (origin, changed files, hooks, env vars without secret values, options, routes) |
| `GET /_calm/api/requests`, `GET /_calm/api/requests/:id` | Recent requests, one request in full |
| `GET /_calm/api/logs`, `GET /_calm/api/mails` | Recent logs and emails |
| `GET /_calm/api/pushes` | Recent push notifications: message, devices, payloads, warnings and delivery log |
| `GET /_calm/api/devices?user=<userId>` | Registered and simulated devices (tokens masked), with the transport each goes through |
| `POST /_calm/api/devices` `{ userId, platform, behavior?, name?, token? }` | Adds a simulated device, or a real one when `token` is given |
| `GET /_calm/api/devices/behaviors` | The simulated behaviors and what each does |
| `PATCH /_calm/api/devices/:id` `{ behavior?, name? }` | Changes a device (behavior: simulated devices only) |
| `POST /_calm/api/devices/:id/rotate` | Rotates a simulated device's token: returns the new device, the old one fails on the next send |
| `GET /_calm/api/devices/:id/inbox` | A simulated device's lock screen |
| `POST /_calm/api/devices/:id/online` | Brings an offline device back and shows what was waiting |
| `POST /_calm/api/devices/:id/inbox/:pushId/open` | Taps a notification on the lock screen (emits `push.opened`) |
| `DELETE /_calm/api/devices/:id/inbox`, `DELETE /_calm/api/devices/:id` | Clears a lock screen, removes a device |
| `POST /_calm/api/push/test` `{ userId \| deviceIds, ...message }` | Sends a notification through `app.push.send()` |
| `POST /_calm/api/seed` `{ resource, count }` | Creates sample records (up to 200) through the services |
| `GET /_calm/api/doctor` | Runtime doctor findings |
| `GET /_calm/api/activity` | Project activity from `.calm/activity.jsonl`, newest first |
| `GET /_calm/api/security` | Exposure matrix, security events and posture |
| `POST /_calm/api/audit` | Runs the security audit on a throwaway database and returns the report |
| `GET /_calm/api/resources/:name/docs?as=<userId>` | Stored vs returned documents |
| `POST /_calm/api/act-as` `{ userId }` | A session token for that user |

The [`calm mcp`](/ai-agents) server uses this API to give coding agents the recent requests, logs, emails, push notifications and security events of your dev server, and to sign in as other users for `calm_http`.

---

Source: https://docs.calmapi.dev/testing

# Testing

CalmAPI tests are plain [`node:test`](https://nodejs.org/api/test.html) files that call your API over HTTP. `createTestApp()` boots your app against a throwaway database on a random port, and helpers sign users up and send requests.

```js
// test/posts.test.js (from the api template)
import { test, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'node:path';
import { createTestApp } from '#calm/testing.js';

let t;
before(async () => {
  t = await createTestApp({ root: join(import.meta.dirname, '..') });
});
after(() => t.close());

test('signed-in users write posts, visitors only see published ones', async () => {
  const alice = await t.signup();

  const draft = await t.post('/posts', { title: 'Hello world', body: 'First!' }, alice);
  assert.equal(draft.status, 201);
  assert.equal(draft.body.data.slug, 'hello-world');

  const anonymous = await t.get('/posts');
  assert.equal(anonymous.body.meta.total, 0, 'drafts are not public');
});

test('only the author (or an admin) can edit a post', async () => {
  const alice = await t.signup();
  const bob = await t.signup();
  const post = await t.post('/posts', { title: 'Mine', body: '...', status: 'published' }, alice);

  const edit = await t.patch(`/posts/${post.body.data.id}`, { title: 'Hacked' }, bob);
  assert.equal(edit.status, 403);
});
```

```bash
npm test
```

`npm test` runs `node --test`, which finds `test/**/*.test.js`. It needs a MongoDB server.

## createTestApp(options)

```js
const t = await createTestApp({ root, config, baseUri });
```

| Option | Meaning |
|---|---|
| `root` | The project folder (default `process.cwd()`) |
| `config` | Config overrides, merged over everything else (see below) |
| `baseUri` | MongoDB server to create the test database on (default `MONGODB_TEST_URI`) |

It creates a database named `calm_test_<time>_<random>` on `MONGODB_TEST_URI` (default `mongodb://127.0.0.1:27017`), starts the app with `mode: 'test'` and listens on a random port. In test mode rate limits are off, logs are silent, devtools is off and password hashing uses cheap parameters so tests stay fast. `.encrypted()` fields work without setup: tests use `CALM_ENCRYPTION_KEYS` when it is set, and a random key otherwise.

```bash
MONGODB_TEST_URI=mongodb://localhost:27018 npm test   # another server
CALM_TEST_LOG=info npm test                           # see the app logs
```

## The test client

| Member | Does |
|---|---|
| `t.get(path, auth?)` | `GET` |
| `t.post(path, body?, auth?)` | `POST` with a JSON body |
| `t.patch(path, body?, auth?)`, `t.put(path, body?, auth?)` | `PATCH`, `PUT` |
| `t.delete(path, auth?)` | `DELETE` |
| `t.request(method, path, body?, auth?)` | Any method |
| `t.signup({ name?, email?, password?, roles? })` | Registers a user through `/api/auth/register` and returns `{ token, user, id, email, password }`. `roles` are written straight to the database. |
| `t.idle()` | Waits for background work: event listeners, emails, `app.background()` tasks |
| `t.mails` | Emails the app sent (captured, never delivered), oldest first |
| `t.pushes` | [Push notifications](/push-notifications#testing) the app sent: `{ message, devices, payloads, warnings, status, log }`, oldest first |
| `t.app` | The app: `t.app.model('post')`, `t.app.service('post')`, `t.app.events`, `t.app.mailer`... |
| `t.origin` | `http://127.0.0.1:<port>`, for raw `fetch` calls |
| `t.close()` | Stops the server, drops the database and disconnects |

Paths are relative to the API prefix: `t.get('/posts')` calls `/api/posts`. Paths that already start with `/api`, `/health` or `/_calm` are used as they are.

`auth` is either the object returned by `t.signup()` or a token string. Every helper resolves to `{ status, body, headers }`, with `body` parsed as JSON (or `null` for `204`).

## Recipes

### Admins and roles

```js
const admin = await t.signup({ name: 'Root', roles: ['user', 'admin'] });
assert.equal((await t.get('/users', admin)).status, 200);
```

### Emails and password resets

```js
await t.post('/auth/password/forgot', { email: alice.email });
await t.idle(); // the email is sent in the background
const token = t.mails.at(-1).meta.token;
assert.equal((await t.post('/auth/password/reset', { token, password: 'new-password-1' })).status, 204);
```

### Push notifications

Nothing is delivered in tests, even with a transport block installed: every notification is recorded in `t.pushes`, with the message, the devices (tokens masked), the payload for each provider, the warnings devtools would show, the status and the delivery log.

```js
await t.post('/auth/devices', { token: 'test-token-1', platform: 'ios' }, alice);
await t.post(`/orders/${order.id}/ship`, {}, admin);

const push = t.pushes.at(-1);
assert.equal(push.message.title, 'Your order shipped');
assert.equal(push.status, 'captured');
assert.equal(push.devices[0].platform, 'ios');
```

[Simulated devices](/push-notifications#testing) work in tests too, to check what happens when a phone was uninstalled or is offline.

### Sample data

`calm/seed.js` builds records that look real from your field definitions, the same code as [`calm seed`](/cli#calm-seed) and the devtools **Sample data** button. Use it when a test needs a full list, not one record:

```js
import { seed } from '#calm/seed.js';

before(async () => {
  t = await createTestApp({ root: join(import.meta.dirname, '..') });
  await seed(t.app, { resource: 'product', count: 30, seed: 42 });
});

test('lists are paginated', async () => {
  const alice = await t.signup();
  const page = await t.get('/products?limit=10', alice);
  assert.equal(page.body.data.length, 10);
});
```

`seed(app, { resource, resources, count, users, seed })` creates `count` records (default 10) of each resource, plus a few records of the resources they reference when those are empty. Records are validated like API input and created through the services, so hooks run. When the database has no users yet, `users` demo users (default 3) are created to own the records. It resolves to `{ created: { product: 30, user: 3 }, users: [{ email, password }] }`, so a test can sign in as a demo user with `t.post('/auth/login', users[0])`. `seed: 42` makes names, numbers and choices repeat between runs.

### Block settings

Blocks read their settings from `calm.config.js` `blocks`, so a test app can use other ones:

```js
const t = await createTestApp({ root, config: { blocks: { webhooks: { retrySchedule: [20, 20] } } } });
```

### Events

```js
const seen = [];
const off = t.app.events.on('post.*', (payload, name) => seen.push(name));
await t.post('/posts', { title: 'Evented', body: 'x' }, alice);
await t.idle();
off();
assert.deepEqual(seen, ['post.created']);
```

### Rate limits on

```js
const limited = await createTestApp({ root, config: { rateLimit: { enabled: true, auth: { windowMs: 60_000, max: 3 } } } });
```

### Reading the database directly

```js
const stored = await t.app.model('product').findById(id).select('+cost').lean();
assert.equal(stored.cost, 10); // a hidden field, set by the service
```

## Generated tests

`calm make resource` writes `test/<plural>.test.js` with two tests: create, read and list as a signed-in user, and a `401` for signed-out requests. It is skipped when the project has no `user` resource, and when required references would need fixtures it cannot guess. Use it as a starting point.

## In CI

Run MongoDB as a service and point `MONGODB_TEST_URI` at it. With GitHub Actions:

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mongo:
        image: mongo:8
        ports: ['27017:27017']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
      - run: npx calm doctor --ci
      - run: npm test
        env: { MONGODB_TEST_URI: 'mongodb://127.0.0.1:27017' }
      - run: npx calm audit --ci
        env: { MONGODB_TEST_URI: 'mongodb://127.0.0.1:27017' }
```

`calm audit` uses the same throwaway database setup to call every route as every kind of user. See [Security audit](/audit).

---

Source: https://docs.calmapi.dev/audit

# Security audit

`calm audit` tests the authorization of your API from the outside. It calls every route as every kind of user and checks each answer against your policies and field rules. It runs on a throwaway database, so your data is never touched.

```bash
npx calm audit
```

Policies and field rules say what should happen. The audit shows what actually happens, including bugs in services, hooks and custom code that a static check cannot see.

## What it does

1. Boots your app (your own `calm/` and `app/` code) with `createTestApp` on a throwaway database on `MONGODB_TEST_URI` (default `mongodb://127.0.0.1:27017`). Rate limits and login lockout are off for the run, and the database is dropped at the end.
2. Signs up one user per persona: the owner, another user, an admin, and one user for each custom role your policies use. Anonymous calls carry no token.
3. Seeds a valid record for every resource from its field definitions, referenced resources first. Records the owner cannot create through the API are created through the service. A resource whose required fields it cannot fill (a `.pattern()`, a `.check()` or a Standard Schema without a default) gets fewer checks.
4. Calls `list`, `read`, `create`, `update` and `delete` on every resource as every persona, and compares each answer with the [exposure matrix](/security#exposure-matrix).
5. Runs probes against each resource and against the auth routes.

Without a `user` resource (the `minimal` template), only anonymous calls are made.

## What it checks

| Check | Passes when |
|---|---|
| Status codes | Allowed actions answer `200`, `201` or `204`; denied ones answer `401`, `403` or `404` |
| Owner-only lists | With `'owner'` on `list`, every returned record belongs to the caller |
| Field leaks | No response contains a field the persona may not read, or a key that is not a declared field |
| Mass assignment | A create that sets a hidden, read-only or owner field is rejected with `422` |
| Operator injection | `?x[$ne]=1` answers `400` |
| Page size cap | `?limit=100000` answers `400` |
| Unknown filters | `?definitelyNotAField=1` answers `400` |
| Error hygiene | A malformed id answers `404`, without stack traces or database errors |
| Forged token | A made-up bearer token answers `401` |
| Token in the query string | `/api/auth/me?token=<valid token>` answers `401` (only the header counts) |
| Account enumeration | A wrong password and an unknown email get the same status and message |

Some cells are skipped, not failed: an allowed action that answers `404` on a resource whose service has its own `scope()` (the scope may hide the record on purpose), and actions decided by a policy function.

## Reading the output

On a new project from the `api` template:

```text
  Auditing on a throwaway database...

  CalmAPI audit

  post /posts  (custom scope)
    action  Anonymous  Signed-in user  Owner    Admin
    list    ✔ allow    ✔ allow         ✔ allow  ✔ allow
    read    ~ allow    ~ allow         ✔ allow  ✔ allow
    create  ✔ deny     ✔ allow         ✔ allow  ✔ allow
    update  ✔ deny     ✔ deny          ✔ allow  ✔ allow
    delete  ✔ deny     ✔ deny          ✔ allow  ✔ allow

  user /users
    action  Anonymous  Signed-in user  Owner    Admin
    list    ✔ deny     ✔ deny          ✔ deny   ✔ allow
    read    ✔ deny     ✔ deny          ✔ allow  ✔ allow
    create  ✔ deny     ✔ deny          ✔ deny   ✔ allow
    update  ✔ deny     ✔ deny          ✔ allow  ✔ allow
    delete  ✔ deny     ✔ deny          ✔ deny   ✔ allow

  Probes
  ✔ mass assignment: post.slug rejected with 422
  ✔ mass assignment: post.author rejected with 422
  ✔ mass assignment: post.publishedAt rejected with 422
  ✔ operator injection: post x[$ne]=1 -> 400
  ✔ limit cap: post limit=100000 -> 400
  ✔ unknown filter: post definitelyNotAField=1 -> 400
  ✔ error hygiene: post bad id -> 404
  ✔ operator injection: user x[$ne]=1 -> 400
  ✔ limit cap: user limit=100000 -> 400
  ✔ unknown filter: user definitelyNotAField=1 -> 400
  ✔ error hygiene: user bad id -> 404
  ✔ forged session token -> 401
  ✔ token in query string ignored -> 401
  ✔ login does not reveal accounts 401 / 401

  All checks passed · 52 passed · 2 skipped (custom scope or policy) · 54 checks
```

Each table shows the expected answer from your policies, and a mark for what the API did:

| Cell | Meaning |
|---|---|
| `✔ allow`, `✔ deny`, `✔ own` | The API did what the policy says (`own`: an owner-only list) |
| `✖ allow (403)` | The policy allows it but the API refused, with the status it returned |
| `✖ deny (200)` | The policy denies it but the API allowed it |
| `✖ own (200)` | An owner-only list returned records of other users |
| `~ allow` | Skipped: a `404` from a resource with its own `scope()` |
| `? custom` | A policy function decides, so the cell is not checked |
| `off` | The route is turned off with the resource's `crud` option |

The `post` reads are skipped because `post.service.js` hides drafts from everyone but their author and admins.

### When a check fails

Here notes are private to their author:

```js
// app/resources/note/note.resource.js
import { resource, f } from '#calm';

export default resource('note', {
  fields: { text: f.string().required(), author: f.ref('user').owner() },
  policy: { list: 'owner', read: 'owner', create: 'authenticated', update: 'owner', delete: 'owner' },
});
```

But the service overrides `list()` and forgets the owner scope:

```js
// app/resources/note/note.service.js (a bug)
import { ResourceService } from '#calm';

export default class NoteService extends ResourceService {
  async list() {
    const items = await this.model.find({}).lean();
    return { items, total: items.length };
  }
}
```

The audit reports it under the resource, with one line per failed cell:

```text
  note /notes
    action  Anonymous  Signed-in user  Owner        Admin
    list    ✔ deny     ✖ own (200)     ✖ own (200)  ✖ own (200)
    read    ✔ deny     ✔ deny          ✔ allow      ✔ deny
    create  ✔ deny     ✔ allow         ✔ allow      ✔ allow
    update  ✔ deny     ✔ deny          ✔ allow      ✔ deny
    delete  ✔ deny     ✔ deny          ✔ allow      ✔ deny
    ✖ list as Signed-in user: returned 2 record(s) owned by someone else
    ✖ list as Owner: returned 1 record(s) owned by someone else
    ✖ list as Admin: returned 5 record(s) owned by someone else
```

For the whole project (the `api` template plus `note`), the summary line reads `3 failed · 74 passed · 2 skipped (custom scope or policy) · 79 checks`. Field leaks are listed under **Field leaks**, one line each (for example `✖ customer.phone returned to anonymous (read /customers)`), and failed probes get a `✖` under **Probes**.

The fix is to keep the request context, so owner scoping still applies: call `super.list(query, ctx)`, or build the filter with `this.filterFor(ctx, filter)` (see [Services and hooks](/services)).

## Options

```text
calm audit [--json] [--ci]
```

| Option | Meaning |
|---|---|
| `--ci` | Exit with code 1 when a check fails |
| `--json` | The report as JSON: `ok`, `summary` (`checks`, `passed`, `failed`, `skipped`, `leaks`), `results`, `leaks`, `probes`, `notes` |

Each entry in `results` looks like this:

```json
{ "resource": "note", "action": "list", "persona": "owner", "expected": "own", "status": 200, "ok": false, "note": "returned 1 record(s) owned by someone else" }
```

`ok` is `true`, `false`, or `null` for a skipped cell.

## In CI and devtools

The audit needs a MongoDB server, like `npm test`. Add it to the pipeline next to your tests (see [Testing](/testing#in-ci)):

```bash
MONGODB_TEST_URI=mongodb://127.0.0.1:27017 npx calm audit --ci
```

The same audit runs from the devtools **Security** panel (**Run audit**, on a throwaway database on your dev server's MongoDB), and coding agents can run it with the `calm_audit` [MCP tool](/ai-agents#calm-mcp-tools-for-coding-agents). Run it after changing policies, fields or services.

---

Source: https://docs.calmapi.dev/cli

# CLI reference

The `calmapi` package installs a `calm` command (also available as `calmapi`). It is a dev dependency of every project, so use it with `npx calm <command>` or through the npm scripts. It has no dependencies of its own.

```text
calm create [dir]                       new project (npm create calmapi@latest)
calm dev                                watch mode + devtools
calm make resource <name> [fields...]   scaffold a resource
calm make block <name>                  start your own block
calm add <block...>                     copy blocks into your project (calm add --list, gh:user/repo/name)
calm block list|check|pack              your blocks: what changed, a safety review, a file to share
calm seed [resource...]                 sample records that look real
calm routes                             every route with its policy and source file
calm openapi                            write openapi.json
calm doctor [--prod] [--audit] [--ci]   security and correctness checks
calm audit [--ci]                       test every route as every role on a throwaway database
calm admin <email> [--revoke]           grant (or remove) the admin role
calm keygen [--write]                   encryption key for .encrypted() fields (rotates)
calm upgrade                            merge framework updates into calm/
calm mcp                                MCP server for coding agents
```

`calm <command> --help` prints the options of a command, `calm --version` the version. Aliases: `new` and `init` for `create`; `generate`, `g` and `m` for `make`; `blocks` for `block`. Running `calmapi` with no arguments outside a project starts the `create` wizard. Commands other than `create` must run inside a project (a folder with `calm.lock`, or below one). Set `CALM_DEBUG=1` to see stack traces.

## calm create

```text
calm create [directory]     also: npm create calmapi@latest [directory]
```

| Option | Meaning |
|---|---|
| `--template <api\|minimal>` | `api`: users, auth and an example resource (default). `minimal`: an empty `app/` to start from scratch |
| `--db <uri>` | MongoDB connection string (default: local server) |
| `--pm <npm\|pnpm\|yarn\|bun>` | Package manager to install with |
| `--no-install` | Skip installing dependencies |
| `--no-git` | Skip `git init` |
| `-y`, `--yes` | Accept every default, no prompts |

With `npm create`, put the options after `--`: `npm create calmapi@latest my-api -- --template minimal --yes`. The target folder must be empty or not exist.

## calm dev

```text
calm dev
```

Starts the app in development mode: `NODE_ENV=development`, file watching (`node --watch` on `app/`, `calm/`, `calm.config.js`, `server.js` and `.env`, so new resource folders restart the server too) and devtools at `http://localhost:<port>/_calm`. Extra arguments are passed to `node`, for example `calm dev --inspect`.

It also records every file change (with a line diff, marked as made by an AI agent or by you), restart and crash in `.calm/activity.jsonl`. The contents of `.env` are never recorded. Devtools shows this log live in the **Activity** panel; see [Watching an agent work](/ai-agents#watching-an-agent-work).

## calm make resource

```text
calm make resource <name> [fields...]
```

Creates `app/resources/<name>/<name>.resource.js` and, when the project has users, `test/<names>.test.js`.

| Option | Meaning |
|---|---|
| `--service` | Also create `<name>.service.js` |
| `--routes` | Also create `<name>.routes.js` (with an example `GET /stats`) |
| `--no-owner` | Do not add an owner field (by default `owner: f.ref('user').owner()` is added when the project has users) |
| `--no-test` | Do not create the test file |
| `--force` | Overwrite existing files |

Field syntax: `name:type[!][=default][+modifier...]`

| Spec | Generated |
|---|---|
| `title:string!` | `f.string().required()` |
| `price:number=0` | `f.number().default(0).sortable().filterable()` |
| `status:enum:draft,live=draft` | `f.enum(['draft', 'live']).default('draft').filterable()` |
| `category:ref:category` | `f.ref('category').filterable()` |
| `author:ref` | `f.ref('author').filterable()` (the field name is the resource) |
| `tags:string[]` | `f.array(f.string()).default([])` |
| `name:string!+searchable+sortable` | `f.string().required().searchable().sortable()` |
| `publishedAt:date=now` | `f.date().default(() => new Date()).sortable().filterable()` |

Types: `string text email url password number integer boolean date enum ref id json` (also `str`, `num`, `float`, `int`, `bool`, `datetime`, `object`). Modifiers: `searchable sortable filterable unique index hidden writeOnly readOnly immutable populate owner`. Enums, booleans and refs are made filterable, numbers and dates filterable and sortable.

A field spec `owner:ref:user` becomes the owner field (`f.ref('user').filterable().owner()`), and no second owner field is added.

```bash
npx calm make resource invoice number:string!+unique amount:number! status:enum:draft,sent,paid=draft customer:ref:user notes:text --service
```

Without a `user` resource (the `minimal` template), the generated policies are `public` with a comment reminding you to add auth before deploying anything writable.

## calm make block

```text
calm make block <name>
```

Starts your own block: `app/blocks/<name>/index.js` (a working route, with every extension point listed in comments), `block.json` (what sharing it needs), `README.md`, and `test/blocks/<name>.test.js`. The block is live in your app right away. The name is turned into kebab case and must start with a letter.

| Option | Meaning |
|---|---|
| `--no-test` | Do not create the test file |
| `--force` | Overwrite existing files |

See [Building your own block](/building-blocks).

## calm add

```text
calm add <block...>
```

Copies a block's files into your project, adds its dependencies to `package.json`, appends its environment variables to `.env.example` and `.env`, installs, and records it in `calm.lock`. The code is yours from then on. See [Blocks](/blocks).

```bash
npx calm add jobs api-docs                # official blocks (same as @calmapi/jobs)
npx calm add @acme/billing                # a registry from package.json "calm.registries"
npx calm add gh:acme/blocks/billing       # r/billing.json in a GitHub repository (@ref to pin)
npx calm add https://x.dev/r/y.json       # any URL
npx calm add ./blocks/my-block.json       # a local file
npx calm add --list                       # list official blocks
```

| Option | Meaning |
|---|---|
| `--dry-run` | Show what would change, write nothing |
| `--overwrite` | Replace files that already exist with different content |
| `--no-install` | Do not run the package manager |
| `--remote` | Fetch official blocks from `https://docs.calmapi.dev/r` instead of the copy bundled with the CLI |
| `-y`, `--yes` | Do not ask for confirmation |
| `--trust` | With `--yes`: also add third-party blocks whose review found risky code |
| `--list` | List official blocks |

Existing files with different content are kept and reported as conflicts unless you pass `--overwrite`. Blocks that provide the same resource (`storage-local` and `storage-s3`) refuse to be installed together. A block whose `minVersion` is newer than the CalmAPI version in `calm.lock` is refused until you run `calm upgrade`.

Blocks that are not official are reviewed before anything is written: the plan lists what their code does, in plain language (network requests, file writes, child processes, `eval`, computed imports, native or minified code, request hooks, the environment variables it reads and the hosts it mentions). Risky findings are marked `!` and must be confirmed; with `--yes`, they need `--trust` too. `--dry-run` shows the review without writing anything. See [What people see before installing](/building-blocks#what-people-see-before-installing).

## calm block

```text
calm block list
calm block check [name|address]
calm block pack [name...] [--out r]
```

Tools for the blocks in your project and the ones you share. See [Building your own block](/building-blocks#share-it).

| Command | Does |
|---|---|
| `list` (or `ls`) | Every block in the project: version, where it came from (from `calm.lock`, or "written here"), and the files you changed since adding it |
| `check` | Checks your blocks before you share them, or someone else's before you add it: name, versions, file targets (never `calm/`, `.env` or `package.json`), dependency ranges, env var declarations, committed secrets, imports of `calm/` internals, and the plain-language review of what the code does. Without a name it checks every block with a `block.json`. With an address (`gh:...`, a URL, `@scope/name` or a `.json` file) it fetches the block first. Exits with code 1 on errors. |
| `pack` | Writes a registry item for each block to `r/<name>.json` and an `r/index.json`. Without names, every block with a `block.json`. Blocks with errors are not packed. `--out <dir>` writes elsewhere. |

```text
$ npx calm block pack
✔ Packed slack-notify into r/

  Share it
  Commit r/ and push to GitHub, then anyone can run:
    npx calm add gh:<you>/<repo>/slack-notify
  Or host r/ anywhere: npx calm add https://<host>/r/<name>.json
```

## calm seed

```text
calm seed [resource...] [--count 10] [--users 3] [--seed 42]
```

Fills the database (`MONGODB_URI` from `.env`) with sample records that look real, built from your field definitions: names, emails, prices, ratings, phone numbers, cities, values from enums, dates in the past or the future depending on the field name, unique values kept unique, references to records that exist, and owners. Records are validated like API input and created through your services, so hooks run. Resources that the seeded ones reference get a few records first (up to 5), when they are empty.

```bash
npx calm seed                      # every resource, 10 records each
npx calm seed product --count 50   # one resource
npx calm seed --seed 42            # the same choices on every run
```

| Option | Meaning |
|---|---|
| `--count <n>` | Records per resource (default 10, at most 10,000) |
| `--users <n>` | Demo users to create when there are none yet (default 3) |
| `--seed <n>` | A fixed random seed, so names, numbers and choices repeat. Emails and unique values still differ between runs, so they never collide. |

When the database has no users, demo users are created to own the records, and their emails and password are printed so you can sign in as them:

```text
✔ Seeded 3 user, 10 product

  Demo users (sign in with these)
  demo.grace.mgnx8k2a0@example.test  calm-demo-password-1
  demo.alan.mgnx8k2b1@example.test  calm-demo-password-1
  demo.radia.mgnx8k2b2@example.test  calm-demo-password-1
```

It refuses to run with `NODE_ENV=production`. In devtools, **Sample data** in the Data panel does the same for one resource.

## calm routes

```text
calm routes [--json]
```

Every route the app serves with its method, path, policy and the file it comes from. Defaulted policies are marked `(default)`. `--json` prints machine readable output.

## calm openapi

```text
calm openapi [--out openapi.json] [--stdout]
```

Writes the OpenAPI 3.1 document generated from your resources and routes (default `openapi.json`), or prints it with `--stdout`. The running app also serves it at `/api/openapi.json`.

## calm doctor

```text
calm doctor [--prod] [--audit] [--ci] [--strict] [--json]
```

Security and correctness checks: config, policies, private fields, personal data exposure, hardcoded secrets, `.env` in git, risky code patterns, framework drift and published advisories. Also works inside CalmAPI 1.x projects (`npx calmapi@next doctor`), where it reports the advisories published for 1.x. See [Security](/security#what-calm-doctor-checks) for every check.

| Option | Meaning |
|---|---|
| `--prod` | Evaluate with production rules (`NODE_ENV=production`) |
| `--audit` | Also run `npm audit` on production dependencies |
| `--ci` | Exit with code 1 when there are errors |
| `--strict` | With `--ci`: also fail on warnings |
| `--json` | Machine readable output: `{ findings, errors, warnings }` |

```text
  CalmAPI doctor · my-api · production rules

  ! warn   No mail transport in production
           Password reset emails cannot be delivered. Run `calm add @calmapi/mail-resend` or register a transport.
  • info   TRUST_PROXY is not set
           Behind a load balancer every client shares one IP for rate limiting. Set TRUST_PROXY (e.g. 1).

  0 errors · 1 warning · 1 info
```

Doctor boots your app in a child process to inspect it, without connecting to MongoDB.

## calm audit

```text
calm audit [--json] [--ci]
```

Authorization testing for your API. Boots the app on a throwaway database (`MONGODB_TEST_URI`, default `mongodb://127.0.0.1:27017`), creates a user per persona (anonymous, owner, another user, admin, custom roles), seeds records and calls every CRUD route as every persona. It checks status codes against your policies, owner-only lists, field leaks, mass assignment, query injection, the page size cap, error hygiene and token handling. Your real database is never touched. See [Security audit](/audit).

| Option | Meaning |
|---|---|
| `--ci` | Exit with code 1 when a check fails |
| `--json` | Machine readable report |

```text
  note /notes
    action  Anonymous  Signed-in user  Owner        Admin
    list    ✔ deny     ✖ own (200)     ✖ own (200)  ✖ own (200)
    read    ✔ deny     ✔ deny          ✔ allow      ✔ deny
    create  ✔ deny     ✔ allow         ✔ allow      ✔ allow
    update  ✔ deny     ✔ deny          ✔ allow      ✔ deny
    delete  ✔ deny     ✔ deny          ✔ allow      ✔ deny
    ✖ list as Signed-in user: returned 2 record(s) owned by someone else
    ✖ list as Owner: returned 1 record(s) owned by someone else
    ✖ list as Admin: returned 5 record(s) owned by someone else
```

That is one resource of a failing run: its service ignores the owner scope on `list`.

## calm admin

```text
calm admin <email> [--revoke]
```

Gives an existing user the `admin` role, or removes it with `--revoke`. It connects to `MONGODB_URI` from `.env`, and the change applies to the user's next request. To make your first admin, sign up through `POST /api/auth/register`, then:

```bash
npx calm admin ada@example.com
```

```text
✔ Ada Lovelace <ada@example.com> roles: user, admin
```

## calm keygen

```text
calm keygen [--write]
```

Generates a 32-byte key for [`.encrypted()` fields](/security#encryption-at-rest) and prints it as a `CALM_ENCRYPTION_KEYS=k1:<key>` line. With `--write`, it adds the line to `.env`. If `CALM_ENCRYPTION_KEYS` already exists, the new key goes first (it encrypts from now on) and the old keys stay (they still decrypt existing data): that is key rotation.

```text
$ npx calm keygen --write
✔ Added CALM_ENCRYPTION_KEYS to .env (key k1).

$ npx calm keygen --write
✔ Rotated: k2 encrypts new data; k1 still decrypts existing data.
```

Put the same keys in your production secrets. Never commit them.

## calm upgrade

```text
calm upgrade [--dry-run] [--base <dir>] [-y]
```

Brings framework fixes into `calm/` without losing your edits. See [Upgrading](/upgrading).

| Option | Meaning |
|---|---|
| `--dry-run` | Show the plan, write nothing |
| `--base <dir>` | Use this calmapi checkout as the original files instead of downloading the version in `calm.lock` |
| `-y`, `--yes` | Do not ask for confirmation |

## calm mcp

```text
calm mcp
```

Starts a Model Context Protocol server on stdio for AI coding agents. Register it once:

```bash
claude mcp add calm -- npx calm mcp
```

or add `{ "command": "npx", "args": ["calm", "mcp"] }` to your agent's MCP configuration. It offers 18 tools: inspect the project, scaffold, call the dev API as any user (`calm_http`), run tests, doctor and the audit, and read requests, logs, emails, security events and project activity. Every tool call is logged to `.calm/activity.jsonl` with the client's name, so you can follow it in devtools. See [AI agents](/ai-agents) for the list.

---

Source: https://docs.calmapi.dev/ai-agents

# AI agents

CalmAPI is designed to be worked on by coding agents as well as people: conventions are written down in the project, the CLI is scriptable, and an MCP server lets agents inspect and drive the project. While an agent works, `calm dev` records what it changes, so you can watch it in devtools. Separately, the [mcp-server block](/blocks/mcp-server) lets agents *use* your API.

## AGENTS.md

Every new project has an `AGENTS.md` at its root, the file Claude Code, Codex, Cursor, Copilot and other agents look for. It describes the layout, the import conventions (`#calm`, `#app/...`) and the golden rules:

1. Add resources with the CLI (`npx calm make resource ...`), then edit them.
2. Declare fields once with `f.*()`; visibility and validation come from there.
3. Every route needs a policy.
4. Handlers return values; throw `notFound()`, `forbidden()`... instead of calling `res.json`.
5. Business logic goes in the service, with hooks before whole-method overrides, and queries scoped with `this.filterFor(ctx, filter)`.
6. Never return raw documents from non-resource routes; use `ctx.serialize(doc, 'resource')`.
7. Sensitive data: `.visibleTo('owner | admin')` for personal fields, `.encrypted()` for secrets at rest. Never log secrets.
8. Before finishing: `npm test`, `npx calm doctor` (fix every `error`) and, after changing policies or fields, `npx calm audit`.

`CLAUDE.md` contains one line pointing Claude Code to `AGENTS.md`. Edit `AGENTS.md` with your own project's rules; it is yours.

For GitHub Copilot, the same guidance is available as [copilot-instructions.md](/copilot-instructions.md): save it as `.github/copilot-instructions.md` in your project.

## calm mcp: tools for coding agents

`calm mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. Register it once per project with Claude Code:

```bash
claude mcp add calm -- npx calm mcp
```

For other agents, add it to their MCP configuration:

```json
{
  "mcpServers": {
    "calm": { "command": "npx", "args": ["calm", "mcp"] }
  }
}
```

It must run inside the project (the agent's working directory). Static tools run the CLI in a child process, so they always see the current code; runtime tools talk to the dev server, so start `npm run dev` for those.

It offers 18 tools.

**Understand the project**

| Tool | What it does |
|---|---|
| `calm_project` | Overview: app name, framework version, resources with paths and policies, installed blocks, whether the dev server is running. Agents should call it first. |
| `calm_routes` | Every route with method, path, policy and source file |
| `calm_resource` | One resource: the source of its resource, service and routes files, and its routes |
| `calm_openapi` | The OpenAPI 3.1 document |
| `calm_blocks` | List the official blocks |

**Change it**

| Tool | What it does |
|---|---|
| `calm_make_resource` | Scaffold a resource from field specs (`title:string!+searchable`, `status:enum:draft,live=draft`...), optionally with a service and routes file |
| `calm_add_block` | Add blocks (with a dry run option) |

**Try it** (dev server)

| Tool | What it does |
|---|---|
| `calm_http` | Call the dev API like a real client and get the status and body. `as` picks the caller: `anonymous` (default), `admin` (an admin user) or a user's email. The request is tagged as the agent's in devtools. |
| `calm_recent_requests` | Recent requests on the dev server (filter by errors or path) |
| `calm_request` | One request in full: headers, bodies, every MongoDB query with timing, logs, the error with stack trace |
| `calm_logs` | Recent log lines, optionally by level |
| `calm_mails` | Emails the dev server would have sent, such as password reset links |
| `calm_pushes` | [Push notifications](/push-notifications) the dev server sent: message, devices, status, warnings, delivery log and payload sizes |
| `calm_activity` | Recent project activity: file changes with diffs and who made them, restarts and crashes with their error output |

**Check it**

| Tool | What it does |
|---|---|
| `calm_test` | Run the project tests and get pass and fail counts, with each failing test and its error |
| `calm_doctor` | Run the security and correctness checks (optionally with production rules) |
| `calm_audit` | Run [`calm audit`](/audit) and get the failed checks, field leaks and failed probes |
| `calm_security` | The [exposure matrix](/security#exposure-matrix), the security related doctor findings, and recent [security events](/security#security-events) from the dev server |

A typical loop: the agent edits a resource, calls `calm_activity` to see whether the dev server restarted or crashed, tries the endpoint with `calm_http` as different users, reads `calm_request` for the queries and errors it caused, then runs `calm_test`, `calm_doctor` and `calm_audit`. Nobody has to copy logs into the chat.

`calm_http` signs in as other users through the devtools "act as" endpoint, so `admin` and email callers need the dev server and existing users. Make your first admin with `npx calm admin <email>`.

## Watching an agent work

`calm dev` writes what happens in the project to `.calm/activity.jsonl`, and `calm mcp` adds every tool call to the same file. The devtools **Activity** panel streams it live, so you can follow an agent from your browser while it works.

| `type` | Written by | Records |
|---|---|---|
| `session` | `calm dev` | The dev server started |
| `file` | `calm dev` | A file in `app/`, `calm/`, `calm.config.js`, `server.js` or `.env` was added, modified or deleted, with a line diff and who changed it |
| `restart`, `ready` | `calm dev` | The server restarted after a change, and came back up |
| `crash` | `calm dev` | The server crashed or failed to start, with the last lines of its error output |
| `agent` | `calm mcp` | A tool call: client name, tool, arguments, success, duration and a short summary |

A file change looks like this (one JSON object per line, shown here formatted):

```json
{
  "time": "2026-10-11T09:33:19.507Z",
  "type": "file",
  "path": "app/resources/post/post.resource.js",
  "change": "modified",
  "actor": { "kind": "agent", "name": "claude-code" },
  "diff": {
    "added": 1,
    "removed": 1,
    "hunks": [
      {
        "oldStart": 3,
        "newStart": 3,
        "lines": [
          " export default resource('post', {",
          "   fields: {",
          "-    title: f.string().required().max(200).searchable().sortable(),",
          "+    title: f.string().required().max(180).searchable().sortable(),",
          "     slug: f.string().readOnly().unique().filterable(),",
          "     body: f.text().required().max(50_000),"
        ]
      }
    ],
    "truncated": false
  }
}
```

- **Who changed it.** A file system event does not say who saved the file. `calm dev` attributes a change to an agent when that agent made a tool call in the last 20 seconds, and to you otherwise. The agent's name is the client name it sent when connecting over MCP.
- **Secrets stay out.** Changes to `.env` are recorded without their contents or a diff. Diffs are kept for text files up to 256 KB.
- **Bounded.** The file is trimmed to its last 2,000 events when it grows past 4 MB. New projects list `.calm/` in `.gitignore`.

Agents read the same log back with `calm_activity`, which is how they find out that their last edit crashed the server.

Requests sent with `calm_http` carry an `X-Calm-Agent` header with the client name. Devtools marks them as agent requests, and the **Requests** panel can filter them. Your own scripts can send the header too.

## The mcp-server block: your API as tools

To let agents act on your **data** (list posts, create an order), add the [mcp-server](/blocks/mcp-server) block. It serves MCP over Streamable HTTP at `/mcp` and turns each resource into tools (`post_list`, `post_get`, `post_create`, `post_update`, `post_delete`). Every tool call is executed as a real request against your API with the caller's session token, so policies, validation, scoping, rate limits and field visibility are exactly those of the REST API.

```bash
npx calm add mcp-server
claude mcp add --transport http my-api http://localhost:5001/mcp --header "Authorization: Bearer <session token>"
```

## llms.txt

These docs are available in a form that is easy to give to a model: [https://docs.calmapi.dev/llms.txt](/llms.txt) lists every page with a short description and a link to its markdown source, and [https://docs.calmapi.dev/llms-full.txt](/llms-full.txt) contains all CalmAPI 2 pages in one file. The markdown of any page is at its URL plus `.md`, for example [https://docs.calmapi.dev/policies.md](/policies.md).

---

Source: https://docs.calmapi.dev/upgrading

# Upgrading

The framework lives in your project as `calm/`, and you are free to edit it. `calm upgrade` brings in fixes and features from new CalmAPI releases **without** overwriting your edits.

```bash
npm install -D calmapi@latest   # the new CLI carries the new framework files
npx calm upgrade --dry-run      # see the plan
npx calm upgrade                # apply it
npx calm doctor && npm test
```

## How it works

`calm.lock` records the CalmAPI version your `calm/` folder came from and the SHA-256 hash of every framework file as it was shipped:

```json
{
  "lockfileVersion": 1,
  "calmapi": "2.0.0-alpha.0",
  "template": "api",
  "core": {
    "calm/app.js": "sha256:585bd812...",
    "calm/errors.js": "sha256:3c0f9e21..."
  },
  "blocks": {}
}
```

For each file, `calm upgrade` compares three versions: **yours** (what is in `calm/` now), the **original** (the file as shipped in the version in `calm.lock`) and the **new** one (from the CLI you just installed). The hash tells it whether you changed the file.

| Your file | Upstream | Result | Shown as |
|---|---|---|---|
| unchanged | changed | replaced with the new version | `update` |
| edited | changed, no overlap | three-way merge: your edits plus the upstream change | `merge` |
| edited | changed, same lines | written with conflict markers for you to resolve | `conflict` |
| does not exist | new file | added | `add` |
| unchanged | removed | deleted | `delete` |
| edited | removed | kept | `kept` |
| deleted by you | still exists | left deleted | `skipped` |
| exists, not in `calm.lock` | exists | your file is kept, the new version is written next to it as `<file>.calm-new` | `conflict` |
| edited, original not available | changed | your file is kept, the new version is written as `<file>.calm-new` | `review` |
| edited | unchanged | your file stays as it is | |
| identical to the new version | | nothing to do | |

Then `calm.lock` is updated to the new version and hashes.

```text
  calm upgrade 2.0.0-alpha.0 → 2.0.0-alpha.1

  merge     calm/errors.js
  update    calm/logger.js
  conflict  calm/mail.js
  add       calm/testing.js

? Apply? [Y/n]
```

## Conflicts

A conflicting file contains both versions, like a git merge:

```js
<<<<<<< yours
// Outgoing email (ours).
=======
// Outgoing email.
>>>>>>> calmapi@2.0.0-alpha.1
```

Edit the file to keep what you want and remove the markers. A later `calm upgrade` leaves resolved files alone.

For `.calm-new` files, compare the two versions by hand (`git diff --no-index calm/mail.js calm/mail.js.calm-new`), merge what you need, and delete the `.calm-new` file.

## Where the original files come from

To merge, the upgrade needs the files as they were shipped in the version recorded in `calm.lock`. It downloads that version of the `calmapi` package once with `npm pack` and caches it in `~/.calm/cache`. Offline, or for an unpublished version, pass a checkout with `--base`:

```bash
npx calm upgrade --base ../calmapi/v2
```

Without the originals, edited files cannot be merged and get a `.calm-new` copy instead. The three-way merge uses `git merge-file`, so git must be installed.

## Tips

- Commit before upgrading, so the result is one reviewable diff.
- Prefer extending over editing: hooks in services, plugins in `app/blocks`, options in `calm.config.js`. The fewer edits in `calm/`, the fewer conflicts.
- `calm doctor` lists the framework files you changed locally and tells you when `calm/` is older than the installed CLI.
- `calm upgrade` only touches `calm/`. Your `app/` folder and files added by [blocks](/blocks) are never changed. Blocks are versioned in `calm.lock`; re-add one with `calm add <block> --dry-run` to see what changed upstream.

---

Source: https://docs.calmapi.dev/blocks

# Blocks

Blocks are production features you add with one command. Like [shadcn/ui](https://ui.shadcn.com) components, they are **copied into your project** as source code: you read them, own them and change them. There is no runtime package to keep up with.

```bash
npx calm add jobs
```

```text
  Blocks
  + @calmapi/jobs v1.0.0 · @calmapi (bundled)
    Background jobs and cron on MongoDB (no Redis): retries with backoff, schedules, event triggers, admin API and a devtools panel.

  Files
  create    app/blocks/jobs/cron.js
  create    app/blocks/jobs/index.js
  create    app/blocks/jobs/queue.js
  create    app/jobs/welcome-email.js

  Environment (.env.example and .env)
  + JOBS_WORKER=on
  + JOBS_CONCURRENCY=4

? Apply these changes? [Y/n]
```

`calm add` writes the files, adds npm dependencies to `package.json` and installs them, appends environment variables to `.env.example` and `.env` (without touching values you already have), records the block in `calm.lock`, and prints the block's notes. Restart (or let `npm run dev` restart) and the block is live: every folder in `app/blocks/` with an `index.js` is loaded at boot.

## Official blocks

| Block | What you get |
|---|---|
| **Users and access** | |
| [api-keys](/blocks/api-keys) | Personal and service API keys with scopes, hashed at rest, expiry and revoke |
| [magic-link](/blocks/magic-link) | Passwordless sign-in by email, bound to the browser that asked |
| [totp](/blocks/totp) | Two-factor authentication with authenticator apps, recovery codes and replay protection |
| [privacy](/blocks/privacy) | Users export their data and delete their account (delete, anonymize or keep per resource) |
| **Messaging** | |
| [notifications](/blocks/notifications) | `ctx.notify()`: in-app inbox, push and email in one call, with preferences and quiet hours |
| [push-expo](/blocks/push-expo) / [push-fcm](/blocks/push-fcm) | [Push notification](/push-notifications) delivery through Expo or Firebase Cloud Messaging, alone or together |
| [mail-resend](/blocks/mail-resend) / [mail-smtp](/blocks/mail-smtp) | Email delivery |
| [webhooks](/blocks/webhooks) | Outgoing webhooks for resource events: signed, retried, logged, SSRF safe |
| [realtime-sse](/blocks/realtime-sse) | Live resource events, filtered per subscriber by the same policies |
| **Data and files** | |
| [storage-local](/blocks/storage-local) | Uploads to disk with type and size allowlists, magic-byte checks and safe downloads |
| [storage-s3](/blocks/storage-s3) | Direct-to-S3 uploads with presigned URLs (AWS S3, Cloudflare R2, MinIO) |
| [audit-log](/blocks/audit-log) | Who changed what, with field diffs (private values never logged) |
| [soft-delete](/blocks/soft-delete) | `softDelete: true` per resource, with trash and restore |
| **Running in production** | |
| [jobs](/blocks/jobs) | MongoDB job queue and cron (no Redis): retries, schedules, event triggers, admin API |
| [feature-flags](/blocks/feature-flags) | Kill switches, gradual rollouts, targeting, variants and route gates |
| [idempotency](/blocks/idempotency) | The `Idempotency-Key` header: safe retries for payments and other writes |
| [rate-limit-mongo](/blocks/rate-limit-mongo) | Rate limits shared across instances |
| **APIs and agents** | |
| [api-docs](/blocks/api-docs) | Interactive API reference at `/docs` |
| [mcp-server](/blocks/mcp-server) | Your resources as MCP tools for AI agents, enforced by your API's rules |

```bash
npx calm add --list                 # official blocks
npx calm add jobs audit-log         # several at once
npx calm add jobs --dry-run         # show the plan, write nothing
npx calm block list                 # blocks in this project, and the files you changed
```

The devtools **Blocks** panel shows every installed block: where it came from, the files you changed since, what it hooks into, its environment variables (set or missing) and its routes.

## Where blocks come from

An address is resolved like this:

| Address | Source |
|---|---|
| `jobs` or `@calmapi/jobs` | The official registry. The CLI carries a copy of it, so this works offline. `--remote` fetches `https://docs.calmapi.dev/r/jobs.json` instead. |
| `gh:acme/blocks/billing` | `r/billing.json` in a GitHub repository, what `calm block pack` writes. Add `@v1.2.0` (or a branch or commit) to pin it. |
| `@acme/billing` | The `@acme` registry declared in your `package.json` |
| `https://example.com/r/thing.json` | Any URL |
| `./blocks/thing.json` | A local file |

Registries are declared in `package.json`:

```json
{
  "calm": {
    "registries": { "@acme": "https://acme.dev/r/{name}.json" }
  }
}
```

The official registry is served as JSON at [https://docs.calmapi.dev/r/index.json](/r/index.json), one file per block (for example [/r/jobs.json](/r/jobs.json)), in the [shadcn registry-item format](https://ui.shadcn.com/docs/registry). To write and share your own, see [Building your own block](/building-blocks) and [Publishing your own block](/publishing-blocks).

## Safety rules

- A block can only write inside your project, never to `calm/` or `calm.lock`.
- Existing files with different content are kept and reported as **conflicts**; pass `--overwrite` to replace them.
- Blocks that provide the same resource refuse to be installed together (`storage-local` and `storage-s3` both provide `file`).
- `registryDependencies` are installed first; dependencies already in `package.json` are left as they are.
- Blocks can declare the oldest CalmAPI they work with (`minVersion`); older projects are asked to run `calm upgrade` first.
- Blocks that are not official are reviewed before anything is written: `calm add` lists in plain language what their code does (network requests, file writes, child processes, `eval`, request hooks, the environment variables it reads, the hosts it mentions). Risky findings must be confirmed, and with `--yes` they also need `--trust`. A block runs in your app with full access, like any code you paste, so read it. See [What people see before installing](/building-blocks#what-people-see-before-installing).

## After adding a block

The block's code is now in your project, and it is yours. Change it, delete parts you do not need, or remove the block by deleting its folder (and its entry in `calm.lock`). Re-running `calm add <block>` later shows which files differ from the current upstream version. `calm upgrade` never touches block files.

---

Source: https://docs.calmapi.dev/blocks/api-docs

# API docs (api-docs)

An interactive API reference at `/docs`, rendered by [Scalar](https://scalar.com) from the OpenAPI document your app already generates. Every resource, custom route, field rule and policy shows up without annotations.

```bash
npx calm add api-docs
```

| Adds | |
|---|---|
| Files | `app/blocks/api-docs/index.js` |
| Environment | `API_DOCS=on` |
| Routes | `GET /docs` (HTML page), `GET /docs/init.js` |

Open `http://localhost:5001/docs`. The page loads `/api/openapi.json` and lets you browse and try every endpoint, with a session token as bearer authentication.

## When it is served

- In **development** and **test** mode: always.
- In **production**: only when the environment has `API_DOCS=on`.
- Never when `openapi.enabled` is `false` in the config.

`calm add` writes `API_DOCS=on` to `.env` and `.env.example`. If your production environment is built from `.env.example`, remove that line there (or set `API_DOCS=off`) unless you want a public reference in production.

## Notes

- The Scalar script is pinned to an exact version and loaded from jsDelivr (`@scalar/api-reference@1.72.1`). Change the `SCALAR` constant in the block to upgrade it, or self-host the file.
- The page has its own Content-Security-Policy, which allows that script and Scalar's fonts and nothing else.
- What the reference shows is what OpenAPI shows: hidden and write-only fields are not in output schemas, PUT aliases are not listed, and routes with `hidden: true` are left out. Each operation's description says who may call it (`Access: owner | admin`).

---

Source: https://docs.calmapi.dev/blocks/api-keys

# API keys (api-keys)

Let your users create API keys for scripts, CI jobs and integrations. A key is shown once, stored only as a SHA-256 hash, and sent like a session token (`Authorization: Bearer calm_ak_...`). Scopes narrow what each key can do (`posts:read`, `posts:write`, `read`, `*`), and your policies still apply on top, so a key never does more than its owner. Keys expire (90 days by default), record when and from where they were last used, can be revoked by their owner or an admin, and can never manage keys, passwords or sessions. No dependencies.

```bash
npx calm add api-keys
```

| Adds | |
|---|---|
| Files | `app/blocks/api-keys/index.js` (routes, authentication, scope guard, devtools panel, doctor checks), `keys.js` (key format and checksum), `scopes.js` (scope rules) |
| Environment | none |
| Collection | `calm_api_keys` |
| Routes | `/api/auth/api-keys` for users, `/api/admin/api-keys` for admins |

## Create a key

Keys are created from a signed-in session. An API key cannot create keys.

```bash
curl -X POST http://localhost:5001/api/auth/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "name": "GitHub Actions deploy", "scopes": ["posts:read", "posts:write"], "expiresInDays": 30 }'
```

```json
{
  "data": {
    "id": "6650c0ffee0000000000abcd",
    "name": "GitHub Actions deploy",
    "prefix": "calm_ak_7Kq2Zp",
    "scopes": ["posts:read", "posts:write"],
    "status": "active",
    "createdAt": "2026-10-12T09:30:00.000Z",
    "lastUsedAt": null,
    "lastUsedIp": null,
    "expiresAt": "2026-11-11T09:30:00.000Z",
    "key": "<the full key, shown once>",
    "note": "Copy this key now. It is not stored and will not be shown again."
  }
}
```

The response is sent with `Cache-Control: no-store`, so the key never sits in a cache.

| Field | Default | |
|---|---|---|
| `name` | required | What the key is for, up to 100 characters |
| `scopes` | `["read"]` | See [Scopes](#scopes). Unknown scopes answer `422` with the list of valid ones. |
| `expiresInDays` | `90` | 1 to 365. `null` (never expires) only when `allowNoExpiry` is on. |

A user can have 20 active keys (`409 API_KEY_LIMIT` beyond).

## Use a key

Send it exactly like a session token:

```bash
curl http://localhost:5001/api/posts -H "Authorization: Bearer $CALM_API_KEY"
```

```js
const res = await fetch('https://api.example.com/api/posts', {
  headers: { Authorization: `Bearer ${process.env.CALM_API_KEY}` },
});
```

`GET /api/auth/me` works with any key, so a script can check which account it acts as.

In your own routes, [`ctx.auth`](/routes#the-handler-context) says how the request signed in:

```js
r.get('/reports', { policy: 'authenticated' }, (ctx) => {
  ctx.auth; // { via: 'api-key', scopes: ['reports:read'], id: '<key id>' }
            // or { via: 'session', scopes: ['*'], id: '<session id>' }
});
```

## Scopes

| Scope | Allows |
|---|---|
| `*` | Everything the key's user can do |
| `read` | Every `GET` request (routes with their own scope excepted) |
| `posts:read` | `GET` requests to `/api/posts...` |
| `posts:write` | `POST`, `PUT`, `PATCH` and `DELETE` requests to `/api/posts...` (not reading) |
| `posts:*` | Both, plus any custom `posts:<name>` scope |
| `reports:export` | A custom scope a route asks for (see below) |

The name before the colon is the first segment of the URL after `/api`: `/api/posts/123/publish` needs `posts:write`, `/api/reports/monthly` needs `reports:read`. List every scope your app has, with a description, for a key creation form:

```bash
curl http://localhost:5001/api/auth/api-keys/scopes -H "Authorization: Bearer $SESSION_TOKEN"
```

Scopes only narrow access. Policies, service `scope()` filters and field rules run as usual after the scope check, so a key of a normal user still cannot list users, and a disabled user's keys stop working at once. A missing scope answers `403` with the scope it needs:

```json
{ "error": { "code": "FORBIDDEN", "message": "This API key does not have the \"posts:write\" scope" } }
```

### Custom route scopes

Give a sensitive route its own scope with the [`scope` route option](/routes#the-route-builder). Only `*`, that exact scope or `reports:*` can call it (`read` and `reports:write` cannot):

```js
// app/routes.js
r.post('/reports/export', { policy: 'admin', scope: 'reports:export' }, exportReports);
```

For routes you do not write yourself (a block's routes, CRUD routes), set it in `calm.config.js`:

```js
export default defineConfig({
  blocks: {
    'api-keys': {
      routeScopes: { 'POST /reports/export': 'reports:export' },
    },
  },
});
```

Write the path as the route is registered, without `/api` and with its `:params`. `calm doctor` warns when an entry matches no route.

### What keys can never do

Keys cannot call `/api/auth/*`, except `GET /api/auth/me`: no creating or revoking keys, no password changes, no sessions, no 2FA changes, no profile edits through `/auth/me`. A leaked key must not be able to lock its owner out or mint more keys. These need a signed-in session.

## List and revoke

```bash
# Your active and expired keys (never the keys themselves)
curl http://localhost:5001/api/auth/api-keys -H "Authorization: Bearer $SESSION_TOKEN"

# Revoke one
curl -X DELETE http://localhost:5001/api/auth/api-keys/6650c0ffee0000000000abcd -H "Authorization: Bearer $SESSION_TOKEN"
```

`lastUsedAt` and `lastUsedIp` are updated at most once a minute per key.

Admins see every key with its owner and can revoke any of them:

```bash
curl 'http://localhost:5001/api/admin/api-keys?status=active' -H "Authorization: Bearer $ADMIN_SESSION"
curl -X DELETE http://localhost:5001/api/admin/api-keys/6650c0ffee0000000000abcd -H "Authorization: Bearer $ADMIN_SESSION"
```

Filters: `status` (`active`, `expired`, `revoked`), `user` (a user id), `limit` (up to 200). Revoked and expired keys stay in the admin list for 30 days, then MongoDB deletes them.

A password reset (the account recovery flow) revokes every key of that user, in case an attacker created one. A normal password change does not.

## Service keys

For a server-to-server integration, create a dedicated user (for example `billing-sync@example.com` with only the roles it needs), then sign in as that user and create a key, or create it from a script:

```js
import { createApp } from '#calm';

const app = await createApp();
await app.start();
const bot = await app.model('user').findOne({ email: 'billing-sync@example.com' });
const { key } = await app.ext.apiKeys.create(bot, { name: 'Billing sync', scopes: ['invoices:write'], expiresInDays: 90 });
console.log(key); // store it in the other service's secret manager
await app.stop();
```

`app.ext.apiKeys` also has `revoke(id)`, `scopes()` and `model` (the Mongoose model).

With the [mcp-server](/blocks/mcp-server) block, an AI agent can use an API key instead of a session. Tool calls go through your API with the same header, so with a `posts:read` key the agent can call `post_list` and `post_get`, and `post_create` is refused.

## Settings

All optional, in `calm.config.js`:

```js
export default defineConfig({
  blocks: {
    'api-keys': {
      policy: 'authenticated',
      maxKeysPerUser: 20,
      defaultExpiryDays: 90,
    },
  },
});
```

| Option | Default | |
|---|---|---|
| `policy` | `'authenticated'` | Who may create keys, for example `'admin'` |
| `maxKeysPerUser` | `20` | Active keys per user |
| `defaultExpiryDays` | `90` | Lifetime when the request does not say |
| `maxLifetimeDays` | `365` | Longest lifetime a request may ask for |
| `allowNoExpiry` | `false` | Allow `{ "expiresInDays": null }` |
| `defaultScopes` | `['read']` | Scopes of a key created without scopes |
| `routeScopes` | `{}` | `{ 'POST /reports/export': 'reports:export' }` |
| `revokeOnPasswordReset` | `true` | A password reset revokes every key of the user |

## Security events and checks

| Event | When |
|---|---|
| `security.api_key_created` | A key was created (`userId`, `keyId`, `prefix`, `scopes`, `expiresAt`, `ip`) |
| `security.api_key_revoked` | A key was revoked (`by`, `reason`: `user`, `admin` or `script`) |
| `security.api_keys_revoked` | A password reset revoked a user's keys |
| `security.invalid_api_key` | A key was refused (`reason`: `checksum`, `unknown`, `revoked`, `expired`, `user_disabled`, `user_deleted`) |

Events never contain the key. They show up live in the devtools **Security** panel, and your own listeners can alert on them: `calm.on('security.invalid_api_key', ...)`.

The devtools **API keys** panel lists keys with their owner, prefix, scopes and last use. The devtools **Doctor** panel counts active keys and warns about keys with the `*` scope that never expire. (`calm doctor` in a terminal does not connect to the database, so there it only checks your settings: unknown `defaultScopes` and `routeScopes` that match no route.)

## Leaked keys

Every key starts with `calm_ak_` followed by 38 letters and digits; the last 6 are a CRC32 checksum, so a typo or a truncated copy is refused before any database lookup. Add this pattern to your secret scanner (GitHub custom patterns, GitGuardian, gitleaks):

```text
calm_ak_[0-9A-Za-z]{38}
```

When a key leaks, revoke it (`DELETE /api/auth/api-keys/:id`, or an admin with `DELETE /api/admin/api-keys/:id`). The stored `prefix` (the first 6 characters after `calm_ak_`) tells you which key it is.

## Testing

```js
test('a read-only key can list posts but not create them', async () => {
  const alice = await t.signup();
  const created = await t.post('/auth/api-keys', { name: 'CI', scopes: ['posts:read'] }, alice);
  const key = created.body.data.key;

  assert.equal((await t.get('/posts', key)).status, 200);
  assert.equal((await t.post('/posts', { title: 'Hi', body: '...' }, key)).status, 403);
  assert.equal((await t.post('/auth/api-keys', { name: 'More' }, key)).status, 403);
});
```

The test client takes a token string as `auth`, so a key works like a session there too.

---

Source: https://docs.calmapi.dev/blocks/audit-log

# Audit log (audit-log)

Records who created, updated or deleted what, and when, with a field-level diff. Hidden, write-only and password fields are never written to the log: only the fact that they changed.

```bash
npx calm add audit-log
```

| Adds | |
|---|---|
| Files | `app/blocks/audit-log/index.js` |
| Environment | `AUDIT_RETENTION_DAYS=365` |
| Collection | `calm_audit_log` (entries expire after the retention period) |
| Route | `GET /api/audit-log` (admin) |

Every resource write is recorded automatically, because the block listens to the `<resource>.created`, `.updated` and `.deleted` events that services emit. That includes writes from jobs and scripts that go through services.

## Reading the log

```bash
curl -g "http://localhost:5001/api/audit-log?resource=post&recordId=6acb46a57e4a738ebdd998b4" -H "Authorization: Bearer $ADMIN_TOKEN"
```

```json
{
  "data": [
    {
      "id": "6acb5b2f7e4a738ebdd998e1",
      "user": { "id": "6acb46a57e4a738ebdd998b1", "name": "Ada Lovelace" },
      "action": "updated",
      "resource": "post",
      "recordId": "6acb46a57e4a738ebdd998b4",
      "changes": {
        "title": { "from": "Hello CalmAPI", "to": "Hello again" },
        "internalNote": { "changed": true }
      },
      "requestId": "3e0c7a51-1d4b-4a9c-8f55-6f2d0b1c9e27",
      "ip": "127.0.0.1",
      "at": "2026-10-11T09:02:11.204Z"
    }
  ]
}
```

Filters: `resource`, `recordId`, `action` (`created`, `updated`, `deleted`), `user` (a user id) and `limit` (default 50, at most 200). Entries are newest first.

## Options

- Exclude a resource with `audit: false` in its options: `resource('session-note', { audit: false, fields: { ... } })`.
- Change the retention with `AUDIT_RETENTION_DAYS`. It is the TTL of an index, so once the index exists, changing the value also means updating that index in MongoDB (`collMod`).
- The model is available as `app.ext.audit` for your own queries or an export job.

---

Source: https://docs.calmapi.dev/blocks/feature-flags

# Feature flags (feature-flags)

Ship code dark and turn it on when you are ready: kill switches, gradual rollouts, per user and per role targeting, and weighted variants for experiments. Flags live in MongoDB, are evaluated in memory (`ctx.flags.enabled('new-checkout')` is synchronous) and give every user the same answer on every instance. Admins change them through an API, frontends read theirs from `GET /api/flags`, routes can be gated with `requireFlag()`, and devtools lists them.

```bash
npx calm add feature-flags
```

| Adds | |
|---|---|
| Files | `app/blocks/feature-flags/index.js`, `evaluate.js` (the rules), `gate.js` (`requireFlag`) |
| Environment | none |
| Routes | `GET /api/flags`, `GET` and `POST /api/admin/flags`, `GET`, `PATCH` and `DELETE /api/admin/flags/:key` |
| Collection | `calm_flags` |

## A flag

```json
{
  "key": "new-checkout",
  "description": "One page checkout",
  "enabled": true,
  "rollout": 20,
  "users": ["6650c0ffee0000000000abcd"],
  "roles": ["beta"],
  "variants": { "control": 50, "one-page": 50 },
  "clientVisible": true
}
```

A flag is on for a caller when:

1. `enabled` is `true`. It is the kill switch: `false` turns the flag off for everyone, targeting included.
2. And their user id is in `users`, or they have one of the `roles`, or they fall inside `rollout`.

`rollout` is a percentage. Each user gets a bucket from 0 to 99, a hash of the flag key and their id, and the flag is on when the bucket is below `rollout`. There is no randomness and nothing stored per user: the same user gets the same answer on every request and every instance. Raising the rollout from 20 to 50 keeps the first 20% and adds 30% more, so nobody flips back and forth. Each flag hashes differently, so the same 20% of users are not always first.

Visitors who are not signed in are off, unless `rollout` is 100 or `users` lists their anonymous id. If your frontend sends a stable random id in the `X-Anonymous-Id` header (letters, digits, `.`, `_`, `:` and `-`, up to 128 characters), visitors are bucketed by it like users. Signed-in users are always bucketed by their user id.

## In your code

`ctx.flags` is on every request context (handlers, and the hooks and services that receive `ctx`):

```js
r.post('/orders', { policy: 'authenticated' }, async (ctx) => {
  if (ctx.flags.enabled('new-checkout')) return ctx.services.order.checkoutV2(ctx.body, ctx);
  return ctx.services.order.checkout(ctx.body, ctx);
});

const layout = ctx.flags.variant('pricing-page'); // 'control' | 'one-page' | null
```

`variant()` is `null` when the flag is off for the caller, when it has no variants, or when the caller has no id (a visitor without `X-Anonymous-Id`). Variants are weighted (`{ "control": 50, "one-page": 50 }`, whole numbers) and hashed separately from the rollout, so a user keeps their variant when the rollout changes. Changing the weights moves some users to another variant.

Unknown flags are off. In development, the first check of a flag that does not exist logs a warning, which catches typos.

Outside requests (jobs, event listeners, scripts), use the same evaluation through `app.ext.flags`:

```js
const flags = app.ext.flags;
await flags.isEnabled('new-checkout', { user });      // a user record, or { userId, roles }
await flags.variant('pricing-page', { anonymousId });
const forUser = await flags.evaluate({ user });       // then forUser.enabled(...) synchronously
```

## Gating routes with requireFlag

```js
import { requireFlag } from '#app/blocks/feature-flags/index.js';

export default (r) => {
  r.post('/checkout/v2', { policy: [requireFlag('new-checkout'), 'authenticated'] }, checkoutV2);
  r.get('/labs', { policy: requireFlag('labs') }, labs);
};
```

While the flag is off for the caller, the route answers `404 Route not found`, as if it did not exist. When it is on, the rest of the policy decides as usual: `[requireFlag('new-checkout'), 'authenticated']` still needs a signed-in user, and `[requireFlag('notes'), 'owner']` still limits users to their own records. A policy made only of gates (`requireFlag('labs')`) lets in whoever the flag is on for, visitors included when it is on for them.

Gates work in resource policies too:

```js
const notes = requireFlag('notes');

export default resource('note', {
  fields: { text: f.string().required(), author: f.ref('user').owner() },
  policy: { list: [notes, 'owner'], read: [notes, 'owner'], create: [notes, 'authenticated'], update: [notes, 'owner'], delete: [notes, 'owner'] },
});
```

How it works: a policy list means "any of" in CalmAPI, so an ordinary policy function could only widen access. `requireFlag()` returns a policy function marked as a gate. The block's [guard](/building-blocks#guards) finds gates in the route's policy and answers `404` before the policy runs; inside the policy, a gate never grants access on its own. Routes show the gate as `flag:new-checkout` in `calm routes` and devtools. Gates are for route and resource action policies; in field rules (`visibleTo`, `writableBy`) they are always false.

## Declaring flags in code

Flags your code relies on can be declared in `calm.config.js`. They are created on start when they do not exist, and never touched again: once a flag exists, the admin API owns it, so a deploy never undoes an admin's change.

```js
export default defineConfig({
  blocks: {
    'feature-flags': {
      flags: {
        'new-checkout': { description: 'One page checkout', rollout: 0 },
        'pricing-page': { description: 'Pricing experiment', rollout: 100, variants: { control: 50, 'one-page': 50 }, clientVisible: true },
      },
    },
  },
});
```

Declared flags start with `enabled: true` and whatever you set: a flag declared with `rollout: 0` is live only for the users and roles you target. Invalid declarations stop the boot with a readable error. A declared flag deleted through the API comes back, with its declared values, on the next start.

## Admin API

Every route needs the `admin` role.

```http
GET    /api/admin/flags                 every flag
GET    /api/admin/flags/new-checkout
POST   /api/admin/flags                 { "key": "new-checkout", "rollout": 10 }        -> 201
PATCH  /api/admin/flags/new-checkout    { "rollout": 50, "roles": ["beta"] }
DELETE /api/admin/flags/new-checkout                                                   -> 204
```

`PATCH` changes only the fields you send, and `null` resets a field (`"variants": null` removes the variants). Keys cannot change, and a key that is taken answers `409`. Every change records `updatedBy` and emits `flag.changed`.

| Field | |
|---|---|
| `key` | Letters, digits, `.`, `-` and `_`, up to 100, starting with a letter or a digit |
| `description` | Up to 500 characters |
| `enabled` | The kill switch (default `true`) |
| `rollout` | 0 to 100 (default 0) |
| `users`, `roles` | User ids (or anonymous ids) and roles that always get the flag |
| `variants` | `{ name: weight }`, up to 20, whole weights |
| `clientVisible` | Include it in `GET /api/flags` (default `false`) |

## For frontends

`GET /api/flags` returns the flags marked `clientVisible`, already evaluated for the caller, and nothing about the others:

```json
{ "data": { "new-checkout": { "enabled": true, "variant": null }, "pricing-page": { "enabled": true, "variant": "one-page" } } }
```

Send the session token for signed-in users and `X-Anonymous-Id` for visitors. The response is marked `Cache-Control: private, no-store`. Flags without `clientVisible` stay on the server, so internal flag names and targeting never reach the browser.

## Settings and caching

```js
export default defineConfig({ blocks: { 'feature-flags': { cacheTtlMs: 2000 } } });
```

| Option | Default | |
|---|---|---|
| `cacheTtlMs` | `5000` | How long a process reuses the flags it read. `0` reads them on every request. |
| `flags` | `{}` | Flags created on start when missing (see [Declaring flags in code](#declaring-flags-in-code)) |

Each process reads all flags at most once per `cacheTtlMs` and evaluates from memory. Changes made through the admin API (or `app.ext.flags`) apply at once in the process that made them, and within `cacheTtlMs` in the others. After writing to `calm_flags` directly, call `app.ext.flags.invalidate()` or wait for the TTL. If MongoDB cannot be read, the last known flags keep being served, or every flag is off if they were never read.

## Events and devtools

`flag.changed` is emitted for every create, update and delete, through the API or from declared flags:

```js
calm.on('flag.changed', ({ key, action, flag, previous, user }) => {
  calm.log.info(`${user?.name ?? 'Deploy'} ${action} ${key}: rollout ${previous?.rollout ?? 0}% to ${flag?.rollout ?? 0}%`);
});
```

In development, open `/_calm` and pick **Feature flags** to see every flag with its rollout, targeting, variants and last change.

## Testing

Declare the flags a test needs through the config of the test app, or create them with `app.ext.flags`:

```js
const t = await createTestApp({
  root: join(import.meta.dirname, '..'),
  config: { blocks: { 'feature-flags': { cacheTtlMs: 0, flags: { labs: { rollout: 0, roles: ['beta'] } } } } },
});

test('labs is only there for beta users', async () => {
  const beta = await t.signup({ roles: ['user', 'beta'] });
  const other = await t.signup();
  assert.equal((await t.get('/labs', beta)).status, 200);
  assert.equal((await t.get('/labs', other)).status, 404);

  await t.app.ext.flags.update('labs', { rollout: 100 });
  assert.equal((await t.get('/labs', other)).status, 200);
});
```

---

Source: https://docs.calmapi.dev/blocks/idempotency

# Idempotency keys (idempotency)

A client creates an order, the network drops before the answer arrives, and the client cannot tell whether the order exists. Retrying blindly can charge twice. With this block, the client sends an `Idempotency-Key` header with each `POST`, `PATCH`, `PUT` or `DELETE`. If it sends the same request again with the same key, the API answers with the response it stored the first time instead of running the operation again. It follows the IETF draft [The Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/), the scheme Stripe and others use.

```bash
npx calm add idempotency
```

| Adds | |
|---|---|
| Files | `app/blocks/idempotency/index.js` |
| Environment | none (settings live in `calm.config.js` under `blocks.idempotency`) |
| Collection | `calm_idempotency` (keys and stored responses, removed by a TTL index) |

## Send a key

Generate one key per operation (a UUID is a good choice) and reuse it only for retries of that operation:

```bash
KEY=$(uuidgen)
curl -i -X POST http://localhost:5001/api/orders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: \"$KEY\"" \
  -d '{ "item": "book", "qty": 2 }'
# HTTP/1.1 201 Created
# { "data": { "id": "6acd...", "item": "book", "qty": 2 } }
```

The draft writes the key as a quoted string (`"8e03978e-..."`). The bare form (`8e03978e-...`) works too and is the same key. A key is 1 to 255 visible ASCII characters; anything else answers `400 IDEMPOTENCY_KEY_INVALID`.

```js
// In a client: one key per operation, the same key for its retries
const key = crypto.randomUUID();
const send = () => fetch('/api/orders', {
  method: 'POST',
  headers: { 'content-type': 'application/json', authorization: `Bearer ${token}`, 'idempotency-key': key },
  body: JSON.stringify(order),
});
```

## Retry safely

Send exactly the same request again (same method, path, body and key):

```bash
curl -i -X POST http://localhost:5001/api/orders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: \"$KEY\"" \
  -d '{ "item": "book", "qty": 2 }'
# HTTP/1.1 201 Created
# Idempotent-Replayed: true
# { "data": { "id": "6acd...", "item": "book", "qty": 2 } }   (the same order, not a new one)
```

The replay has the stored status, body and a safe set of headers (`Content-Type`, `Location`, `ETag`, `Last-Modified`, `Link`, `Cache-Control`, `Content-Disposition`, `Content-Language`, `Content-Location`), plus `Idempotent-Replayed: true`, which CORS exposes to browsers. Cookies, rate limit headers and the request id are never stored; each request keeps its own `X-Request-Id`.

| Situation | Answer |
|---|---|
| First time | The route runs normally and its response is stored |
| Same key, same request, first one finished | The stored response, with `Idempotent-Replayed: true` |
| Same key, same request, first one still running | `409 IDEMPOTENCY_IN_PROGRESS`, `Retry-After: 1` |
| Same key, different body or query string | `422 IDEMPOTENCY_KEY_REUSED` |
| First one answered `5xx` | Nothing was stored: the retry runs the route again |
| First one answered `4xx` | Stored and replayed: fix the request and use a new key |
| No key | The route runs normally (unless the route is in `required`) |

"Same request" means the same SHA-256 fingerprint of the JSON body (object keys sorted, so key order does not matter) and the query string. Multipart uploads are not part of the fingerprint, neither the files nor the form fields: the key is checked before the upload is parsed.

## Who can see a stored response

Keys are scoped to the caller: the signed-in user (any credential that resolves to that user, such as an [API key](/blocks/api-keys)), or the client IP for anonymous requests, plus the method and the path. Another user sending the same key gets their own fresh execution, never your response. The record id is a SHA-256 of the scope, method, path and key.

`GET`, `HEAD` and `OPTIONS` ignore the header: they are safe to retry already.

## Require a key on some routes

```js
// calm.config.js
export default defineConfig({
  blocks: {
    idempotency: {
      required: ['POST /api/orders', 'POST /api/payments/:id/capture'],
      docsUrl: 'https://example.com/docs/idempotency',
    },
  },
});
```

Patterns are a method (or `*`) and a path with the `/api` prefix. `:name` and `*` match one path segment, and a final `**` matches the rest. Without the header those routes answer:

```bash
curl -i -X POST http://localhost:5001/api/orders -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "item": "book" }'
# HTTP/1.1 400 Bad Request
# Link: <https://example.com/docs/idempotency>; rel="describedby"; type="text/html"
# { "error": { "code": "IDEMPOTENCY_KEY_MISSING", "message": "POST /api/orders needs an Idempotency-Key header: a unique value per operation, such as a UUID" } }
```

With `docsUrl` set, every idempotency error carries the `Link` header the draft recommends. `calm doctor` warns about patterns that match no route, and about patterns whose method the block ignores.

## Expiry

Keys and responses are kept for `ttlHours` (default 24) after the response, then MongoDB removes them. A retry after that runs the operation again, so tell your API clients that retries are safe for 24 hours. The draft asks servers to publish this.

A request that is still running holds its key for at most `lockTimeoutSeconds` (default 300). If the process crashed mid-request, a retry after that takes the key over and runs the operation.

## How it works

The block is a [guard](/building-blocks#guards) with `order: 100`, so it runs after authentication, body parsing and the other guards (such as API key scopes), and before the route's policy check. A request another guard refuses is never stored.

1. It claims the key by inserting a `{ status: 'running' }` document. The unique `_id` makes the insert the lock, so two instances cannot both run the same key.
2. The response is captured as it is written. Before it is released to the client, the document becomes `{ status: 'done', response }`, so a retry arriving right after the response always finds it.
3. A `5xx` deletes the document instead.

Responses over `maxResponseKb` (default 1024) are not stored: a replay gets the stored status and headers with an empty body, and the operation still does not run twice.

## Settings

| Option | Default | |
|---|---|---|
| `methods` | `['POST', 'PATCH', 'PUT', 'DELETE']` | Methods that honor the header |
| `required` | `[]` | Route patterns that must carry a key (`400` otherwise) |
| `ttlHours` | `24` | How long keys and responses are kept |
| `lockTimeoutSeconds` | `300` | After this, a running request's key is considered abandoned |
| `maxResponseKb` | `1024` | Larger response bodies are not stored |
| `docsUrl` | `null` | Documentation link sent with idempotency errors |

From code: `app.ext.idempotency.model` (the Mongoose model of `calm_idempotency`) and `app.ext.idempotency.parseKey(header)`.

The [privacy](/blocks/privacy) block removes a user's stored responses when their account is deleted.

## Testing

The test client does not send custom headers, so use `fetch` with `t.origin`:

```js
test('a retried order is created once', async () => {
  const alice = await t.signup();
  const send = () => fetch(`${t.origin}/api/orders`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', authorization: `Bearer ${alice.token}`, 'idempotency-key': 'order-1' },
    body: JSON.stringify({ item: 'book', qty: 2 }),
  });

  const first = await send();
  const second = await send();
  assert.equal(second.status, first.status);
  assert.equal(second.headers.get('idempotent-replayed'), 'true');
  assert.equal(await t.app.model('order').countDocuments(), 1);
});
```

---

Source: https://docs.calmapi.dev/blocks/jobs

# Background jobs (jobs)

A job queue and scheduler stored in MongoDB, so there is no Redis to run. Jobs retry with exponential backoff, run on a cron or interval schedule or when an event fires, and admins get an API and a devtools panel.

```bash
npx calm add jobs
```

| Adds | |
|---|---|
| Files | `app/blocks/jobs/index.js`, `queue.js`, `cron.js`; an example job in `app/jobs/welcome-email.js` |
| Environment | `JOBS_WORKER=on`, `JOBS_CONCURRENCY=4` |
| Collection | `calm_jobs` |
| Routes | `GET /api/jobs`, `GET /api/jobs/stats`, `POST /api/jobs/:jobId/retry`, `POST /api/jobs/enqueue` (all `admin`) |

## Define a job

Each file in `app/jobs/` default-exports a job:

```js
// app/jobs/welcome-email.js
import { defineJob } from '#app/blocks/jobs/index.js';

export default defineJob({
  name: 'welcome-email',
  on: 'auth.registered',   // run whenever this event fires, with its payload as data
  retries: 3,
  async run({ user }, { app }) {
    await app.mailer.send({
      to: user.email,
      subject: `Welcome to ${app.config.app.name}`,
      text: `Hi ${user.name},\n\nYour account is ready. Happy building!`,
    });
  },
});
```

| Option | Default | Meaning |
|---|---|---|
| `name` | required | Unique job name |
| `run(data, { app, job, log })` | required | The work. Throw to fail the attempt. The return value is stored as the job's `result`. |
| `retries` | `3` | Extra attempts after a failure |
| `backoff` | `'10s'` | Delay before the first retry, doubled on each attempt (capped at 1 hour) |
| `schedule` | none | Cron (`'0 9 * * 1-5'`, UTC) or interval (`'every 5m'`) |
| `on` | none | Event name or pattern that enqueues the job, for example `'order.created'` |

## Enqueue

From anywhere you have the app (routes, services, other jobs):

```js
const jobs = ctx.app.ext.jobs;

await jobs.enqueue('send-invoice', { invoiceId: invoice._id });
await jobs.enqueue('send-reminder', { userId }, { delay: '24h' });
await jobs.enqueue('nightly-report', {}, { runAt: new Date('2026-12-01T02:00:00Z') });
await jobs.enqueue('sync-customer', { id }, { uniqueKey: `sync:${id}` }); // one job per key
await jobs.enqueue('flaky-webhook', payload, { retries: 10 });
```

Durations accept `30s`, `5m`, `2h`, `1d` or milliseconds. With a `uniqueKey`, enqueuing again returns the existing job with that key (queued, running or finished) instead of creating a duplicate. Completed jobs keep their key until they are cleaned up.

## Schedules

```js
export default defineJob({
  name: 'cleanup-drafts',
  schedule: '0 3 * * *',  // every day at 03:00 UTC
  async run(_data, { app, log }) {
    const { deletedCount } = await app.model('post').deleteMany({
      status: 'draft',
      updatedAt: { $lt: new Date(Date.now() - 90 * 86_400_000) },
    });
    log.info(`Removed ${deletedCount} old drafts`);
    return { deletedCount };
  },
});
```

Cron expressions have five fields (minute, hour, day of month, month, day of week) with `*`, lists, ranges and steps (`*/15`, `1-5`), plus `@hourly`, `@daily`, `@weekly` and `@monthly`. Intervals are `every 30s`, `every 5m`, `every 2h`, `every 1d`. Each scheduled job exists once in the queue, however many instances you run, and a failed run is retried and then simply waits for its next time.

## Workers

Every instance with `JOBS_WORKER` not set to `off` runs a worker: it polls every second, claims due jobs atomically and runs up to `JOBS_CONCURRENCY` at a time. You can run as many instances as you like; a job is only ever claimed by one. Jobs whose worker died mid-run are put back in the queue after 5 minutes. On shutdown the worker stops claiming and waits up to 10 seconds for running jobs.

To keep web servers responsive, run dedicated workers: `JOBS_WORKER=off` on the web instances and `JOBS_WORKER=on` on one or more worker instances of the same app. `calm doctor` reminds you when the worker is off on an instance.

In tests the worker does not run. Process due jobs explicitly:

```js
await t.app.ext.jobs.drain();
```

Completed jobs are deleted after 7 days by a TTL index; failed jobs stay until you retry or remove them.

## Admin API

| Route | Does |
|---|---|
| `GET /api/jobs?status=failed&name=welcome-email&limit=50` | Recent jobs, newest first |
| `GET /api/jobs/stats` | Worker id, running count, job definitions and counts by name and status |
| `POST /api/jobs/:jobId/retry` | Queue a failed job again |
| `POST /api/jobs/enqueue` `{ name, data }` | Queue a job by name |

The devtools **Jobs** panel shows the same statistics and the latest jobs. The block emits `job.completed` and `job.failed` events.

---

Source: https://docs.calmapi.dev/blocks/magic-link

# Magic link sign-in (magic-link)

Passwordless sign-in by email. A user types their address, gets a link, opens it and is signed in, with the same session tokens as password sign-in. Links work once, expire after 15 minutes and are stored only as hashes. The request never reveals whether an account exists, each address has a cooldown, redirects are checked against an allowlist, and a link can be bound to the browser that asked for it. [Account lockout](/authentication#account-lockout), disabled accounts and two-factor authentication (the [totp](/blocks/totp) block) apply exactly as they do for passwords.

```bash
npx calm add magic-link
```

| Adds | |
|---|---|
| Files | `app/blocks/magic-link/index.js` |
| Environment | Nothing new. Links are built from `APP_URL`, which every project sets. |
| Routes | `POST /api/auth/magic-link`, `POST /api/auth/magic-link/verify` |
| Collections | `calm_magic_links`, `calm_magic_link_cooldowns` (both cleaned up by TTL indexes) |

Emails go through `app.mailer`, so in development they land in the devtools **Mail** panel. In production add [mail-resend](/blocks/mail-resend) or [mail-smtp](/blocks/mail-smtp).

## The flow

1. Your sign-in page asks for a link:

   ```bash
   curl -X POST http://localhost:5001/api/auth/magic-link -H 'Content-Type: application/json' \
     -d '{ "email": "ada@example.com", "redirect": "/billing" }'
   ```

   ```json
   { "data": { "message": "If that address can sign in, a link is on its way.", "requestId": "<random id>", "expiresIn": 900 } }
   ```

   The answer is `202` and the same for every address, registered or not. The account lookup and the email happen after the response, so the timing does not tell either. Keep `requestId` in `localStorage`.

2. The email links to `APP_URL/auth/magic?token=magic_...` (change the page with the `linkUrl` setting). That page reads the token and calls:

   ```bash
   curl -X POST http://localhost:5001/api/auth/magic-link/verify -H 'Content-Type: application/json' \
     -d '{ "token": "magic_...", "requestId": "<the stored requestId>" }'
   ```

   ```json
   { "data": { "user": { "id": "6650...", "name": "Ada Lovelace", "email": "ada@example.com" }, "token": "calm_...", "expiresAt": "...", "redirect": "http://localhost:5001/billing" } }
   ```

   Use `token` as a Bearer token, like the one from `/api/auth/login`, then send the user to `redirect` if there is one. Remove the stored `requestId` after a verify attempt.

3. When the user has two-factor authentication on, verify answers with the challenge instead of a session, exactly like password sign-in, and keeps `redirect` on it:

   ```json
   { "data": { "mfaRequired": true, "mfaToken": "mfa_...", "methods": ["totp", "recovery"], "expiresAt": "...", "redirect": "..." } }
   ```

   Finish with `POST /api/auth/2fa/verify { mfaToken, code }`.

A minimal page for step 2:

```js
const token = new URLSearchParams(location.search).get('token');
const requestId = localStorage.getItem('magicRequestId') ?? undefined;
const res = await fetch('/api/auth/magic-link/verify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token, requestId }),
});
localStorage.removeItem('magicRequestId');
const { data, error } = await res.json();
if (data?.mfaRequired) showTwoFactorForm(data.mfaToken);
else if (data?.token) signIn(data.token, data.redirect ?? '/');
else showError(error.code === 'OTHER_DEVICE' ? 'Open the link in the browser where you asked for it.' : 'This link is invalid or has expired.');
```

| Answer | When |
|---|---|
| `400 INVALID_TOKEN` | The link is unknown, already used or expired |
| `400 OTHER_DEVICE` | The `requestId` does not match the browser that asked (the link stays usable) |
| `403` | The account was disabled after the link was sent |
| `429` | The account is locked after too many wrong passwords (the link stays usable until it expires) |

## Settings

Set them in `calm.config.js`:

```js
export default defineConfig({
  blocks: {
    'magic-link': {
      createAccount: true,
      requireSameDevice: true,
      allowedRedirects: ['https://app.example.com', 'https://admin.example.com'],
    },
  },
});
```

| Option | Default | |
|---|---|---|
| `linkUrl` | `APP_URL + '/auth/magic'` | The frontend page the email links to. `?token=` (or `&token=`) is added. |
| `ttlMinutes` | `15` | How long a link works |
| `cooldownSeconds` | `60` | Minimum time between two links for the same address. `0` turns it off. |
| `createAccount` | `false` | Unknown addresses get a sign-up link that creates the account when it is opened. Only while `auth.register` is on. |
| `allowedRedirects` | the origin of `APP_URL` | Origins `redirect` may point to |
| `requireSameDevice` | `false` | Refuse links verified without the `requestId` of the browser that asked |

## Binding links to the browser

Every request returns a short `requestId`. Only its hash is stored with the link.

- Sent back on verify, it must match. A link opened in a browser holding a different `requestId` is refused with `400 OTHER_DEVICE`, and the link is not used up, so the right browser can still open it.
- Without `requestId`, the link works anywhere by default, so people can ask on a laptop and open the email on a phone.
- With `requireSameDevice: true` the `requestId` is required. This stops login CSRF (someone mailing you a link to *their* account so you end up signed in as them) and makes a leaked or forwarded link useless. The cost: the link must be opened in the browser that asked for it.

While a cooldown runs, the request answers `429` with `Retry-After` and no new `requestId`, so the browser keeps the one that matches the email already sent.

## Redirects

`redirect` is checked when the link is requested, never when it is used:

- Paths (`/billing?tab=2`) resolve against `APP_URL`.
- Absolute URLs must be `http` or `https`, and their origin must be in `allowedRedirects`.
- Anything else is a `422`: other origins, `//evil.example`, `/\evil.example`, `javascript:`, URLs with credentials such as `https://app.example.com@evil.example`.

The checked URL comes back from verify as `redirect`. It is never put in the email link, so nobody can change it on the way.

## Signing up with a link

With `createAccount: true`, an unknown address gets a "Finish signing up" email instead of nothing. The account is created when the link is verified, not before, so typing someone else's address creates nothing. Verify then also answers `created: true`. You can pass a `name` with the request:

```bash
curl -X POST http://localhost:5001/api/auth/magic-link -H 'Content-Type: application/json' \
  -d '{ "email": "new@example.com", "name": "Ada Lovelace" }'
```

The new account gets the email, the name (or the part of the address before `@`) and a random password nobody knows. The user keeps signing in with links, or sets a password with the reset flow. If your user resource has more required fields, add them in `newAccount()` in `app/blocks/magic-link/index.js`. `auth.registered` is emitted with `via: 'magic-link'`, so welcome emails and jobs listening to it still run.

## How it is protected

- Tokens are 256-bit random values, stored as SHA-256 hashes, single use (claimed with one atomic update) and short lived.
- Both routes use the auth rate limit (`config.rateLimit.auth`), and each address has a cooldown stored in MongoDB, so it holds across instances.
- Sign-in goes through the same [auth service helpers](/building-blocks#the-auth-service) as passwords: a locked account gets `429`, disabled accounts get no links, and login challenges (2FA) run before a session is created.
- Refused links emit `security.invalid_magic_link` with a `reason`: `unknown`, `used`, `expired`, `other_device` or `unknown_user`.
- Anyone who can request links for an address can make that address receive emails, within the rate limit and the cooldown. They cannot sign in: that needs the inbox.

## Events

| Event | Payload |
|---|---|
| `auth.magic_link_requested` | `{ user, email, signup }`, after the email is sent (`user` is `null` for sign-up links) |
| `auth.login` | `{ user }`, when a link signs someone in |
| `auth.registered` | `{ user, via: 'magic-link' }`, when a sign-up link creates an account |
| `security.invalid_magic_link` | `{ reason, ip, email? }` (masked email) |
| `security.locked_login_attempt` | `{ email, ip, via: 'magic-link' }` |

```js
calm.on('auth.magic_link_requested', ({ signup }) => metrics.increment('magic_link', { signup }));
```

## Testing

The email is captured in `t.mails`, and its `meta.token` holds the token:

```js
test('a magic link signs the user in once', async () => {
  const ada = await t.signup();
  const asked = await t.post('/auth/magic-link', { email: ada.email });
  assert.equal(asked.status, 202);
  await t.idle(); // the email is sent after the response

  const token = t.mails.at(-1).meta.token;
  const { requestId } = asked.body.data;
  const signedIn = await t.post('/auth/magic-link/verify', { token, requestId });
  assert.equal(signedIn.status, 200);
  assert.ok(signedIn.body.data.token);

  const again = await t.post('/auth/magic-link/verify', { token, requestId });
  assert.equal(again.body.error.code, 'INVALID_TOKEN');
});
```

---

Source: https://docs.calmapi.dev/blocks/mail-resend

# Email via Resend (mail-resend)

Delivers the emails your app sends (password resets, notifications) through the [Resend](https://resend.com) HTTP API. No SDK: one `fetch` call.

```bash
npx calm add mail-resend
```

| Adds | |
|---|---|
| Files | `app/blocks/mail-resend/index.js` |
| Environment | `RESEND_API_KEY=`, `MAIL_FROM=My App <no-reply@example.com>` |

Set `RESEND_API_KEY` and `MAIL_FROM`, a sender on a domain you verified in Resend. `MAIL_FROM` takes precedence over `mail.from` in `calm.config.js`.

In development without a key, the block stays inactive and emails keep going to the devtools **Mail** panel. In production without a key, `calm doctor` reports an error.

## Sending email

Everything goes through `app.mailer`, so your code does not depend on the provider:

```js
await ctx.app.mailer.send({
  to: 'ada@example.com',
  subject: 'Your invoice',
  text: 'Thanks for your order.',
  html: '<p>Thanks for your order.</p>',
});
```

`to` can be one address or an array. A failed delivery throws with Resend's status and message. For retries, send from a [job](/blocks/jobs).

## Without a mail block

The built-in transport only works in development: it prints a short notice and hands the message to devtools. In production with no transport, emails are not sent and an error is logged, and `calm doctor --prod` warns about it. You can also register your own transport in a plugin:

```js
calm.mailer.use({
  name: 'my-provider',
  async send({ to, from, subject, text, html }) { /* deliver it */ },
});
```

---

Source: https://docs.calmapi.dev/blocks/mail-smtp

# Email via SMTP (mail-smtp)

Delivers the emails your app sends through any SMTP server (Amazon SES, Postmark, Mailgun, your own) with [Nodemailer](https://nodemailer.com).

```bash
npx calm add mail-smtp
```

| Adds | |
|---|---|
| Files | `app/blocks/mail-smtp/index.js` |
| Dependency | `nodemailer` |
| Environment | `SMTP_URL=smtps://user:password@smtp.example.com:465`, `MAIL_FROM=My App <no-reply@example.com>` |

Set `SMTP_URL` to your server (`smtp://` or `smtps://`, credentials URL-encoded) and `MAIL_FROM` to the sender. `MAIL_FROM` takes precedence over `mail.from` in `calm.config.js`.

```ini
SMTP_URL=smtps://AKIA...:secret@email-smtp.eu-west-1.amazonaws.com:465
MAIL_FROM=My App <no-reply@example.com>
```

While `SMTP_URL` is empty or still the `smtp.example.com` placeholder, the block stays inactive: emails go to the devtools **Mail** panel in development, and `calm doctor` reports an error in production. The connection is closed on shutdown.

Send email with `app.mailer.send({ to, subject, text, html })`, exactly as with [mail-resend](/blocks/mail-resend).

---

Source: https://docs.calmapi.dev/blocks/mcp-server

# MCP server (mcp-server)

Expose your API to AI agents as [Model Context Protocol](https://modelcontextprotocol.io) tools, served over Streamable HTTP at `POST /mcp`. Tools are generated from your resources, and every tool call is executed as a real request against your own API with the caller's session, so policies, validation, scoping, rate limits and field visibility are exactly those of the REST API.

This block is for agents that *use* your API. For agents that *develop* your project, see [`calm mcp`](/ai-agents).

```bash
npx calm add mcp-server
```

| Adds | |
|---|---|
| Files | `app/blocks/mcp-server/index.js` |
| Environment | `MCP_RESOURCES` (empty: every resource except `user` and `file`) |
| Endpoint | `POST /mcp` (stateless Streamable HTTP, JSON responses) |

## Tools

For each exposed resource, one tool per CRUD action it has (actions with a `'none'` policy are left out):

| Tool | Calls | Arguments |
|---|---|---|
| `<name>_list` | `GET /api/<names>` | `q`, `filter` (e.g. `{ "status": "published", "price[gte]": "10" }`), `sort`, `page`, `limit`, `include` |
| `<name>_get` | `GET /api/<names>/:id` | `id`, `include` |
| `<name>_create` | `POST /api/<names>` | `data`, with the resource's create schema |
| `<name>_update` | `PATCH /api/<names>/:id` | `id`, `data` |
| `<name>_delete` | `DELETE /api/<names>/:id` | `id` |

Tool descriptions list the filterable fields, and the input schemas come from your fields, so agents know what they may send. The resource's `description` option is used in tool descriptions. A failed call (for example a `403`) returns the API's error body with `isError: true`.

Limit what is exposed with `MCP_RESOURCES=post,product`.

## Connect an agent

Agents authenticate with the same header as any API client: `Authorization: Bearer <session token>`. Without it, calls run as an anonymous visitor.

```bash
claude mcp add --transport http my-api http://localhost:5001/mcp --header "Authorization: Bearer <session token>"
```

To explore the tools, use the MCP Inspector: `npx @modelcontextprotocol/inspector`.

Create a dedicated user for each agent, with only the roles it needs, and sign it in to get its token. Revoke the session (`DELETE /api/auth/sessions/:sessionId`) to cut an agent off.

## Security

- Every call goes through your REST routes, so an agent can never do more than its user could with `curl`.
- Requests with an `Origin` header are only accepted from origins in `CORS_ORIGINS` or from `localhost`, as the MCP specification requires to prevent DNS rebinding. A wildcard CORS setting does not count.
- Only `POST` is accepted; bodies are limited to 1 MB.

---

Source: https://docs.calmapi.dev/blocks/notifications

# Notifications: inbox, push and email (notifications)

One call reaches people wherever they want to be reached. `ctx.notify()` writes an entry in the user's in-app inbox, sends a [push notification](/push-notifications) to every device they registered and an email, following each user's preferences and quiet hours. Notification types are small files you read in one glance, and your app's settings screen can be built from what the API returns.

```bash
npx calm add notifications
```

| Adds | |
|---|---|
| Files | `app/blocks/notifications/index.js`; the `notification` resource in `app/resources/notification/` (resource and routes); an example type in `app/notifications/welcome.js` |
| Environment | none |
| Collections | `notifications` (the inbox, entries expire after 180 days), `calm_notification_prefs` |
| Routes | `/api/notifications` (the inbox), `GET` and `PATCH /api/notifications/preferences` |

Push goes through [`app.push`](/push-notifications) and email through `app.mailer`, so in development everything lands in [devtools](/devtools): inbox entries in **Data**, pushes in **Push** (on a [simulated phone](/push-notifications#simulated-devices) if you add one), emails in **Mail**.

## Send one

```js
// app/resources/order/order.routes.js
r.post('/:id/ship', { policy: 'admin' }, async (ctx) => {
  const order = await ctx.service.update(ctx.params.id, { status: 'shipped' }, ctx);
  await ctx.notify(order.customer, 'order-shipped', { number: order.number });
  return order;
});
```

`ctx.notify(to, type, data)` takes a user id, a user record, or an array of them. It is on every route context, and services get it with the `ctx` you pass them. Outside a request (jobs, event listeners, scripts), use `app.ext.notify(...)`.

For a one-off message without a type file, pass the message itself. Its type is `message`:

```js
await ctx.notify(userId, { title: 'Your export is ready', url: '/exports/42', channels: ['inbox'] });
```

It resolves to what happened (an array when `to` is an array):

```json
{ "user": "6650c0ffee0000000000abcd", "type": "order-shipped", "channels": { "inbox": true, "push": "sent", "email": "sent" }, "quietHours": false, "id": "6650c0ffee0000000000beef" }
```

`id` is the inbox entry. `channels.push` is the [status of the push](/push-notifications#send-a-notification) (`captured` in development without a transport, `no-devices` when the user has no phone registered). A channel that preferences turned off is missing. Users that do not exist or are disabled are skipped: `{ "user": "...", "skipped": "no such user" }`.

## Types

A type is a file in `app/notifications/`, named after the type:

```js
// app/notifications/order-shipped.js
export default {
  title: ({ number }) => `Order #${number} shipped`,
  body: 'It arrives Thursday.',
  url: ({ number }) => `/orders/${number}`,
  category: 'orders',
  channels: ['inbox', 'push', 'email'],
  collapseId: ({ number }) => `order-${number}`,
};
```

Every field can be a value or a function of the data you pass to `ctx.notify()`.

| Field | |
|---|---|
| `title`, `body` | What people read. One of them is required. |
| `url` | Where a tap goes. Also sent as the link in the email (relative URLs resolve against `APP_URL`). |
| `data` | Extra data for the app. The push also carries `type` and `notificationId` (the inbox entry). |
| `category` | Lets people turn a whole group of types on or off |
| `channels` | Where it goes by default: `inbox`, `push`, `email`. Default: the `defaultChannels` setting (`['inbox', 'push']`). |
| `required` | `true` for security notices: preferences and quiet hours cannot turn it off |
| `email` | `{ subject, text, html }` when the email should say more than the push. Default subject: the title. Default text: the body and the link. |
| `collapseId` | A newer notification with the same id replaces the older one on the phone |
| `androidChannel` | Android notification channel id |
| `description` | Shown in the preferences list, for your settings screen |

`calm doctor` warns about types without a title or body, and about unknown channels.

## The inbox

Inbox entries are a regular resource, so they follow the same rules as everything else: each user lists, reads, marks and deletes only their own, and nobody creates them through the API. They expire after 180 days (change the TTL index in `notification.resource.js`).

| Endpoint | |
|---|---|
| `GET /api/notifications` | Newest first. `?readAt[exists]=false` for unread only, `?type=order-shipped` to filter |
| `GET /api/notifications/unread-count` | `{ count }` for the bell icon |
| `POST /api/notifications/:id/read` | Mark one read |
| `POST /api/notifications/read-all` | `{ marked }` |
| `DELETE /api/notifications/:id` | Remove one |

```bash
curl 'http://localhost:5001/api/notifications?readAt[exists]=false' -H "Authorization: Bearer $TOKEN"
```

With the [realtime-sse](/blocks/realtime-sse) block, new entries reach open browser tabs right away. With the `badge` setting on, the iPhone badge shows the unread count.

When someone taps a push, your app gets `data.notificationId`. Report the tap with `POST /api/auth/devices/opened { pushId, data }` (or call `POST /api/notifications/:id/read`), so the unread count stays right on every device. Either way the block only marks entries of the signed-in user. In devtools, tapping a notification on a simulated phone emits the same `push.opened` event.

## Preferences

```bash
curl http://localhost:5001/api/notifications/preferences -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": {
    "channels": {},
    "quietHours": null,
    "types": [
      { "type": "order-shipped", "category": "orders", "description": null, "channels": ["inbox", "push", "email"], "required": false },
      { "type": "welcome", "category": "account", "description": null, "channels": ["inbox", "push"], "required": false }
    ]
  }
}
```

`types` lists everything a user can receive, so your settings screen needs no list of its own. Turn channels off per type or per category, and set quiet hours in the user's own time zone. During quiet hours there is no push; the inbox and the email still get it.

```bash
curl -X PATCH http://localhost:5001/api/notifications/preferences \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "channels": { "orders": { "email": false } }, "quietHours": { "start": "22:00", "end": "07:00", "timeZone": "Europe/Berlin" } }'
```

- Keys in `channels` are type names, categories or `message` (one-off messages). A setting for a type wins over its category.
- `quietHours` takes `HH:MM` times and an IANA time zone (default `UTC`). `"quietHours": null` turns them off.
- Unknown types, channels or time zones answer `422` with the field that is wrong.
- Types marked `required: true` ignore preferences and quiet hours.

## Settings

```js
// calm.config.js
export default defineConfig({
  blocks: { notifications: { defaultChannels: ['inbox'], badge: true } },
});
```

| Option | Default | |
|---|---|---|
| `defaultChannels` | `['inbox', 'push']` | Channels for one-off messages and types that do not list theirs |
| `badge` | `true` | Send the unread count as the iPhone badge |

## Events and devtools

`notification.sent` is emitted for every user notified, with the result shown above:

```js
calm.on('notification.sent', ({ user, type, channels }) => metrics.increment('notification', { type }));
```

The devtools **Notifications** panel lists every type with its channels and the 20 latest inbox entries. `calm doctor` reports an error when the `notification` resource is missing.

## Testing

Notifications are captured in tests like everything else: pushes in `t.pushes`, emails in `t.mails`.

```js
test('the welcome notification reaches the inbox and the phone', async () => {
  const ada = await t.signup({ name: 'Ada' });
  await t.post('/auth/devices', { token: 'test-token-1', platform: 'ios' }, ada);

  const result = await t.app.ext.notify(ada.id, 'welcome', { name: 'Ada' });
  assert.equal(result.channels.inbox, true);
  assert.equal(t.pushes.at(-1).message.title, 'Welcome, Ada!');

  const unread = await t.get('/notifications/unread-count', ada);
  assert.equal(unread.body.data.count, 1);
});
```

---

Source: https://docs.calmapi.dev/blocks/privacy

# Privacy: export and delete (privacy)

Two rights most privacy laws give your users (GDPR articles 17 and 20, CCPA, LGPD and others): getting a copy of their data, and having it erased. This block adds both for the signed-in user, and for admins handling support requests. You decide per resource what an account deletion does to the records the user owns: delete them, keep them without the owner (anonymize), or keep them as they are. `calm doctor` shows the plan and warns about data that stays.

```bash
npx calm add privacy
```

| Adds | |
|---|---|
| Files | `app/blocks/privacy/index.js` (routes, guard, sweep, doctor), `export.js` (streamed export), `erase.js` (account deletion) |
| Environment | none (settings live in `calm.config.js` under `blocks.privacy`) |
| User field | `deletion`, hidden: set while an account is being deleted |

| Route | Who | What |
|---|---|---|
| `GET /api/auth/me/export` | signed in | A JSON download of everything you own |
| `DELETE /api/auth/me` | signed in | Delete your account, confirmed with your password |
| `POST /api/admin/users/:id/export` | admin | Export a user's data |
| `DELETE /api/admin/users/:id` | admin | Delete a user's account and data |
| `POST /api/admin/users/:id/cancel-deletion` | admin | Cancel a deletion during the grace period |

## Export your data

```bash
curl -OJ http://localhost:5001/api/auth/me/export -H "Authorization: Bearer $TOKEN"
# saves my-api-export-2026-10-12.json
```

The file holds your profile, every record you own in every resource with an owner field (`f.ref('user').owner()`), your sessions and your push devices, then a manifest:

```json
{
  "format": "calmapi-export/1",
  "app": "my-api",
  "userId": "6acd1c970d5d7607a3466c9c",
  "generatedAt": "2026-10-12T17:44:56.205Z",
  "profile": { "id": "6acd1c970d5d7607a3466c9c", "name": "Alice", "email": "alice@example.com", "roles": ["user"] },
  "resources": {
    "note": [{ "id": "6acd1c980d5d7607a3466c9e", "text": "Buy milk", "author": "6acd1c970d5d7607a3466c9c" }],
    "post": []
  },
  "sessions": [{ "id": "6acd1c980d5d7607a3466c9d", "createdAt": "...", "ip": "127.0.0.1", "userAgent": "..." }],
  "devices": [{ "id": "6acd1c98a9b5969f7217541e", "platform": "android", "token": "fcm-Al…abcdef" }],
  "manifest": { "generatedAt": "...", "resources": ["note", "post"], "counts": { "profile": 1, "note": 1, "post": 0, "sessions": 1, "devices": 1 } }
}
```

What the export guarantees:

- Records are serialized exactly as the API shows them to their owner: `.hidden()` and `.writeOnly()` fields and password hashes are never written, `visibleTo()` rules apply (an admin-only field stays out of a regular user's export), and `.encrypted()` fields are decrypted only where the owner may see them.
- Sessions come without their token hashes, push devices with masked tokens.
- Soft-deleted records ([soft-delete](/blocks/soft-delete) block) are included: they are still stored data.
- One cursor per resource, and the response is streamed, so a large account never sits in memory. If something fails halfway, the connection is cut, so a partial file never looks complete.
- 5 exports per user per hour (`exportLimit`, while `config.rateLimit.enabled` is on).
- `privacy.exported` is emitted with `{ userId, by, counts }` (`by` is `'self'` or `'admin'`, plus `adminId`).

The export follows ownership through owner fields only. Records that mention a user in another field (an assignee, a mention) are not that user's records; `calm doctor` lists those fields.

## Delete your account

```bash
curl -X DELETE http://localhost:5001/api/auth/me \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "password": "correct-horse-battery" }'
# 204: deleted
# 202 { "data": { "status": "scheduled", "scheduledFor": "..." } } with a grace period
```

The current password is the confirmation, so a stolen session token alone cannot delete an account. A wrong password answers `422` with `details.password` and emits `security.account_delete_failed`. The route is rate limited like login (`config.rateLimit.auth`).

What happens, in this order, so an interrupted deletion can always be finished:

1. The user is marked `status: 'deleting'`. From then on they cannot sign in (`403`) and no credential works (`401`), API keys included.
2. Sessions, password reset links, push devices, 2FA challenges and lockout counters are removed.
3. Each resource the user owns records in is deleted, anonymized or kept (below).
4. Collections in `alsoDelete` are cleaned (by default the [idempotency](/blocks/idempotency) block's stored responses).
5. The user record is deleted last, then `privacy.account_deleted` is emitted with `{ userId, by, resources: { note: { deleted: 3 }, comment: { anonymized: 1 } } }`. No other personal data is in the payload.

If the process stops midway, the sweep (every `sweepEveryMinutes`) finishes the job: every step is safe to run twice. Deleting a user with the user CRUD route (`DELETE /api/users/:id`) goes through the same erasure (turn that off with `cascadeCrudDelete: false`).

Records are deleted through your service hooks: a `beforeDelete` or `afterDelete` in `<name>.service.js` runs for each record (that is how the storage blocks remove the stored files). Services without delete hooks are cleaned with one `deleteMany`. Per-record `<name>.deleted` events are not emitted, because the [audit-log](/blocks/audit-log) block would copy the erased data into the audit trail. Listen to `privacy.account_deleted` instead.

## Delete, anonymize or keep, per resource

By default, records are deleted with their owner. Choose per resource:

```js
// app/resources/comment/comment.resource.js
export default resource('comment', {
  onOwnerDelete: 'anonymize', // 'delete' (default) | 'anonymize' | 'keep'
  personalFields: ['authorName'], // also removed when anonymizing
  fields: {
    body: f.text().required(),
    authorName: f.string(),
    author: f.ref('user').owner(),
  },
});
```

- `delete`: the records are removed.
- `anonymize`: the records stay, and the owner field and the personal fields are removed. Fields marked [`.pii()`](/resources#personal-data) count as personal too.
- `keep`: the records stay untouched and still hold the deleted account's id. Use it for what the law makes you keep (invoices, tax records) and say so in your privacy policy. `calm doctor` warns about every resource set to `keep`.

Or decide centrally, which wins over the resource option:

```js
// calm.config.js
export default defineConfig({
  blocks: {
    privacy: {
      resources: { invoice: 'keep', comment: 'anonymize' },
      personalFields: { comment: ['authorName', 'authorEmail'] },
    },
  },
});
```

Unknown behaviors and personal fields that do not exist stop the boot with an error.

## Grace period

```js
blocks: { privacy: { graceDays: 14 } }
```

With a grace period, the account is locked at once (steps 1 and 2) and erased when the period ends. `DELETE /api/auth/me` answers `202` with `scheduledFor`, and `privacy.deletion_requested` is emitted (send the "your account will be deleted on..." email from there). Support can undo it:

```bash
curl -X POST http://localhost:5001/api/admin/users/6acd1c970d5d7607a3466c9c/cancel-deletion \
  -H "Authorization: Bearer $ADMIN_TOKEN"
# 204: the account is back with its previous status and the user can sign in again
```

Sessions and devices removed meanwhile stay removed. The sweep runs every `sweepEveryMinutes` (default 60; its timer does not keep the process alive). Several instances can sweep at the same time: each account is claimed with a lease. Run it yourself from a [job](/blocks/jobs) or a script with `app.ext.privacy.sweep()`.

## Admin routes

```bash
# Export a user's data (as that user would see it, not as the admin sees it)
curl -X POST -OJ http://localhost:5001/api/admin/users/6acd1c970d5d7607a3466c9c/export \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Delete an account (follows graceDays)
curl -X DELETE http://localhost:5001/api/admin/users/6acd1c970d5d7607a3466c9c \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Delete right away, skipping the grace period
curl -X DELETE http://localhost:5001/api/admin/users/6acd1c970d5d7607a3466c9c \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "immediate": true }'
```

## Doctor

`calm doctor` (and the devtools **Doctor** panel) shows what deleting an account does:

```text
info  What deleting an account does
      Owned records: comment kept without owner (author, authorName removed); invoice kept as is;
      note deleted; post deleted. Always deleted: the profile, sessions, push devices, password
      reset links, calm_idempotency (by user). Grace period: none, data is erased right away.
warn  invoice: records stay when their owner deletes their account
info  User references that are not owner fields
      comment.mentions keep pointing at deleted accounts
```

## Settings

| Option | Default | |
|---|---|---|
| `graceDays` | `0` | Days between the request and the erasure; the account is locked meanwhile |
| `sweepEveryMinutes` | `60` | How often due and interrupted deletions are finished; `0` turns the timer off |
| `resources` | `{}` | `{ resource: 'delete' \| 'anonymize' \| 'keep' }`, wins over `onOwnerDelete` |
| `personalFields` | `{}` | `{ resource: ['field'] }`, removed when anonymizing |
| `alsoDelete` | `{ calm_idempotency: 'user' }` | Other collections to clean: `{ collection: 'fieldHoldingTheUserId' }`, for example `calm_audit_log: 'user'` if your retention policy allows |
| `exportLimit` | `{ windowMs: 3600000, max: 5 }` | Exports per user; `false` for no limit |
| `batchSize` | `200` | Cursor batch size for exports and per-record deletes |
| `cascadeCrudDelete` | `true` | `DELETE /api/users/:id` erases the same way |

## Events

| Event | Payload |
|---|---|
| `privacy.exported` | `{ userId, by, adminId?, counts }` |
| `privacy.deletion_requested` | `{ userId, by, adminId, scheduledFor }` |
| `privacy.deletion_cancelled` | `{ userId }` |
| `privacy.account_deleted` | `{ userId, by, resources }` |
| `security.account_delete_failed` | `{ userId, ip }` (wrong password) |

From code: `app.ext.privacy.request(userId, { by, immediate })`, `.purge(userId)`, `.cancel(userId)`, `.sweep()` and `.plan()`.

## Testing

```js
test('deleting an account removes what the user owns', async () => {
  const alice = await t.signup();
  await t.post('/notes', { text: 'Buy milk' }, alice);

  const exported = await t.get('/auth/me/export', alice);
  assert.equal(exported.body.resources.note.length, 1);

  const deleted = await t.delete('/auth/me', alice); // no password: refused
  assert.equal(deleted.status, 422);
  assert.equal((await t.request('DELETE', '/auth/me', { password: alice.password }, alice)).status, 204);
  assert.equal(await t.app.model('note').countDocuments(), 0);
  assert.equal((await t.get('/auth/me', alice)).status, 401);
});
```

`t.delete()` sends no body, so use `t.request('DELETE', path, body, auth)` to send the password.

---

Source: https://docs.calmapi.dev/blocks/push-expo

# Push notifications via Expo (push-expo)

Delivers [`app.push`](/push-notifications) notifications to Expo push tokens (Expo and React Native apps) through the [Expo push service](https://docs.expo.dev/push-notifications/sending-notifications/), the way Expo documents it: batches, throttling, retries and push receipts. No SDK, just `fetch`. It works next to [push-fcm](/blocks/push-fcm): Expo tokens go through Expo, native FCM tokens through FCM, from the same `ctx.push.send()` call.

```bash
npx calm add push-expo
```

| Adds | |
|---|---|
| Files | `app/blocks/push-expo/index.js` |
| Environment | `EXPO_ACCESS_TOKEN=` |
| Collection | `calm_expo_tickets` (tickets waiting for their receipt) |

## Setup

1. In the app, get a token with `Notifications.getExpoPushTokenAsync({ projectId })` from `expo-notifications` and register it with `POST /api/auth/devices` (see [Registering devices](/push-notifications#registering-devices)).
2. Optional, recommended: turn on **enhanced push security** in your Expo project settings, create an access token and set `EXPO_ACCESS_TOKEN`. Without it, anyone who learns a device token can send it notifications. `calm doctor` warns about this in production.
3. Send from your code: `await ctx.push.send({ to: userId, title, body })`.

## What it does

- Takes Expo push tokens only (`ExponentPushToken[...]`, `ExpoPushToken[...]`). Other tokens go to another transport, such as push-fcm, or are reported in the delivery log.
- Sends the Expo payload shown in the devtools **Push** panel: up to 100 notifications per request, at most 6 requests at a time and 600 notifications a second, gzip above 1 KB.
- Retries network errors, `429` and `5xx` answers with backoff. Tokens of several Expo projects in one batch are split and sent per project.
- Logs Expo's ticket id per device in the **Delivery** tab, with a hint for common errors (missing access token, invalid credentials, payload too big).
- Removes devices Expo reports as `DeviceNotRegistered` (the app was uninstalled or the token expired).

## Receipts

Expo first answers with a ticket: it accepted the notification. Whether Apple or Google took it comes later, as a receipt. The block stores the tickets and checks the receipts for you: 15 minutes after sending in production (every 5 minutes), 1 minute in development (every 30 seconds), so you see the result in devtools while you are still looking.

- A receipt lands in the same delivery log as the notification, and `push.receipt` is emitted with `{ id, device, ok, error, unregistered }`.
- `DeviceNotRegistered` removes the device. Credential errors are logged as errors, with what to fix.
- Tickets without a receipt after 24 hours are dropped with a warning (Expo keeps receipts for 24 hours).

Run a check yourself with `app.ext.pushExpo.checkReceipts({ olderThan: 0 })`, for example from a [job](/blocks/jobs) or a test.

## Development and tests

In development the block delivers to real Expo tokens, so you can test on your phone with Expo Go or a development build: paste your token in devtools (**Push**, **Devices**, **Add device**) or let the app register it. [Simulated devices](/push-notifications#simulated-devices) never leave your machine. In tests nothing is sent: notifications are captured in `t.pushes`, unless `EXPO_API_URL` points at a fake server.

| Variable | |
|---|---|
| `EXPO_ACCESS_TOKEN` | Access token for enhanced push security |
| `EXPO_API_URL` | Expo push API base URL (default `https://exp.host/--/api/v2`): a proxy, or a fake server in tests |

---

Source: https://docs.calmapi.dev/blocks/push-fcm

# Push notifications via Firebase Cloud Messaging (push-fcm)

Delivers [`app.push`](/push-notifications) notifications to Android, iOS and web apps through the [FCM HTTP v1 API](https://firebase.google.com/docs/cloud-messaging/send-message). No SDK: the block signs a service account token with `node:crypto` and calls FCM with `fetch`. It works next to [push-expo](/blocks/push-expo): native tokens go through FCM, Expo push tokens through Expo, from the same `ctx.push.send()` call.

```bash
npx calm add push-fcm
```

| Adds | |
|---|---|
| Files | `app/blocks/push-fcm/index.js` |
| Environment | `FCM_SERVICE_ACCOUNT=` |

## Setup

1. In the Firebase console: **Project settings**, **Service accounts**, **Generate new private key**. Keep the JSON file out of git.
2. Set `FCM_SERVICE_ACCOUNT` to the path of that file, or to the JSON itself (handy on hosts that only take environment variables). `GOOGLE_APPLICATION_CREDENTIALS` works too.
3. For iOS, upload your APNs authentication key in **Project settings**, **Cloud Messaging**. FCM delivers to Apple for you.
4. In the app, get a token from the Firebase SDK (`getToken()`) and register it with `POST /api/auth/devices` (see [Registering devices](/push-notifications#registering-devices)).
5. Send from your code: `await ctx.push.send({ to: userId, title, body })`.

## What it does

- Takes every token except Expo push tokens (`ExponentPushToken[...]`), which belong to push-expo. With both blocks installed, each device goes to the right service.
- Exchanges a JWT signed with the service account key (RS256) for an access token, cached until a minute before it expires.
- Sends the FCM payload shown in the devtools **Push** panel, one request per device, ten at a time. The payload includes the Android, APNs (push type and priority) and Web Push settings for the message.
- Logs FCM's message name per device (**Delivery** tab in devtools).
- Removes devices FCM reports as `UNREGISTERED` (the app was uninstalled or the token expired).

In development it delivers to real tokens, so you can test on your phone. [Simulated devices](/push-notifications#simulated-devices) never leave your machine. In tests nothing is sent: notifications are captured in `t.pushes`.

`calm doctor` reports an error when the service account cannot be read or misses `project_id`, `client_email` or `private_key`, and in production when it is not set.

| Variable | |
|---|---|
| `FCM_SERVICE_ACCOUNT` | Path to the service account JSON, or the JSON itself |
| `GOOGLE_APPLICATION_CREDENTIALS` | Used when `FCM_SERVICE_ACCOUNT` is not set |
| `FCM_API_URL` | Override the FCM endpoint (a proxy, or a fake server in tests) |

---

Source: https://docs.calmapi.dev/blocks/rate-limit-mongo

# Shared rate limits (rate-limit-mongo)

Stores rate limit counters in MongoDB, so limits hold across every instance of your API instead of per process.

```bash
npx calm add rate-limit-mongo
```

| Adds | |
|---|---|
| Files | `app/blocks/rate-limit-mongo/index.js` |
| Collection | `calm_rate_limits` (cleaned up by a TTL index) |

Nothing to configure: once added, the global limit, the auth limit and per-route `rateLimit` options all count in MongoDB. The limits themselves stay in `config.rateLimit` (see [Configuration](/configuration)).

## Why

The default store keeps counters in memory. With three instances behind a load balancer, a client effectively gets three times the limit, and the login limit (10 attempts per 15 minutes) becomes 30. With this block every instance shares one counter per client and window.

## How it works

Fixed windows: one document per key and window (`<limit>:<ip>:<window start>`), incremented atomically with an upsert, with an expiry date at the end of the window. MongoDB's TTL monitor removes old documents (it runs about once a minute, so the collection holds slightly more than the current windows).

Each limited request costs one small write. Behind a proxy, set `TRUST_PROXY` so the key is the client's IP and not the proxy's.

---

Source: https://docs.calmapi.dev/blocks/realtime-sse

# Realtime (realtime-sse)

Live resource changes over [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Every event is checked for every subscriber with the same rules as `GET /api/<resources>/:id`: the read policy, owner scoping, the service's `scope()` and field visibility. The stream never shows anything the REST API would not.

```bash
npx calm add realtime-sse
```

| Adds | |
|---|---|
| Files | `app/blocks/realtime-sse/index.js` |
| Routes | `POST /api/realtime/ticket` (authenticated), `GET /api/realtime/stream` (public) |

## Subscribe

Browsers' `EventSource` cannot send an `Authorization` header, and session tokens must not travel in URLs, so signed-in clients first exchange their session for a **single-use ticket** valid for 60 seconds:

```js
const res = await fetch('/api/realtime/ticket', { method: 'POST', headers: { Authorization: `Bearer ${token}` } });
const { data } = await res.json(); // { ticket, expiresIn: 60 }

const events = new EventSource(`/api/realtime/stream?resources=post,comment&ticket=${data.ticket}`);

events.addEventListener('post.created', (e) => addPost(JSON.parse(e.data)));
events.addEventListener('post.updated', (e) => updatePost(JSON.parse(e.data)));
events.addEventListener('post.deleted', (e) => removePost(JSON.parse(e.data).id));
```

Anonymous visitors can subscribe without a ticket and receive only what `public` read policies allow:

```js
const events = new EventSource('/api/realtime/stream?resources=post');
```

## Events

| Event | Data |
|---|---|
| `ready` | `{ resources, user }`, sent once when the stream opens |
| `<resource>.created` | The record, serialized for this subscriber |
| `<resource>.updated` | The record, serialized for this subscriber |
| `<resource>.deleted` | `{ id }` |
| `<resource>.restored` | The record (with the [soft-delete](/blocks/soft-delete) block) |

With the `api` template's posts, a visitor's stream only carries published posts, while the author's stream also carries their own drafts, and neither ever contains the author's email.

Every event goes through [`app.canRead()`](/building-blocks#reading-records-outside-a-request), the rules of `GET /api/<resource>/:id` (read policy, owner scoping and the service `scope()`). That includes `deleted` events: a subscriber only learns that a record was deleted if they could read it.

## Errors

| Status | When |
|---|---|
| `400` | `resources` is missing or names an unknown resource |
| `401` | The ticket is unknown, expired or already used |

The connection sends a comment every 25 seconds to stay open through proxies, and tells clients to reconnect after 3 seconds. Behind nginx, `X-Accel-Buffering: no` is set so events are not buffered. Get a new ticket before reconnecting a signed-in stream.

## Several instances

Events are in-process: a subscriber only receives changes made by the instance it is connected to. With several instances, either pin realtime clients to one instance, or forward events between instances, for example by publishing them from a MongoDB change stream in each instance. The block's code in `app/blocks/realtime-sse/index.js` is the place to add that.

The devtools **Realtime** panel lists connected subscribers and pending tickets.

---

Source: https://docs.calmapi.dev/blocks/soft-delete

# Soft delete (soft-delete)

Opt-in soft delete per resource: `DELETE` marks a record as deleted instead of removing it, every query hides deleted records, and admins can list and restore them.

```bash
npx calm add soft-delete
```

| Adds | |
|---|---|
| Files | `app/blocks/soft-delete/index.js` |
| Routes, per enabled resource | `GET /api/<names>/trash`, `POST /api/<names>/:recordId/restore` (admin) |

## Enable it on a resource

```js
export default resource('note', {
  softDelete: true,
  fields: {
    text: f.string().required(),
    author: f.ref('user').owner(),
  },
  policy: { list: 'owner | admin', read: 'owner | admin', create: 'authenticated', update: 'owner | admin', delete: 'owner | admin' },
});
```

The block adds a hidden `deletedAt` date field to the resource and replaces its service's `remove()`:

- `DELETE /api/notes/:id` sets `deletedAt` and answers `204`, with the same policy checks and hooks (`beforeDelete`, `afterDelete`) as before.
- Every query (`find`, `findOne`, `countDocuments`, updates and aggregations) ignores records with a `deletedAt`, so they disappear from lists, reads, updates and includes.
- The usual `note.deleted` event is emitted, with `soft: true` in the payload.

## Trash and restore

| Route | Does |
|---|---|
| `GET /api/notes/trash` | Deleted notes, most recently deleted first (up to 100) |
| `POST /api/notes/:recordId/restore` | Clears `deletedAt` and returns the note. Emits `note.restored`. |

From code, `ctx.services.note.restore(id, ctx)` does the same.

## Reading deleted records yourself

Queries skip deleted records unless their filter mentions `deletedAt` or they pass the `withDeleted` option:

```js
const deleted = await this.model.find({ deletedAt: { $ne: null } }).lean();
const everything = await this.model.find({}).setOptions({ withDeleted: true }).lean();
```

Deleted records stay in the collection, including their unique values: a new record cannot reuse the email or slug of a soft-deleted one. Purge old ones with a scheduled [job](/blocks/jobs) if you need to.

---

Source: https://docs.calmapi.dev/blocks/storage-local

# Local file storage (storage-local)

File uploads to the server's disk, with a `file` resource for the metadata. Uploads are checked against a type and size allowlist, the first bytes must match the declared type, stored names are random, and downloads are private to their owner.

```bash
npx calm add storage-local
```

| Adds | |
|---|---|
| Files | `app/blocks/storage-local/index.js`, `storage.js`; the `file` resource in `app/resources/file/` (resource, service and routes) |
| Dependency | `multer` |
| Environment | `UPLOAD_DIR=./uploads`, `UPLOAD_MAX_MB=10`, `UPLOAD_ALLOWED_TYPES=image/png,image/jpeg,image/gif,image/webp,application/pdf` |
| Conflicts with | `storage-s3` (both provide the `file` resource) |

Add `uploads/` to `.gitignore`.

## Routes

| Route | Policy | Does |
|---|---|---|
| `POST /api/files/upload` | authenticated | Upload one file as `multipart/form-data`, field `file`. `201 { data: file }` |
| `GET /api/files` | owner, admin | Your files (admins: all), with the usual filters: `?mimeType=image/png&sort=-size` |
| `GET /api/files/:id` | owner, admin | One file's metadata |
| `GET /api/files/:id/download` | owner, admin | The file itself |
| `DELETE /api/files/:id` | owner, admin | Deletes the record and the file on disk. `204` |

```bash
curl -H "Authorization: Bearer $TOKEN" -F file=@photo.png http://localhost:5001/api/files/upload
```

```json
{
  "data": {
    "id": "6acb4f0e7e4a738ebdd998c2",
    "originalName": "photo.png",
    "mimeType": "image/png",
    "size": 48213,
    "owner": "6acb46a57e4a738ebdd998b1",
    "createdAt": "2026-10-11T08:40:12.511Z",
    "updatedAt": "2026-10-11T08:40:12.511Z"
  }
}
```

From a browser:

```js
const form = new FormData();
form.append('file', input.files[0]);
const res = await fetch('/api/files/upload', { method: 'POST', body: form, headers: { Authorization: `Bearer ${token}` } });
```

## What is checked

- **Signed in first.** The upload parser does not even run for signed-out requests.
- **Type allowlist.** The declared type must be in `UPLOAD_ALLOWED_TYPES`, otherwise `400`.
- **Size.** Larger than `UPLOAD_MAX_MB` is a `400`. One file per request.
- **Content.** For PNG, JPEG, GIF, WebP and PDF, the first bytes must match the declared type. An HTML file renamed `photo.png` is rejected and deleted.
- **Names.** Files are stored as `<uuid>.<ext>` in `UPLOAD_DIR`; the original name is only kept as metadata. The storage key is a `hidden()` field and never leaves the server.
- **Downloads.** Images are served inline; everything else as an attachment. Responses carry `X-Content-Type-Options: nosniff` and a sandboxing Content-Security-Policy, so an uploaded file cannot run scripts on your domain.

## Changing the rules

The code is in your project. Common changes:

- **Who sees what:** edit the policies in `app/resources/file/file.resource.js` (for example `read: 'authenticated'` for files any user may download).
- **More types:** add them to `UPLOAD_ALLOWED_TYPES`. Types without a known signature are accepted on the declared type alone; prefer types you can verify.
- **Linking files to records:** add `f.ref('file')` fields to your resources, and `?include=avatar` returns the file metadata.

Local disk does not work with several instances or ephemeral containers; `calm doctor --prod` points this out. Use [storage-s3](/blocks/storage-s3) there.

---

Source: https://docs.calmapi.dev/blocks/storage-s3

# S3 file storage (storage-s3)

Uploads that go straight from the browser to S3 (or Cloudflare R2, MinIO, any S3-compatible store) with presigned URLs, so file bytes never pass through your API servers. Objects stay private; downloads use short-lived signed URLs.

```bash
npx calm add storage-s3
```

| Adds | |
|---|---|
| Files | `app/blocks/storage-s3/index.js`, `s3.js`; the `file` resource in `app/resources/file/` |
| Dependencies | `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner` |
| Environment | `S3_BUCKET`, `S3_REGION=us-east-1`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, `UPLOAD_MAX_MB=10`, `UPLOAD_ALLOWED_TYPES` |
| Conflicts with | `storage-local` |

Without `S3_ACCESS_KEY_ID`, the AWS default credential chain is used (IAM role, profile, `AWS_*` variables). For R2 or MinIO, set `S3_ENDPOINT`. `calm doctor` reports a missing `S3_BUCKET`.

## The upload flow

**1. Ask for an upload URL.** The API checks type and size and creates a `pending` file record.

```bash
curl -X POST http://localhost:5001/api/files/presign -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"fileName":"cat.png","contentType":"image/png","size":48213}'
```

```json
{
  "data": {
    "file": { "id": "6acb51d27e4a738ebdd998d0", "originalName": "cat.png", "mimeType": "image/png", "size": 48213, "status": "pending", "owner": "6acb46a57e4a738ebdd998b1", "createdAt": "...", "updatedAt": "..." },
    "upload": { "url": "https://my-bucket.s3.us-east-1.amazonaws.com/uploads/...&X-Amz-Signature=...", "method": "PUT", "headers": { "Content-Type": "image/png" }, "expiresIn": 600 }
  }
}
```

**2. Upload the bytes** directly to S3, from the browser:

```js
await fetch(upload.url, { method: upload.method, headers: upload.headers, body: fileInput.files[0] });
```

The signature covers the content type and length, so the client cannot upload something else.

**3. Confirm.** The API checks that the object exists with the declared size and type, then marks the file `ready`:

```bash
curl -X POST http://localhost:5001/api/files/6acb51d27e4a738ebdd998d0/complete -H "Authorization: Bearer $TOKEN"
```

## Routes

| Route | Policy | Does |
|---|---|---|
| `POST /api/files/presign` | authenticated | Start an upload: `{ fileName, contentType, size }`. `201 { data: { file, upload } }` |
| `POST /api/files/:id/complete` | owner | Verify the object and mark the file `ready` |
| `GET /api/files/:id/download` | owner, admin | `302` redirect to a signed URL valid for 5 minutes |
| `GET /api/files`, `GET /api/files/:id` | owner, admin | Metadata, with `status` filterable |
| `DELETE /api/files/:id` | owner, admin | Deletes the record and the S3 object |

Upload URLs expire after 10 minutes. Object keys look like `uploads/<userId>/<yyyy>/<mm>/<uuid>.<ext>` and are stored in a `hidden()` field.

## Bucket CORS

The browser uploads to the bucket directly, so the bucket must allow `PUT` from your frontend. For AWS S3:

```json
[
  {
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["Content-Type"],
    "MaxAgeSeconds": 3600
  }
]
```

Keep the bucket private (no public access); every download goes through the API and a signed URL. Pending files whose upload never completed stay `pending`; clean them up with a scheduled [job](/blocks/jobs) if you need to.

---

Source: https://docs.calmapi.dev/blocks/totp

# Two-factor authentication (totp)

Adds a second step to sign-in with an authenticator app (Google Authenticator, 1Password, Authy and the like). Codes follow RFC 6238 (6 digits, every 30 seconds) and are computed with `node:crypto`, so the block has no dependencies. Users who turn it on also get 10 single-use recovery codes.

```bash
npx calm add totp
```

| Adds | |
|---|---|
| Files | `app/blocks/totp/index.js`, `totp.js` |
| Environment | `TOTP_ISSUER=My App` (the name authenticator apps show; empty: the app name) |
| User fields | `twoFactorEnabledAt` (read-only, visible to the owner and admins), and the hidden `totpSecret`, `totpPendingSecret`, `totpLastStep` and `totpRecovery` |
| Collection | `calm_mfa_challenges` (entries expire on their own) |
| Routes | `POST /api/auth/2fa/setup`, `/enable`, `/verify`, `/disable` |

Encrypt the secrets at rest by setting encryption keys before users turn 2FA on:

```bash
npx calm keygen --write
```

With `CALM_ENCRYPTION_KEYS` set, `totpSecret` and `totpPendingSecret` are [`.encrypted()`](/security#encryption-at-rest) fields. Without keys the block still works, but stores secrets in plain text, and `calm doctor` warns (`totp-unencrypted`). Set the same keys in production.

## Routes

| Route | Policy | Body | Success |
|---|---|---|---|
| `POST /api/auth/2fa/setup` | authenticated | | `200 { data: { secret, otpauthUrl } }` |
| `POST /api/auth/2fa/enable` | authenticated, rate limited | `{ code }` | `200 { data: { enabled, recoveryCodes, note } }` |
| `POST /api/auth/2fa/verify` | public, rate limited | `{ mfaToken, code }` or `{ mfaToken, recoveryCode }` | `200 { data: { user, token, expiresAt } }` |
| `POST /api/auth/2fa/disable` | authenticated, rate limited | `{ password }` | `204` |

## Turn it on

1. Start the setup as the signed-in user:

   ```bash
   curl -X POST http://localhost:5001/api/auth/2fa/setup -H "Authorization: Bearer $TOKEN"
   ```

   ```json
   {
     "data": {
       "secret": "U2M5Y6PWULASWCRACIXFLGOPMQZ2JL2G",
       "otpauthUrl": "otpauth://totp/My%20App:ada%40example.com?secret=U2M5Y6PWULASWCRACIXFLGOPMQZ2JL2G&issuer=My%20App&algorithm=SHA1&digits=6&period=30"
     }
   }
   ```

   Render `otpauthUrl` as a QR code in your frontend with any QR library, and show `secret` for people who type it in. The secret stays pending until the next step. Calling setup again replaces it. If 2FA is already on, setup answers `400` (`Two-factor authentication is already on`).

2. Confirm with the code the app shows:

   ```bash
   curl -X POST http://localhost:5001/api/auth/2fa/enable -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' -d '{"code":"492039"}'
   ```

   ```json
   {
     "data": {
       "enabled": true,
       "recoveryCodes": ["e72a3-29307", "15a14-8a64c", "b51ad-e5ae2", "c0aab-3b768", "a3802-32020", "c5b91-b2e82", "fdb66-edf87", "fa5f7-43ef4", "d0508-9084e", "63722-ce01d"],
       "note": "Store these codes safely. Each works once. They will not be shown again."
     }
   }
   ```

   Show the recovery codes once and ask the user to store them. A wrong code answers `422` with `details.code`. Every other session of the user ends, because those sessions were created without a second factor.

`GET /api/auth/me` now includes `twoFactorEnabledAt`, so your settings page can tell whether 2FA is on.

## Sign in

With 2FA on, a correct email and password no longer return a session. Login answers `200` with a challenge instead:

```bash
curl -X POST http://localhost:5001/api/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct-horse-battery"}'
```

```json
{
  "data": {
    "mfaRequired": true,
    "mfaToken": "mfa_i3u6jcWUM-GBSlgHVkCEfN96-gP03Eol",
    "methods": ["totp", "recovery"],
    "expiresAt": "2026-10-11T09:39:03.125Z"
  }
}
```

Clients check `mfaRequired`, ask for a code, and finish the sign-in:

```bash
curl -X POST http://localhost:5001/api/auth/2fa/verify -H 'Content-Type: application/json' \
  -d '{"mfaToken":"mfa_i3u6jcWUM-GBSlgHVkCEfN96-gP03Eol","code":"318604"}'
```

The answer is the normal login response, `{ data: { user, token, expiresAt } }`. To use a recovery code, send `recoveryCode` instead of `code`:

```json
{ "mfaToken": "mfa_i3u6jcWUM-GBSlgHVkCEfN96-gP03Eol", "recoveryCode": "e72a3-29307" }
```

| Answer | When |
|---|---|
| `401 Invalid code` | The code or recovery code is wrong, or the code was already used |
| `401 This sign-in has expired, sign in again` | The `mfaToken` is unknown, older than 5 minutes, already used, or has had 5 attempts |
| `422` | Neither `code` nor `recoveryCode` was sent |

## Turn it off

Turning 2FA off needs the user's password:

```bash
curl -X POST http://localhost:5001/api/auth/2fa/disable -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"password":"correct-horse-battery"}'
```

`204` on success. The secret, recovery codes and `twoFactorEnabledAt` are removed. A wrong password answers `422` with `details.password`.

## How it is protected

- **No session before the second factor.** Login returns only a challenge. The `mfaToken` is random, stored as a SHA-256 hash, single use, valid for 5 minutes and allows 5 attempts.
- **No replay.** A code is accepted for its own 30 second step and the steps right before and after it (clock drift). The last used step is stored, so a code works only once.
- **Recovery codes.** 10 per user, stored as SHA-256 hashes and removed when used.
- **Secrets stay private.** They are hidden fields: never returned, not even to their owner, and encrypted at rest when keys are set.
- **Rate limits.** `enable`, `verify` and `disable` share the auth limiter (10 requests per 15 minutes per IP and route). Wrong passwords still count toward [account lockout](/authentication#account-lockout).
- **Constant time.** Codes are compared with `timingSafeEqual`.

## Security events

The block emits [security events](/security#security-events) that show up in the devtools **Security** panel:

| Event | Payload |
|---|---|
| `security.2fa_enabled` | `{ userId }` |
| `security.2fa_disabled` | `{ userId }` |
| `security.2fa_failed` | `{ userId, ip, attempt }` |
| `security.2fa_recovery_used` | `{ userId, remaining }` |

## How it hooks into login

The block uses the `loginChallenge` [plugin hook](/building-blocks#the-auth-service). It runs after a correct password, before a session is created. Other sign-in blocks such as [magic-link](/blocks/magic-link) go through the same hook (they call `completeLogin()`), so a user with 2FA on is asked for a code there too. A hook that returns an object answers the login with that object instead of a session. Once the second factor checks out, the block calls `calm.app.auth.service.finishLogin(user, req)`, which creates the session and returns the usual login response:

```js
// app/blocks/totp/index.js (simplified)
calm.loginChallenge(async (user) => {
  if (!user.twoFactorEnabledAt) return null; // no challenge: normal login
  const token = `mfa_${randomBytes(24).toString('base64url')}`;
  const expiresAt = new Date(Date.now() + 5 * 60_000);
  await Challenge.create({ _id: sha(token), user: user._id, expiresAt });
  return { mfaRequired: true, mfaToken: token, methods: ['totp', 'recovery'], expiresAt };
});
```

The same hook works for other second factors, such as email codes or passkeys. The code is in your project, so you can change the challenge lifetime, the number of recovery codes or the issuer name there.

---

Source: https://docs.calmapi.dev/blocks/webhooks

# Webhooks (webhooks)

Outgoing webhooks for your API. Your users (and admins) register a URL, pick events like `order.created` or `order.*`, and receive an HTTP `POST` every time a matching record changes. Each user only receives records they are allowed to read, serialized exactly like the REST API returns them to that user. Requests are signed with the [Standard Webhooks](https://www.standardwebhooks.com) scheme, queued in MongoDB, retried with backoff and logged per endpoint. URLs that point at localhost, private networks or cloud metadata services are refused in production. No dependencies.

```bash
npx calm add webhooks
```

| Adds | |
|---|---|
| Files | `app/blocks/webhooks/index.js` (routes, events, doctor, devtools), `delivery.js` (queue and sender), `signing.js` (signatures and `verifyWebhook`), `ssrf.js` (URL safety) |
| Environment | `WEBHOOKS_WORKER=on` (set `off` on instances that should not send webhooks) |
| Collections | `calm_webhooks` (endpoints), `calm_webhook_deliveries` (queue and delivery log, cleaned up by a TTL index) |
| Routes | `/api/webhooks` (see [API](#api)) |

Set encryption keys so signing secrets and queued payloads are encrypted at rest:

```bash
npx calm keygen --write
```

## Quick start

Create an endpoint as a signed-in user. The response is the only time the signing secret is shown:

```bash
curl -X POST http://localhost:5001/api/webhooks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/calm", "events": ["post.created", "post.updated"] }'
```

```json
{
  "data": {
    "id": "6650c0ffee0000000000abcd",
    "url": "https://example.com/hooks/calm",
    "events": ["post.created", "post.updated"],
    "scope": "own",
    "enabled": true,
    "status": "active",
    "secret": "whsec_<shown once>"
  }
}
```

Send yourself a test event, then look at the delivery log:

```bash
curl -X POST http://localhost:5001/api/webhooks/6650c0ffee0000000000abcd/test -H "Authorization: Bearer $TOKEN"
curl http://localhost:5001/api/webhooks/6650c0ffee0000000000abcd/deliveries -H "Authorization: Bearer $TOKEN"
```

Event names are `<resource>.created`, `<resource>.updated`, `<resource>.deleted` (and `<resource>.restored` with the [soft-delete](/blocks/soft-delete) block). Use `<resource>.*` for all four, or `*` for every resource. Unknown resources and events answer `422` with the list of valid ones.

## What receivers get

A `POST` with a JSON body and three headers:

```http
POST /hooks/calm HTTP/1.1
content-type: application/json
webhook-id: msg_<random id>
webhook-timestamp: 1767225600
webhook-signature: v1,<base64 signature>

{"type":"post.created","timestamp":"2026-01-01T00:00:00.000Z","data":{"id":"6650...","title":"Hello","status":"published","author":"6650...","createdAt":"...","updatedAt":"..."}}
```

- `webhook-id` is the same on every retry of a message: store it and skip duplicates.
- `webhook-timestamp` is the time of this attempt, so old messages cannot be replayed.
- `webhook-signature` is `v1,` followed by the base64 HMAC-SHA256 of `id.timestamp.body`, keyed with the base64-decoded part of the secret after `whsec_`. During a secret rotation it holds two signatures separated by a space.
- `data` is the record as the endpoint owner would see it from `GET /api/<resource>/:id`. Deleted records are sent as they were just before deletion.

Answer with any `2xx` status quickly and do slow work in the background. Anything else, a redirect, or no answer within 10 seconds counts as a failed attempt.

## Verifying signatures

The block exports `verifyWebhook(secret, headers, rawBody)`. It checks the signature in constant time and refuses timestamps more than 5 minutes away from now. It returns the parsed payload or throws a `WebhookVerificationError`. It needs the raw body: parsing the JSON and serializing it again changes the bytes.

`app/blocks/webhooks/signing.js` only imports `node:crypto`, so copy it into the app that receives the webhooks. Any Standard Webhooks library (for example the `standardwebhooks` npm package) works too.

```js
import express from 'express';
import { verifyWebhook } from './signing.js';

const app = express();

app.post('/hooks/calm', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(process.env.CALM_WEBHOOK_SECRET, req.headers, req.body);
  } catch {
    return res.sendStatus(401);
  }
  if (event.type === 'post.created') queuePostSync(event.data);
  res.sendStatus(204);
});
```

With plain `node:http` or a fetch-style handler, pass the body as a string or Buffer and the headers as they are (`req.headers` or a `Headers` object).

## Who receives what

- **Own endpoints** (the default) receive a record only if their owner may read it through the API: the resource's `read` policy, owner scoping (`'owner'`) and the service `scope()` (drafts, tenants...). This is [`app.canRead()`](/building-blocks#reading-records-outside-a-request). The payload is serialized for that owner, so `hidden()` fields never appear and `visibleTo()` fields only appear for users allowed to see them. With the `api` template, Bob's endpoint does not receive Alice's draft posts, and receives the post once she publishes it.
- **Global endpoints** receive every record of the events they follow, whatever its read policy, serialized with the admin's view (hidden fields still never appear). The service `scope()` still applies, so in a multi-tenant app a tenant admin only receives their tenant's records. Only users matching `globalPolicy` (default `'admin'`) can create them, and they stop receiving events if their owner loses that role:

```json
{ "url": "https://ops.example.com/hooks", "events": ["*"], "scope": "global" }
```

Endpoints belong to their owner: other users get `404` for every route of an endpoint that is not theirs. Disabled users receive nothing, and a deleted user's endpoints and delivery log are removed.

Keep a resource out of webhooks entirely with `webhooks: false` in its `resource()` options.

## Retries and failures

Deliveries are queued in MongoDB and sent by a worker in every instance. A delivery is claimed atomically, so it is never sent twice. A failed attempt is retried after 5 s, 30 s, 2 min, 10 min, 30 min, 2 h and 6 h (each with 20% random jitter, and later when the receiver sends `Retry-After`), then the delivery is marked `failed`.

- `410 Gone` turns the endpoint off at once: the receiver is asking you to stop.
- After `disableAfterFailures` deliveries in a row (default 5) fail every retry, the endpoint is turned off.
- When an endpoint is turned off, the block emits `webhook.disabled` with `{ webhook, owner, reason }` (`'gone'`, `'failing'` or `'manual'`) and emails the owner (turn that off with `notifyOwner: false`).

```js
// In any block: also alert your team
calm.on('webhook.disabled', ({ webhook, reason }) => {
  if (reason !== 'manual') calm.log.warn(`Webhook ${webhook.id} turned off: ${reason}`);
});
```

The owner turns it back on with `PATCH /api/webhooks/:id { "enabled": true }`, which also resets its failure counters.

### The delivery log

`GET /api/webhooks/:id/deliveries?status=failed&limit=20` returns the latest deliveries, newest first:

```json
{
  "id": "6650...",
  "type": "post.updated",
  "messageId": "msg_<random id>",
  "status": "succeeded",
  "attempts": 3,
  "statusCode": 200,
  "durationMs": 84,
  "error": null,
  "nextAttemptAt": null,
  "response": "ok",
  "payload": "{\"type\":\"post.updated\",...}",
  "payloadTruncated": false,
  "attemptLog": [
    { "at": "...", "statusCode": 500, "durationMs": 12, "error": "HTTP 500" },
    { "at": "...", "statusCode": 500, "durationMs": 9, "error": "HTTP 500" },
    { "at": "...", "statusCode": 200, "durationMs": 84, "error": null }
  ]
}
```

`status` is `pending`, `sending`, `succeeded` or `failed`. The receiver's answer is kept up to 1 KB and the payload preview up to 2 KB. Entries are deleted `keepDeliveriesDays` (default 14) after they finish. `POST /api/webhooks/:id/deliveries/:deliveryId/retry` sends one again right away, with the same `webhook-id` and a fresh retry schedule.

## Rotating the secret

```bash
curl -X POST http://localhost:5001/api/webhooks/6650c0ffee0000000000abcd/rotate-secret -H "Authorization: Bearer $TOKEN"
```

The response shows the new secret, once. For `secretGraceHours` (default 24) every message is signed with both the new and the old secret, so receivers can switch without missing anything.

Secrets must be readable to sign messages, so they cannot be hashed. With `CALM_ENCRYPTION_KEYS` set they are encrypted at rest with AES-256-GCM, together with queued payloads (which can contain fields your resources store `.encrypted()`).

## SSRF protection

Webhook URLs are typed by users and called by your server, so they are checked twice: when an endpoint is saved, and on every delivery.

- Only `http://` and `https://`, and no user name or password in the URL. In production, `https://` only (`requireHttps`).
- In production, hosts must be public. Refused: `localhost`, loopback (`127.0.0.0/8`, `::1`), private networks (`10/8`, `172.16/12`, `192.168/16`, `fc00::/7`), link-local and cloud metadata addresses (`169.254.169.254`, `fd00:ec2::254`, `100.100.100.200`, `192.0.0.192`), carrier-grade NAT (`100.64/10`), multicast, reserved and documentation ranges, and IPv6 forms that carry such an IPv4 address (`::ffff:127.0.0.1`, NAT64, 6to4).
- Host names are resolved and every address must be public. When sending, the connection goes to the address that was checked, so a DNS answer that changes in between (DNS rebinding) cannot reach your network.
- Redirects are never followed: a `3xx` answer is a failed attempt.

In development and tests (`allowPrivate`, on by default outside production) local receivers such as `http://localhost:4000/hooks` work. `calm doctor` warns if `allowPrivate` is on in production.

## Settings

Set them in `calm.config.js`:

```js
export default defineConfig({
  blocks: {
    webhooks: {
      maxEndpointsPerUser: 5,
      retrySchedule: ['10s', '1m', '10m', '1h', '6h', '24h'],
      policy: 'admin', // only admins manage webhooks
    },
  },
});
```

| Option | Default | |
|---|---|---|
| `policy` | `'authenticated'` | Who may create and manage their own endpoints |
| `globalPolicy` | `'admin'` | Who may create `scope: 'global'` endpoints |
| `allowPrivate` | on in development and test | Allow localhost and private addresses |
| `requireHttps` | on in production | Refuse `http://` URLs |
| `maxEndpointsPerUser` | `10` | Endpoints per user (`409 LIMIT_REACHED` beyond) |
| `maxEventsPerEndpoint` | `20` | Event names per endpoint |
| `maxUrlLength` | `2048` | Characters |
| `retrySchedule` | `['5s', '30s', '2m', '10m', '30m', '2h', '6h']` | Waits between attempts: milliseconds, or `'30s'`, `'5m'`, `'2h'`, `'1d'` |
| `timeoutMs` | `10000` | Time a receiver has to answer |
| `pollMs` | `1000` | How often the worker looks for due deliveries |
| `concurrency` | `10` | Deliveries in flight per instance |
| `disableAfterFailures` | `5` | Failed deliveries in a row before the endpoint is turned off (`0`: never) |
| `keepDeliveriesDays` | `14` | Delivery log retention |
| `secretGraceHours` | `24` | How long the old secret keeps signing after a rotation |
| `notifyOwner` | `true` | Email the owner when an endpoint is turned off automatically |

| Variable | |
|---|---|
| `WEBHOOKS_WORKER` | `off` on instances that should not send deliveries (for example web servers when a separate worker process runs). Default `on`. |

## API

| Route | |
|---|---|
| `POST /api/webhooks` | Create `{ url, events, description?, scope? }`. Returns the secret, once. |
| `GET /api/webhooks` | Your endpoints |
| `GET /api/webhooks/:id` | One endpoint: status, last success, last error |
| `PATCH /api/webhooks/:id` | Change `url`, `events`, `description`, `enabled` |
| `DELETE /api/webhooks/:id` | Delete the endpoint and its delivery log |
| `POST /api/webhooks/:id/rotate-secret` | New secret, shown once |
| `POST /api/webhooks/:id/test` | Send a `webhook.test` event now and return the delivery |
| `GET /api/webhooks/:id/deliveries` | Recent deliveries (`?status=`, `?limit=` up to 100, default 50) |
| `POST /api/webhooks/:id/deliveries/:deliveryId/retry` | Send a delivery again now |

`test` and `retry` are rate limited (10 a minute per client), since they make your server send requests. A disabled endpoint answers `400` to both until it is turned back on.

From server code, `app.ext.webhooks` gives the `Webhook` and `Delivery` models, `drain()` (send everything that is due now, handy in tests) and `verifyWebhook`.

## Devtools, doctor and production

- The devtools **Webhooks** panel lists endpoints with their status, the latest deliveries with status codes, errors and next retries, and how many deliveries are pending.
- `calm doctor` reports how many endpoints exist and warns about endpoints that are failing right now, about `allowPrivate` in production, and about secrets stored without `CALM_ENCRYPTION_KEYS` in production.
- With several instances, every instance sends deliveries from the shared queue. Set `WEBHOOKS_WORKER=off` where it should not.
- Deliveries are not ordered: use `timestamp` (or fetch the record) when order matters.

## Testing

Test apps run the worker too, and local receivers are allowed in tests. Point an endpoint at a local server, then call `drain()` instead of waiting for the next poll:

```js
const t = await createTestApp({
  root: join(import.meta.dirname, '..'),
  config: { blocks: { webhooks: { retrySchedule: [20, 20] } } }, // retries in milliseconds
});

const alice = await t.signup();
await t.post('/webhooks', { url: `${receiverUrl}/hooks`, events: ['post.created'] }, alice);
await t.post('/posts', { title: 'Hi', body: '...' }, alice);
await t.idle();                     // event listeners have queued the deliveries
await t.app.ext.webhooks.drain();   // and they are sent
```

`receiverUrl` is a small `node:http` server your test starts on a random port. Check what it received with `verifyWebhook()` and the secret from the create response.

---

Source: https://docs.calmapi.dev/building-blocks

# Building your own block

A block is a folder in `app/blocks/<name>/` with an `index.js` that default-exports `definePlugin({ name, setup })`. Every official block is built this way, and so is anything you write for your own app: an event listener, a payment integration, a maintenance switch. Start inside a real project, where the block is live right away. Share it later with one command.

## A block in 15 lines

```js
// app/blocks/hello/index.js
import { definePlugin } from '#calm';

export default definePlugin({
  name: 'hello',
  options: { greeting: 'Hello' },
  setup(calm, options) {
    calm.routes((r) => {
      r.get('/hello', { policy: 'public', summary: 'Say hello' }, () => ({ message: `${options.greeting} from a block` }));
    });

    calm.on('post.created', ({ doc }) => calm.log.info(`New post: ${doc.title}`));
  },
});
```

Save it and `npm run dev` restarts: `GET /api/hello` answers `{ "data": { "message": "Hello from a block" } }`, and every new post is logged. Every folder in `app/blocks/` with an `index.js` is loaded at boot, in alphabetical order.

Change the settings of any block in `calm.config.js`, without touching its code:

```js
// calm.config.js
export default defineConfig({
  blocks: { hello: { greeting: 'Hi' } },
});
```

To start with every file in place, let the CLI write them:

```bash
npx calm make block hello
```

```text
✔ Created block hello
  + app/blocks/hello/index.js
  + app/blocks/hello/block.json
  + app/blocks/hello/README.md
  + test/blocks/hello.test.js
```

`index.js` lists every extension point in comments, `block.json` describes the block for sharing, and the test runs with `npm test`. Add `--no-test` to skip the test, `--force` to overwrite.

## definePlugin

| Key | |
|---|---|
| `name` | Required. Letters, digits, `-` and `_`, starting with a letter. Use the folder name: it is also the key in `calm.config.js` `blocks`. |
| `setup(calm, options)` | Required. Runs once at boot and may be async. |
| `options` | Settings with their defaults |
| `env` | The environment variables the block reads |

### Settings

`options` holds the defaults. At boot they are merged with `blocks.<name>` from `calm.config.js` and passed to `setup(calm, options)`; `calm.options` is the same object. Plain objects are merged key by key, and anything else (arrays, strings, functions) replaces the default.

```js
export default definePlugin({
  name: 'reports',
  options: { schedule: 'every 1h', recipients: [], format: { csv: true, pdf: false } },
  setup(calm, options) {
    // with blocks: { reports: { recipients: ['ops@example.com'], format: { pdf: true } } }
    // options = { schedule: 'every 1h', recipients: ['ops@example.com'], format: { csv: true, pdf: true } }
  },
});
```

Tests can pass other settings: `createTestApp({ config: { blocks: { reports: { schedule: 'every 1m' } } } })`.

Settings are for things that are the same on every machine. Secrets and per-environment values belong in environment variables.

### Environment variables

Declare what the block reads, then read it with `calm.env()`:

```js
// app/blocks/slack-notify/index.js
import { definePlugin } from '#calm';

export default definePlugin({
  name: 'slack-notify',
  env: {
    SLACK_WEBHOOK_URL: { required: 'production', secret: true, description: 'Incoming webhook URL from Slack' },
    SLACK_CHANNEL: 'Channel to post in (default: the webhook channel)',
  },
  setup(calm) {
    const url = calm.env('SLACK_WEBHOOK_URL');
    if (!url) return; // in development without the variable, the block stays quiet

    calm.on('post.updated', async ({ doc, previous }) => {
      if (doc.status !== 'published' || previous.status === 'published') return;
      await fetch(url, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ text: `New post: ${doc.title}`, channel: calm.env('SLACK_CHANNEL') }),
      });
    });
  },
});
```

| Spec | Meaning |
|---|---|
| `'Description'` | Optional, not secret |
| `required: true` | Needed everywhere |
| `required: 'production'` | Needed in production only |
| `secret: true` | The value is never shown in devtools |
| `description` | What it is and where to find it |

Names are `UPPER_SNAKE_CASE`. `calm.env(key, fallback)` returns the value, or `fallback` when it is unset or empty. Reading a variable the block did not declare throws, so the list stays complete.

What you get for declaring them:

- `calm doctor` and the devtools **Doctor** panel report missing ones: `env-SLACK_WEBHOOK_URL` is an error when the block needs it now (`required: true`, or `'production'` under production rules) and an info in development ("Needed in production").
- The devtools **Blocks** panel shows each variable as set or missing, with its description, and never the value of a secret one.

List them in `block.json` `envVars` too, so `calm add` appends them to `.env.example` and `.env` (see [Share it](#share-it)).

## When setup runs

`createApp()` loads `app/resources/*` and `app/blocks/*`, then runs each block's `setup()`, then compiles the resources, then sets up auth and builds the routes. So inside `setup()`:

- You can still change resource definitions (`calm.onResource`), which is why blocks can add fields.
- `calm.app.registry` is still empty and `calm.app.auth` is still `null`. Read them later: in route handlers, in the `calm.routes()` callback, in `calm.onService()`, `calm.onStart()` and event listeners.

```js
setup(calm) {
  const inbox = () => calm.app.registry.get('notification'); // read when needed, not now
  calm.routes((r) => {
    if (!calm.app.auth) return calm.log.warn('my-block needs auth'); // auth is ready here
    r.get('/inbox/count', { policy: 'authenticated' }, (ctx) => inbox().model.countDocuments({ user: ctx.user._id }));
  });
}
```

## Extension points

`setup(calm)` receives the plugin API:

| Member | Use |
|---|---|
| `calm.app`, `calm.config`, `calm.log`, `calm.events`, `calm.mongoose`, `calm.mailer`, `calm.push` | The app and its parts |
| `calm.name`, `calm.options`, `calm.env(key, fallback)` | The block's name, its [settings](#settings) and its [environment variables](#environment-variables) |
| `calm.on(pattern, fn)` | Listen to events: `'post.created'`, `'post.*'`, `'*'`. `fn(payload, name)`. Resource events carry `{ doc, previous?, resource, user }`. |
| `calm.onResource((def) => def)` | Change resource definitions before they compile: add fields, read your own resource options |
| `calm.onService(({ def, model, service }) => {})` | Runs for every resource once services exist: wrap or add methods |
| `calm.routes((r) => {...}, { prefix })` | Add routes under `/api` with the [route builder](/routes) |
| `calm.use(middleware)` | Express middleware in front of the whole app, for paths outside `/api` (like `/docs` or `/mcp`) |
| `calm.authenticate(fn)` | Accept your own credentials in `Authorization: Bearer` ([below](#credentials)) |
| `calm.guard(fn, { order })` | Run before every route's policy and stop or answer the request ([below](#guards)) |
| `calm.policy(name, fn)` | A named policy, usable in policy strings like `'member \| admin'` ([below](#named-policies)) |
| `calm.loginChallenge(fn)` | Take part in sign-in, for a second factor ([below](#the-auth-service)) |
| `calm.provide(key, value)` | Expose an API to the rest of the app as `app.ext[key]` |
| `calm.doctor(fn)` | Add checks to `calm doctor` and the devtools Doctor panel ([below](#doctor-checks)) |
| `calm.devtools.panel(name, fn)` | A devtools panel that renders the JSON `fn(app)` returns |
| `calm.onStart(fn)`, `calm.onShutdown(fn)` | Start and stop workers and timers. Shutdown hooks run in reverse order. |
| `calm.push.use(transport)`, `calm.mailer.use(transport)` | Deliver [push notifications](/push-notifications#your-own-transport) or email |

The devtools **Blocks** panel shows, for every block, which of these it uses: guards, authenticators, policies, events it listens to, transports, what it provides, its panels and its routes.

### Routes

Block routes use the same [route builder](/routes) as your app, with a policy on every route (`calm doctor` warns when one is missing). They are not resource routes, so there is no `ctx.service`, no `ctx.doc` and no automatic serialization: use `ctx.services.<name>` and `ctx.serialize(doc, '<name>')`.

Two route options exist mostly for blocks:

```js
r.post('/reports/export', { policy: 'admin', scope: 'reports:export', meta: { audit: true } }, exportReports);
```

- `scope` names a permission for credentials that carry scopes. The [api-keys](/blocks/api-keys) block only lets keys with `reports:export` (or `*`, or `reports:*`) call this route.
- `meta` is anything you want to read in a guard: `route.meta.audit`.

Resource options are open too: a block reads its own option from `def.options` (`softDelete: true`, `webhooks: false`, `onOwnerDelete: 'anonymize'`):

```js
// import { definePlugin, f } from '#calm';
calm.onResource((def) => {
  if (!def.options.searchIndex) return def;
  def.fields.searchText = f.text().hidden();
  return def;
});
```

### Credentials

`calm.authenticate(fn)` accepts another kind of token in `Authorization: Bearer <token>`: API keys, service tokens, tokens from another identity provider. `fn(token, req)` runs for every bearer token, before sessions are looked up:

```js
import { definePlugin, hashToken, unauthorized } from '#calm';

calm.authenticate(async (token, req) => {
  if (!token.startsWith('svc_')) return null; // not ours: the next authenticator, or a session
  const entry = await ServiceToken.findOne({ hash: hashToken(token) }).lean();
  if (!entry) throw unauthorized('Unknown service token');
  const user = await calm.app.model('user').findById(entry.user).lean();
  return { user, via: 'service-token', scopes: entry.scopes, id: String(entry._id) };
});
```

- Return `null` quickly for tokens that are not yours. The first authenticator that returns an object wins.
- Throw to refuse: the error is the response.
- Return `{ user, via, scopes, id }`. `user` is a user record. Users that are disabled or being deleted are refused with `401`.

Every route then sees how the request signed in, in `ctx.auth`:

| Request | `ctx.auth` |
|---|---|
| Your authenticator | `{ via: 'service-token', scopes: [...], id }` (`via` defaults to `'token'`, `scopes` to `['*']`) |
| A session | `{ via: 'session', scopes: ['*'], id: '<session id>' }` |
| No credential | `null` |

Scopes are only data. Enforce them in a [guard](#guards), for example against `route.scope`, the way the api-keys block does.

### Guards

`calm.guard(fn, { order })` runs `fn(ctx, route)` before every route: auth routes, block routes, your routes and every CRUD route. It runs after authentication and JSON parsing, before route middleware (such as an upload parser) and before the policy check. (On routes with middleware, a quick check that turns away signed-out callers when the policy needs a user comes first.)

```js
// app/blocks/maintenance/index.js
import { definePlugin, CalmError } from '#calm';

export default definePlugin({
  name: 'maintenance',
  env: { MAINTENANCE: 'Set to "on" to answer 503 on every write' },
  setup(calm) {
    calm.guard((ctx, route) => {
      if (calm.env('MAINTENANCE') !== 'on' || route.method === 'GET') return;
      if (ctx.user?.roles?.includes('admin')) return;
      throw new CalmError(503, 'MAINTENANCE', 'We are updating the app. Try again in a few minutes.');
    });
  },
});
```

A guard lets the request through by returning nothing. It stops it in one of three ways:

| Stop with | Response |
|---|---|
| `throw` an error (`forbidden()`, `tooManyRequests()`, `new CalmError(...)`) | The usual [error response](/errors) |
| `return ctx.reply(data, { status, headers })` | `{ data }` with that status (default `200`) |
| Send the response yourself (`ctx.res...end()`) | Whatever you sent. The [idempotency](/blocks/idempotency) block replays a stored response this way. |

What a guard puts on `ctx` stays there for the handler: the [feature-flags](/blocks/feature-flags) block adds `ctx.flags`, the [notifications](/blocks/notifications) block adds `ctx.notify`.

`route` describes the matched route: `method`, `path` (without `/api`), `policy` (the parsed tokens), `scope`, `meta`, `resource`, `action` and `source` (`'crud'`, `'auth'`, `'block:<name>'`...). `ctx` is the route context: `user`, `auth`, `req`, `res`, `params`, `query`, `body` (not validated yet), `services`, `app`.

Guards run in `order`, lowest first (default `0`). The idempotency block uses `order: 100` so it runs after the others, and a request another guard refuses is never stored. Guards do not run for `calm.use()` middleware, health checks or devtools.

### Named policies

`calm.policy(name, fn)` adds a policy that reads like a built-in one:

```js
// app/blocks/orgs/index.js
export const member = async ({ user, req }) =>
  Boolean(user && (await Membership.exists({ user: user._id, org: req?.params.orgId })));

export default definePlugin({
  name: 'orgs',
  setup(calm) {
    calm.policy('member', member);
    calm.routes((r) => {
      r.get('/orgs/:orgId/report', { policy: 'member | admin' }, orgReport);
    });
  },
});
```

The function receives `{ user, action, doc, req }` (`doc` on routes with `:id`) and returns `true` or `false`, or a promise of it. Names are letters, digits, `-` and `_`, and cannot replace a built-in (`public`, `authenticated`, `owner`, `none` and their aliases). `calm routes` and devtools show the name.

Named policies work everywhere a policy does: routes, field rules (`visibleTo`, `writableBy`) and resource files. Resource files load before blocks run `setup()`, so calm resolves the names once every block is set up:

```js
export default resource('project', {
  fields: { ... },
  policy: { list: 'member | admin', read: 'member | admin', create: 'member | admin', update: 'admin', delete: 'admin' },
});
```

Importing the function (`policy: { list: [member, 'admin'] }`) works too, and also on older cores.

### Sharing an API

`calm.provide(key, value)` puts anything on `app.ext`, for routes, services, jobs and other blocks:

```js
calm.provide('slack', { post: (text) => postToSlack(text) });

// anywhere else
await ctx.app.ext.slack.post('Deploy finished');
```

Official blocks share this way: `app.ext.notify`, `app.ext.flags`, `app.ext.webhooks`, `app.ext.apiKeys`, `app.ext.jobs`.

### Doctor checks

`calm.doctor(fn)` adds findings to `calm doctor` and the devtools Doctor panel. `fn(app)` returns an array of `{ level, id, title, detail?, file? }`, with `level` `error`, `warn` or `info`:

```js
calm.doctor((app) =>
  app.config.mode === 'production' && calm.options.recipients.length === 0
    ? [{ level: 'warn', id: 'reports-no-recipients', title: 'Reports have no recipients', detail: 'Set blocks.reports.recipients in calm.config.js.' }]
    : [],
);
```

Checks return an array or a promise of one. `calm doctor` boots the app without connecting to MongoDB, so a check that queries the database should skip when `calm.mongoose.connection.readyState !== 1` (devtools runs checks against the connected app). Refreshing numbers in the background and reporting the last value also works, as the [webhooks](/blocks/webhooks) and [api-keys](/blocks/api-keys) blocks do. A check that throws is reported as `doctor-hook` ("A block doctor check crashed").

Missing environment variables need no check of their own: [declare them](#environment-variables).

### Reading records outside a request

Work that runs outside a request (webhooks, realtime streams, notifications, exports) still has to respect who may see what. `app.canRead()` applies the rules of `GET /api/<resource>/:id`: the read policy, owner scoping and the service `scope()`.

```js
const viewer = { ...userRecord, id: String(userRecord._id) }; // shaped like ctx.user

await calm.app.canRead('post', doc, viewer);                    // may this user read this post?
await calm.app.canRead('post', doc, viewer, { deleted: true }); // a deleted record, judged on your copy
await calm.app.inScope('post', doc, viewer);                    // only the service scope(), not the read policy
```

`doc` is the stored record (for example the `doc` of a `post.updated` event). For a deleted record, pass `{ deleted: true }`: it is judged on the copy you hold, and a `scope()` too complex to check without the database refuses it. Then serialize it for that user with `serialize(def, doc, { user, registry })` from `#calm` (or `ctx.serialize()` inside a request), so hidden and `visibleTo()` fields stay out. The [realtime-sse](/blocks/realtime-sse) and [webhooks](/blocks/webhooks) blocks work this way.

### The auth service

Sign-in blocks (magic links, passkeys, one-time codes) use the same helpers as password sign-in, so lockout, disabled accounts and second factors behave the same way everywhere. They live on `calm.app.auth.service`, which is ready once the routes are built (and `null` when auth is off).

| Helper | Does |
|---|---|
| `completeLogin(user, ctx)` | After the user proved who they are: runs the login challenges (a second factor), then creates the session. Resolves to `{ user, token, expiresAt }`, or to the challenge. |
| `finishLogin(user, req)` | Creates the session without challenges, once a second factor checked out |
| `lockedUntil(email)` | The date until which sign-in for this email is locked, or `null` |
| `recordFailure(email, req, reason)` | Counts a failed attempt (`security.login_failed`) and locks the email after `auth.lockout.maxAttempts` |
| `clearFailures(email)` | Resets the count after a success |
| `inactive(user)` | `true` for accounts that are `disabled` or being deleted: they cannot sign in or use a session |

```js
// A sign-in route for one-time codes
r.post('/auth/code/verify', { policy: 'public', rateLimit: 'auth', input: { email: f.email().required(), code: f.string().required() } }, async (ctx) => {
  const auth = calm.app.auth.service;
  const { email, code } = ctx.body;
  if (await auth.lockedUntil(email)) throw tooManyRequests('Too many failed sign-in attempts. Try again later.');

  const user = await calm.app.model('user').findOne({ email }).lean();
  if (!user || !(await codeMatches(user, code))) {
    await auth.recordFailure(email, ctx.req, 'wrong_code');
    throw unauthorized('Invalid code');
  }
  await auth.clearFailures(email);
  if (auth.inactive(user)) throw forbidden('This account is disabled');
  return auth.completeLogin(user, ctx);
});
```

To add a second factor instead, use `calm.loginChallenge(async (user, ctx) => answer)`. It runs inside `completeLogin`, after the user proved who they are and before a session exists. Return an object (such as `{ mfaRequired: true, mfaToken }`) to answer the sign-in with it, or `null` to continue. Once the second factor checks out, call `finishLogin(user, req)`. The [totp](/blocks/totp#how-it-hooks-into-login) block works this way, and so every sign-in block gets two-factor authentication for free.

### What to import

Blocks import only from `#calm`, the public surface of the framework. Files under `#calm/...` are internals that can change between versions, and `calm block check` points such imports out.

| Export | Use |
|---|---|
| `definePlugin` | Declare the block |
| `resource`, `f`, `Field`, `ResourceService` | Resources, fields and services |
| `serialize`, `validateInput`, `standardSchema`, `resourceJSONSchema` | Apply a resource's output and input rules, or describe it as JSON Schema |
| `evaluatePolicy`, `parsePolicy`, `hasRole`, `isOwner`, `matchesFilter` | Policies, and checking a record against a MongoDB filter in memory |
| `createToken`, `hashToken` | Random tokens with a prefix, and their SHA-256 for storage |
| `hashPassword`, `verifyPassword` | scrypt helpers |
| `isEncrypted` | Whether a stored value is ciphertext from `.encrypted()` |
| `maskToken`, `providerPayloads` | Push helpers: a masked token for logs, the payload each provider receives |
| `Reply`, `currentRequest` | What `ctx.reply()` returns; the current request from anywhere |
| `createApp`, `defineConfig` | Build an app in a script |
| `CalmError`, `badRequest`, `unauthorized`, `forbidden`, `notFound`, `conflict`, `validationError`, `tooManyRequests` | [Errors](/errors) |

Tests are the exception: they import `createTestApp` from `#calm/testing.js`.

## Test it

`calm make block` writes a test next to your others:

```js
// test/blocks/hello.test.js
import { test, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'node:path';
import { createTestApp } from '#calm/testing.js';

let t;
before(async () => {
  t = await createTestApp({ root: join(import.meta.dirname, '..', '..'), config: { blocks: { hello: { greeting: 'Hi' } } } });
});
after(() => t.close());

test('hello says hi', async () => {
  const res = await t.get('/hello');
  assert.equal(res.status, 200);
  assert.equal(res.body.data.message, 'Hi from a block');
});
```

Events, emails and push notifications are captured too: `await t.idle()` waits for event listeners, then check `t.mails` and `t.pushes`. See [Testing](/testing).

## Share it

### block.json

`block.json` sits next to `index.js` and describes the block for other people. `calm make block` writes one:

```json
{
  "name": "slack-notify",
  "title": "Slack notifications",
  "description": "Post to a Slack channel when a post is published.",
  "version": "1.0.0",
  "minVersion": "2.0.0-alpha.1",
  "author": "Acme",
  "license": "MIT",
  "categories": ["notifications"],
  "envVars": { "SLACK_WEBHOOK_URL": "" },
  "dependencies": [],
  "files": [],
  "docs": "Set SLACK_WEBHOOK_URL to an incoming webhook URL (Slack, Apps, Incoming Webhooks)."
}
```

| Field | |
|---|---|
| `name`, `title`, `description`, `version` | Who it is. `version` is semver; raise it when you change the block. |
| `minVersion` | The oldest CalmAPI (`calm/` in the project) the block works with |
| `author`, `license`, `homepage`, `categories` | Shown to people choosing a block |
| `envVars` | Appended to `.env.example` and `.env` on install. Use empty values or harmless placeholders, never real secrets. |
| `dependencies`, `devDependencies` | npm packages with a range: `"stripe@^18.0.0"` |
| `registryDependencies` | Other blocks installed first: `"jobs"`, `"gh:acme/blocks/base"` |
| `conflicts` | Blocks that cannot be installed together with this one |
| `files` | Extra files or folders outside `app/blocks/<name>/` to ship: `"app/jobs/digest.js"`, `"app/resources/invoice"` |
| `docs` | Printed right after installing: what to set, what to call |

Everything in `app/blocks/<name>/` is shipped, except `block.json` itself and a `docs.md`.

### calm block check

```bash
npx calm block check slack-notify
```

```text
  slack-notify v1.0.0 · 2 file(s)
  ok    nothing to fix

  What the code does
  - makes network requests app/blocks/slack-notify/index.js:15
  - reads SLACK_WEBHOOK_URL app/blocks/slack-notify/index.js
```

It checks what makes a block safe and pleasant to install, as errors, warnings and notes:

- a valid name and semver `version` and `minVersion`, a description and docs, and an `index.js` that exports `definePlugin()`;
- file targets that stay in the project and never touch `calm/`, `calm.lock`, `.env` or `package.json`;
- dependencies with a version range, and every `envVars` entry used and declared in `definePlugin({ env })`;
- what looks like a committed secret key (an error), imports of `#calm/...` internals, very large files;
- the same review of what the code does that people see before installing it (below).

With no name it checks every block that has a `block.json`. It also takes an address (`calm block check gh:acme/blocks/slack-notify`, a URL or a `.json` file), to look at someone else's block before adding it. The exit code is `1` when there are errors, so it fits in CI.

### calm block pack

```bash
npx calm block pack
```

```text
✔ Packed slack-notify into r/

  Share it
  Commit r/ and push to GitHub, then anyone can run:
    npx calm add gh:<you>/<repo>/slack-notify
  Or host r/ anywhere: npx calm add https://<host>/r/<name>.json
```

`pack` writes one [registry item](/publishing-blocks#the-registry-item) per block to `r/<name>.json`, plus `r/index.json` listing every item in the folder. A block with errors is not packed. Give names to pack only some, and `--out <dir>` to write elsewhere.

### Installing from GitHub

Commit `r/` and push. Anyone can then install the block straight from the repository:

```bash
npx calm add gh:acme/blocks/slack-notify          # the default branch
npx calm add gh:acme/blocks/slack-notify@v1.2.0   # a tag, a branch or a commit
```

`gh:<user>/<repo>/<name>[@ref]` reads `r/<name>.json` from that repository on GitHub. Any static host works too (`npx calm add https://blocks.acme.dev/r/slack-notify.json`), and so does a [registry of your own](/publishing-blocks#your-own-registry) with short names like `@acme/slack-notify`.

### What people see before installing

A block runs inside the app with full access, like any code you paste. So before a block that is not an official one is installed, `calm add` says in plain language what its code does:

```text
  Review gh:acme/blocks/slack-notify is not an official block: read it before you trust it
  - makes network requests app/blocks/slack-notify/index.js:15
  - reads SLACK_WEBHOOK_URL app/blocks/slack-notify/index.js

? Apply these changes? [Y/n]
```

| Marked | Finding |
|---|---|
| `!` | Runs other programs (`child_process`), evaluates code built at runtime (`eval`, `new Function`), uses `node:vm`, imports from a computed path, loads native code, or has minified lines that cannot be reviewed |
| `-` | Makes network requests, writes or deletes files, opens a port, sees every request (`calm.use`, `calm.guard`, `calm.authenticate`), takes part in sign-in, the environment variables it reads, the hosts it mentions |

When something is marked `!`, the question becomes "This block has code worth reading (marked !). Add it anyway?". With `--yes` (no question asked, for scripts and CI), such a block is refused unless you also pass `--trust`, after reading it:

```bash
npx calm add gh:acme/blocks/slack-notify --dry-run      # the plan and the review, nothing written
npx calm add gh:acme/blocks/slack-notify --yes --trust  # non-interactive, risky code accepted
```

### minVersion

`minVersion` protects people whose `calm/` is older than what your block needs. `calm add` compares it with the CalmAPI version recorded in `calm.lock` and stops with "needs CalmAPI 2.0.0-alpha.2 or newer in calm/ (yours is 2.0.0-alpha.1). Run `calm upgrade` first." Set it to the version you built and tested against; `calm make block` fills in your current one.

### calm block list

```bash
npx calm block list
```

```text
  hello                0.1.0    written here
  jobs                 1.0.1    @calmapi (bundled)
  slack-notify         1.0.0    gh:acme/blocks/slack-notify
                       1 file(s) changed since added: app/blocks/slack-notify/index.js
```

Every block in the project with its version, where it came from, and the files you changed since adding it. The devtools **Blocks** panel shows the same, plus what each block hooks into, its environment variables, its settings and its routes.

## Good blocks

- Keep them small and readable: the people who add your block own its code.
- Put secrets in declared environment variables, and everything else in `options`.
- Go through services (`ctx.services`, `calm.app.service(name)`) and `serialize()`, or `app.canRead()` outside requests, so policies and visibility rules keep applying.
- Give every route an explicit policy, and use the auth service helpers for anything that signs people in.
- Fail loudly at boot for invalid settings, and add doctor checks for what is missing in production.
- Write a test, run `calm block check`, and raise `version` when you change something.
- Pin versions of anything you load from a CDN, and of npm dependencies.

The official blocks are built the same way, from `registry/blocks/<name>/` in the [calmapi repository](https://github.com/sunilksamanta/calmapi). Read them for examples of every extension point.

---

Source: https://docs.calmapi.dev/publishing-blocks

# Publishing your own block

A shared block is one JSON file in the [shadcn registry-item format](https://ui.shadcn.com/docs/registry): the block's files plus a little metadata. Anyone can host one, and `calm add` installs it like an official block. This page is the reference for that file and for hosting it. To write a block, start with [Building your own block](/building-blocks).

The short version:

```bash
npx calm make block slack-notify      # app/blocks/slack-notify/ with block.json
npx calm block check slack-notify     # fix what it reports
npx calm block pack                   # writes r/slack-notify.json and r/index.json
git add r && git commit -m "Share slack-notify" && git push
# anyone can now run: npx calm add gh:<you>/<repo>/slack-notify
```

## The registry item

`calm block pack` writes this file from your block folder and its `block.json`. You rarely write it by hand, but it is plain JSON, so you can:

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "slack-notify",
  "type": "registry:item",
  "title": "Slack notifications",
  "description": "Post to a Slack channel when a post is published.",
  "version": "1.0.0",
  "author": "Acme",
  "license": "MIT",
  "categories": ["notifications"],
  "dependencies": [],
  "devDependencies": [],
  "registryDependencies": [],
  "envVars": { "SLACK_WEBHOOK_URL": "" },
  "docs": "Set SLACK_WEBHOOK_URL to an incoming webhook URL (Slack, Apps, Incoming Webhooks).",
  "meta": { "calmapi": { "minVersion": "2.0.0-alpha.1", "conflicts": [] } },
  "files": [
    {
      "path": "app/blocks/slack-notify/index.js",
      "type": "registry:file",
      "target": "app/blocks/slack-notify/index.js",
      "content": "import { definePlugin } from '#calm';\n..."
    }
  ]
}
```

| Field | Used by `calm add` for |
|---|---|
| `name`, `files` | Required. Each file needs `content` and a `target` (or `path`): where it goes in the project. |
| `version`, `description` | Shown in the plan and recorded in `calm.lock` |
| `dependencies`, `devDependencies` | npm packages as `"name@range"` (`"stripe@^18.0.0"`), added to `package.json` when missing, then installed |
| `envVars` | Appended to `.env.example` and `.env` when missing; values already there are kept |
| `registryDependencies` | Other blocks installed first (`"jobs"`, `"@acme/base"`, `"gh:acme/blocks/base"`, a URL) |
| `docs` | Printed after installing |
| `meta.calmapi.minVersion` | `calm add` refuses the block when the project's `calm/` is older (see [minVersion](/building-blocks#minversion)) |
| `meta.calmapi.conflicts` | Names of blocks that cannot be installed together with this one |

Targets must stay inside the project: absolute paths, `..` segments, `calm/` and `calm.lock` are refused at install time, and `calm block check` also refuses `.env`, `package.json` and `package-lock.json` (use `envVars` and `dependencies` instead).

`calm block pack` also writes `r/index.json`, which lists every item in the folder with its title, description, version and categories, in the shadcn registry format.

## Where blocks can live

| Address | Reads |
|---|---|
| `gh:acme/blocks/slack-notify` | `r/slack-notify.json` on the default branch of `github.com/acme/blocks` |
| `gh:acme/blocks/slack-notify@v1.2.0` | The same file at a tag, a branch or a commit |
| `https://blocks.acme.dev/r/slack-notify.json` | Any URL |
| `./blocks/slack-notify.json` | A local file |
| `@acme/slack-notify` | A registry of your own (below) |

Serve the JSON from any static host, one file per block: GitHub, a CDN, an S3 bucket, your docs site.

## Your own registry

A registry is a URL template. Users declare yours once in their `package.json`, with `{name}` as the placeholder:

```json
{
  "calm": {
    "registries": { "@acme": "https://blocks.acme.dev/r/{name}.json" }
  }
}
```

```bash
npx calm add @acme/slack-notify --dry-run
npx calm add @acme/slack-notify
```

This also works for private blocks inside a company: host `r/` behind your VPN, and every project that declares the registry can add blocks by name.

## What installers see

Blocks that do not come from the official registry get a plain-language review before anything is written: network requests, file writes, child processes, `eval`, computed imports, request hooks, the environment variables the code reads and the hosts it mentions. Risky findings must be confirmed, and with `--yes` they need `--trust`. See [What people see before installing](/building-blocks#what-people-see-before-installing). Run `calm block check` on your own block to see the same review first.

## The official registry

The official blocks are built the same way, from `registry/blocks/<name>/` in the [calmapi repository](https://github.com/sunilksamanta/calmapi) (a `block.json`, a `files/` folder mirrored into the project, and a `docs.md`). They are bundled with the CLI, so `calm add jobs` works offline, and served at `https://docs.calmapi.dev/r/<name>.json` for `calm add --remote` and other tools. The list is at [/r/index.json](/r/index.json).

---

Source: https://docs.calmapi.dev/deployment

# Deployment

A CalmAPI app is a regular Node.js server: `npm start` runs `node server.js`. It needs Node.js 22.12 or newer (24 LTS recommended) and a MongoDB server.

```bash
NODE_ENV=production \
APP_URL=https://api.example.com \
MONGODB_URI='mongodb+srv://user:pass@cluster.example.mongodb.net/my_api' \
CORS_ORIGINS=https://app.example.com \
TRUST_PROXY=1 \
npm start
```

Before deploying, run the checks with production rules, and the authorization audit (it needs a MongoDB server for its throwaway database):

```bash
npx calm doctor --prod --audit --ci
npx calm audit --ci
```

## Production defaults

`npm start` runs in **production mode** unless `NODE_ENV` says otherwise, so a forgotten variable never exposes development behavior. In production:

- the app refuses to start without `MONGODB_URI` and `APP_URL`;
- devtools are off and cannot be enabled;
- CORS allows no browser origin until you set `CORS_ORIGINS`;
- logs are JSON, one object per line, each with the request id;
- `Strict-Transport-Security` is sent, along with the other security headers;
- `500` responses never contain error details.

Staging and preview environments are production too: anything other than `development` or `test` gets production rules (see [Configuration](/configuration#mode)).

## Environment

| Variable | Required | Notes |
|---|---|---|
| `NODE_ENV` | | Defaults to `production` |
| `MONGODB_URI` | yes | |
| `APP_URL` | yes | Public URL of the API; used in password reset links and OpenAPI |
| `PORT` | | Default `5001` |
| `HOST` | | Default: all interfaces |
| `CORS_ORIGINS` | for browsers | Comma separated frontend origins |
| `TRUST_PROXY` | behind a proxy | Usually `1`; see below |
| `LOG_LEVEL` | | Default `info` |
| `CALM_ENCRYPTION_KEYS` | with `.encrypted()` fields | The same keys as wherever else this database is read; see [Encryption at rest](/security#encryption-at-rest) |

Plus the variables of your blocks (`RESEND_API_KEY`, `S3_BUCKET`, `JOBS_WORKER`...). Install production dependencies only: the CLI and devtools are dev dependencies and are not needed to run the app.

```bash
npm ci --omit=dev
```

Do not deploy `.env`; set real environment variables. (If a `.env` file is present, it is loaded; variables already set in the environment win.)

## Health checks

| Endpoint | Answers |
|---|---|
| `GET /health/live` | `200 { "status": "ok" }` while the process runs. Use it for liveness. |
| `GET /health/ready` | `200 { "status": "ok", "database": "up" }` when MongoDB answers a ping, else `503 { "status": "unavailable", "database": "down" }`. Use it for readiness and load balancer checks. |

Both are outside `/api`, so they are not rate limited.

## Startup and shutdown

At startup the app connects to MongoDB (5 attempts with exponential backoff), builds the indexes your fields declare, runs block start hooks (for example the jobs worker), then listens.

On `SIGTERM` or `SIGINT` it shuts down gracefully:

1. Stop accepting connections and close idle keep-alive connections.
2. Run block shutdown hooks in reverse order: the jobs worker stops claiming and waits for running jobs, realtime streams are closed. In-flight requests keep running meanwhile.
3. Wait for in-flight requests. Connections still open after `shutdownTimeoutMs` (10 seconds) are closed.
4. Wait for background tasks and event listeners, disconnect from MongoDB and exit.

Give your platform's stop timeout a little more than `shutdownTimeoutMs`.

## Behind a proxy or load balancer

Set `TRUST_PROXY` so Express takes the client IP from `X-Forwarded-For`. Without it, every client appears to come from the proxy and shares one rate limit. Use the number of proxies in front of the app (`1` for a single load balancer), or `true` only if every request certainly passes through a proxy you trust. `calm doctor --prod` reminds you.

TLS terminates at the proxy; the app speaks plain HTTP behind it.

## Docker

New projects include this `Dockerfile` and a `.dockerignore` that leaves out `node_modules`, `.env`, `.git` and tests:

```dockerfile
# Production image. Build: docker build -t my-api .
FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY . .
USER node
EXPOSE 5001
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s \
  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 5001) + '/health/ready').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
CMD ["node", "server.js"]
```

```bash
docker build -t my-api .
docker run -p 5001:5001 \
  -e APP_URL=https://api.example.com \
  -e MONGODB_URI='mongodb+srv://...' \
  -e CORS_ORIGINS=https://app.example.com \
  -e TRUST_PROXY=1 \
  my-api
```

The container runs as the unprivileged `node` user, so if you use [storage-local](/blocks/storage-local), mount a volume for `UPLOAD_DIR` that this user can write to.

For local testing with a database next to it:

```yaml
# compose.yaml
services:
  api:
    build: .
    ports: ['5001:5001']
    environment:
      APP_URL: http://localhost:5001
      MONGODB_URI: mongodb://mongo:27017/my_api
    depends_on: [mongo]
  mongo:
    image: mongo:8
    volumes: [mongo-data:/data/db]
volumes:
  mongo-data:
```

## Email

Password reset emails need a transport in production. Add [mail-resend](/blocks/mail-resend) or [mail-smtp](/blocks/mail-smtp). Without one, emails are not sent, an error is logged, and `calm doctor --prod` warns.

## Running several instances

Sessions live in MongoDB, so any instance can serve any user. A few things are per process by default:

| Concern | Default | With several instances |
|---|---|---|
| Rate limits | counted in memory | add [rate-limit-mongo](/blocks/rate-limit-mongo) |
| Background jobs | every instance runs a worker | fine (jobs are claimed atomically); or set `JOBS_WORKER=off` on web instances and run dedicated workers |
| Uploads | [storage-local](/blocks/storage-local) writes to local disk | use [storage-s3](/blocks/storage-s3) |
| Realtime events | in-process | subscribers only see changes from their instance; see [realtime-sse](/blocks/realtime-sse#several-instances) |
| Event listeners | in-process | they run on the instance that made the change, which is usually what you want |

## Checklist

- `NODE_ENV=production`, `APP_URL`, `MONGODB_URI` and `CORS_ORIGINS` are set.
- `TRUST_PROXY` matches your proxy setup.
- A mail block is configured.
- `npx calm doctor --prod --audit --ci`, `npx calm audit --ci` and `npm test` pass.
- `CALM_ENCRYPTION_KEYS` is set if you use `.encrypted()` fields, and the keys are backed up in your secret store.
- The readiness probe uses `/health/ready`, and the stop timeout is above 10 seconds.
- MongoDB has backups, and the app's database user only has access to its own database.

---

Source: https://docs.calmapi.dev/security

# Security

## Reporting a vulnerability

Please report vulnerabilities **privately** through GitHub: open the [calmapi repository](https://github.com/sunilksamanta/calmapi), go to the **Security** tab and choose **Report a vulnerability**. Do not open a public issue. You will get an answer within a few days.

Include the CalmAPI version (`calm.lock`, or `npx calm --version`), what an attacker can do, and the smallest reproduction you can share.

## Supported versions

| Version | Status |
|---|---|
| 2.x | Supported |
| 1.x (0.x on npm) | Security advisories only. Please [migrate](/migrate-v1). |

## Advisories for code in your project

CalmAPI copies its code into your project, so `npm audit` cannot see problems in it. Instead, CalmAPI publishes advisories with a pattern that identifies affected code, and `calm doctor` matches them against your files:

```bash
npx calm doctor            # inside a CalmAPI 2 project
npx calmapi@next doctor    # inside a CalmAPI 1.x project
```

Each finding names the advisory and the fix. Fixes for framework files reach your project through [`calm upgrade`](/upgrading), which merges them into your copy without discarding your edits. Published advisories are listed on [Security advisories](/security-advisories).

## Secure by default

| Area | Default |
|---|---|
| Mode | Anything but `NODE_ENV=development` or `test` runs as production; production requires `APP_URL` and never runs devtools |
| Access | Every route has a policy; missing ones default to `authenticated` and are reported by doctor |
| Private ids | Records a user cannot read answer `404`, not `403`, so their ids are not confirmed |
| Input | Unknown, hidden and read-only fields are rejected (`422`); no silent type coercion |
| Request bodies | At most 1 MB, 20 levels deep and 10,000 values (see [JSON guard](#json-guard)) |
| Output | Hidden and write-only fields never leave the server, including through `?include=`; raw records returned from resource routes are serialized |
| Queries | Only declared filters, sorts and search fields; flat query parsing, so no operator injection; search input escaped |
| Sessions | Random opaque tokens, stored as SHA-256 hashes, bearer header only, revocable, expire automatically |
| Passwords | scrypt (`node:crypto`) with OWASP parameters, upgraded on login when you raise the cost; common passwords and passwords containing the user's email or name are refused |
| Sign-in | Rate limited per IP, and locked per account after 5 failed attempts (see [Authentication](/authentication#account-lockout)) |
| Password reset | Single-use hashed tokens, short expiry, same answer for unknown emails, all sessions revoked on use |
| Rate limits | Every `/api` route, with stricter limits on auth routes |
| Errors | Internal messages and stack traces never reach clients in production |
| Headers | `nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, a restrictive CSP, CORP/COOP, HSTS in production; `X-Powered-By` removed |
| CORS | No browser origin allowed in production until you list them |
| Data at rest | Fields marked `.encrypted()` are stored as AES-256-GCM ciphertext (see [Encryption at rest](#encryption-at-rest)) |
| Uploads (blocks) | Type and size allowlists, content checks, random names, sandboxed downloads |
| Devtools | Development only, loopback only, `Host` checked, writes need a custom header (see [Devtools](/devtools#safety-model)) |
| Dependencies | Two runtime dependencies: `express` and `mongoose` |

## Encryption at rest

Mark a field `.encrypted()` and CalmAPI encrypts it with AES-256-GCM before it reaches MongoDB. It is decrypted when read through the model. A database dump, a backup or a copied replica only holds ciphertext. Your API, services, hooks and `?include=` all see the plain value, so nothing else changes.

```js
// app/resources/patient/patient.resource.js
import { resource, f } from '#calm';

export default resource('patient', {
  fields: {
    name: f.string().required().searchable(),
    nationalId: f.string().required().encrypted().visibleTo('owner | admin'),
    diagnosis: f.text().encrypted().visibleTo('owner | admin'),
    owner: f.ref('user').owner(),
  },
  policy: { list: 'owner | admin', read: 'owner | admin', create: 'authenticated', update: 'owner | admin', delete: 'admin' },
});
```

MongoDB stores a string like this, where every part after the key id is base64url:

```text
enc:v1:k1:<iv>:<tag>:<ciphertext>
```

The value is encrypted as JSON, so numbers, dates and arrays work as well as strings (a date comes back from the database as its ISO string). Encryption hides the value from the database, not from the API: combine it with `.visibleTo()` or `.hidden()` to decide who reads it.

Ciphertext cannot be queried. An encrypted field cannot also be `.filterable()`, `.sortable()`, `.searchable()`, `.unique()`, `.index()` or `.owner()`, and `f.ref()` and `f.id()` fields cannot be encrypted. Declaring one of these throws at boot:

```text
resource('patient'): "nationalId" is .encrypted() and cannot also be filterable (ciphertext cannot be queried)
```

### Keys

Keys come from the `CALM_ENCRYPTION_KEYS` environment variable: a comma separated list of `<id>:<key>` entries, where each key is 32 random bytes in base64. Generate one with `calm keygen`:

```bash
npx calm keygen            # print a new key line
npx calm keygen --write    # add it to .env
```

```text
CALM_ENCRYPTION_KEYS=k1:<32 random bytes, base64>

• Add this line to .env (and to your production secrets). Never commit it.
```

An app with `.encrypted()` fields refuses to start without keys:

```text
patient: fields nationalId, diagnosis are .encrypted() but CALM_ENCRYPTION_KEYS is not set. Run `npx calm keygen` and add the line to .env.
```

Set the same keys in every environment that reads the same database. Data encrypted with a key you lose cannot be decrypted. Tests need no setup: `createTestApp` uses `CALM_ENCRYPTION_KEYS` when it is set and a random key otherwise.

### Rotating keys

The first key in the list encrypts. Every key in the list decrypts. When `CALM_ENCRYPTION_KEYS` already exists, `calm keygen --write` puts a new key in front and keeps the old ones:

```text
$ npx calm keygen --write
✔ Rotated: k2 encrypts new data; k1 still decrypts existing data.
```

```ini
CALM_ENCRYPTION_KEYS=k2:<new key>,k1:<old key>
```

1. Deploy with both keys. New writes use `k2`, existing records still decrypt with `k1`.
2. Re-save records at your pace. A value is encrypted again with the first key whenever it is written, so updates rotate the fields they touch. To rotate everything, load and save each document:

   ```js
   // scripts/reencrypt.js: node scripts/reencrypt.js
   import { createApp } from '#calm';

   const app = await createApp();
   await app.start();
   for await (const doc of app.model('patient').find()) await doc.save();
   await app.stop();
   ```

3. Once no record uses the old key, remove it from the list.

## JSON guard

`bodyLimit` caps the size of a body (1 MB). On top of that, CalmAPI refuses JSON bodies that are nested deeper than 20 levels or hold more than 10,000 values, with `400 BAD_REQUEST` (`JSON body is nested deeper than 20 levels`). A small but deeply nested payload cannot make validation do unbounded work. Change the limits in `calm.config.js`:

```js
// calm.config.js
export default defineConfig({
  jsonLimits: { maxDepth: 20, maxKeys: 10_000 },
});
```

## Security events

Suspicious activity is emitted on the app's event bus as `security.*` events. The devtools **Security** panel lists them live, and you can forward them to your alerting.

| Event | When | Payload |
|---|---|---|
| `security.login_failed` | Wrong email or password | `{ email, ip, reason }`, `reason` is `unknown_email` or `wrong_password` |
| `security.account_locked` | An account reaches the [lockout](/authentication#account-lockout) limit | `{ email, ip, until }` |
| `security.locked_login_attempt` | A sign-in on a locked account | `{ email, ip }` |
| `security.invalid_token` | A bearer token that is unknown or expired | `{ ip, path }` |
| `security.password_change_failed` | Wrong current password on `POST /api/auth/password` | `{ userId, ip }` |
| `security.invalid_reset_token` | A reset token that is unknown, expired or used | `{}` |
| `security.rate_limited` | A client goes over a rate limit (once per window) | `{ ip, path, limiter }` |
| `security.forbidden` | A request fails with `403` | `{ userId, ip, method, path }` |
| `security.write_rejected` | A body tried to set a hidden, read-only, owner or `writableBy` field | `{ userId, ip, method, path, resource, fields }` |

Emails in these payloads are masked (`a***@example.com`). The [totp](/blocks/totp#security-events) block adds `security.2fa_*` events.

Listen with `calm.on()` in a plugin in `app/blocks/` (or with `app.events.on()` anywhere you hold the app):

```js
// app/blocks/security-alerts/index.js
import { definePlugin } from '#calm';

export default definePlugin({
  name: 'security-alerts',
  setup(calm) {
    calm.on('security.account_locked', ({ email, ip, until }) => {
      calm.log.warn(`Account ${email} locked until ${until.toISOString()}`, { ip });
    });
    calm.on('security.*', (payload, name) => {
      // forward to your monitoring, chat or SIEM
    });
  },
});
```

## Exposure matrix

CalmAPI computes, from your resource definitions alone, who can do what. For every resource and every persona (anonymous, a signed-in user, the record's owner, each custom role used in your policies, and admin), it lists which CRUD actions are allowed and which fields each persona can read and write. It is always in sync with the code, because it is derived from the same policies, `visibleTo` and `writableBy` rules the API enforces.

| Action cell | Meaning |
|---|---|
| `allow` | Allowed |
| `own` | Only records they own (an `'owner'` policy on `list`) |
| `deny` | Denied |
| `off` | The CRUD route is turned off with the resource's `crud` option |
| `custom` | A policy function decides, so the answer can depend on the data |

Field cells are `yes`, `no`, or `never` for fields no client can ever read (hidden, write-only) or write (hidden, read-only). Fields whose name looks like personal data (`email`, `phone`, `address`, `iban`, `salary`...) are flagged, and so are fields you mark with [`.pii()`](/resources#personal-data) (`nickname: f.string().pii()`).

You can see it in the devtools **Security** panel, through the `calm_security` [MCP tool](/ai-agents#calm-mcp-tools-for-coding-agents), and in code with `await app.exposure()`. [`calm audit`](/audit) checks the running API against it, and `calm doctor` turns it into findings:

| Id | Level | Finding |
|---|---|---|
| `pii-public` | warn | A field that looks like personal data that anyone can read |
| `pii-users` | info | The same, readable by every signed-in user on a resource that has an owner |
| `sensitive-unencrypted` | info | A field named like a national id, tax id, passport, IBAN, card or health data that is not `.encrypted()` |

## Testing your policies

Static checks tell you what the rules say. [`calm audit`](/audit) tells you what the API does: it boots your app on a throwaway database, signs up a user per persona, seeds records and calls every route as every persona. It checks status codes, owner-only lists, field leaks, mass assignment, query injection and token handling. Run it after changing policies or fields, and in CI.

## What calm doctor checks

`calm doctor` boots your app in a child process (without connecting to MongoDB) and combines several kinds of checks. Run it after changes, and in CI with `--ci` (add `--prod` to apply production rules).

**Runtime checks** (also live in the devtools Doctor panel):

| Id | Finding |
|---|---|
| `node-version` | Node.js older than 22.12 |
| `cors-wildcard` | CORS allows every origin in production |
| `rate-limit-off` | Rate limiting disabled |
| `trust-proxy` | `TRUST_PROXY` not set in production |
| `no-mail` | Auth enabled but no mail transport in production |
| `policy-defaulted` | A resource action without an explicit policy |
| `public-write` | `create`, `update` or `delete` open to `public` |
| `secret-exposed` | A field named like a secret (`password`, `token`, `apiKey`...) that the API returns |
| `unknown-ref` | A reference to a resource that does not exist |
| `user-email-unique` | `user.email` without `.unique()` |
| `roles-writable` | Users can set their own roles |
| `route-policy` | A custom route without an explicit policy |
| `pii-public`, `pii-users`, `sensitive-unencrypted` | Personal or sensitive data findings from the [exposure matrix](#exposure-matrix) |
| `env-<NAME>` | An environment variable a block [declares](/building-blocks#environment-variables) as required is not set: an error when it is needed now, an info in development for variables needed in production |
| (blocks) | Checks added by blocks, such as `totp-unencrypted`, `webhooks-failing` or `privacy-plan` |
| `doctor-hook` | A block's doctor check crashed |

**Static checks** on your files:

| Id | Finding |
|---|---|
| `secret-*` | A hardcoded credential in a source or config file: AWS access keys, private keys, Stripe live keys, GitHub, Slack and Resend tokens, MongoDB URIs with a password, and `apiKey = '...'` style assignments. The value is masked in the report. |
| `populate-without-select` | `.populate()` without a select, which returns whole referenced documents |
| `regex-from-input` | A `RegExp` built from request input |
| `weak-random` | `Math.random()` in a file that deals with tokens, codes or secrets |
| `raw-res-json` | A handler that writes the response itself instead of returning a value |
| `logs-secrets` | `console.log` of something that looks secret |
| `env-not-ignored` | `.env` missing from `.gitignore` |
| `env-committed` | `.env` tracked by git (when the project is a git repository) |
| `core-modified`, `core-missing` | Framework files changed or deleted locally (informational) |
| `upgrade` | `calm/` is older than the installed CLI |

The secrets scan reads `.js`, `.mjs`, `.cjs`, `.ts`, `.json`, `.yml` and `.yaml` files of the whole project, except `node_modules/`, `calm/`, `test/`, `coverage/`, `.calm/`, `package-lock.json` and `calm.lock`. The code patterns (`populate-without-select` to `logs-secrets`) apply to the files in `app/`.

**Dependencies**: with `--audit`, doctor also runs `npm audit` on production dependencies (`npm-audit`): an error for high or critical vulnerabilities, a warning for moderate ones.

**Advisories**: published CalmAPI advisories that match your files.

```bash
npx calm doctor --ci                    # exit 1 on errors
npx calm doctor --ci --strict           # also on warnings
npx calm doctor --prod --audit --ci     # production rules and npm audit, for CI
npx calm doctor --json                  # for scripts
```

```text
  CalmAPI doctor · my-api

  ✖ error  Looks like a Stripe live key in source code  app/routes.js:1
           Found "sk_liv…" Move it to an environment variable (.env, never committed) and rotate it: anything that reached git is compromised.
  ✖ error  .env is committed to git
           Remove it from the repository (git rm --cached .env), rotate every secret in it, and keep it in .gitignore.
  ! warn   customer.phone looks like personal data and anyone can read it
           Add .visibleTo('owner | admin') (or .hidden()) if it should stay private.
  • info   customer.taxId could be encrypted at rest
           Add .encrypted() so database dumps and backups only hold ciphertext.

  2 errors · 1 warning · 1 info
```

## Your part

CalmAPI's defaults cover the framework. These are up to you:

- Write a policy for every action and route, and review them with `npx calm routes` and the devtools **Security** panel.
- Mark everything private as `hidden()`, `writeOnly()` or `visibleTo()`, and check the devtools **Data** panel to see what each kind of user receives.
- Run `npx calm audit` after changing policies or fields, and in CI.
- Encrypt sensitive fields with `.encrypted()`, and keep `CALM_ENCRYPTION_KEYS` in your secret store, never in git.
- Keep `.env` out of git, and use separate database users and secrets per environment.
- Set `CORS_ORIGINS`, `TRUST_PROXY` and a mail transport in production.
- Keep dependencies up to date (`npx calm doctor --audit` runs `npm audit`) and run `calm upgrade` when CalmAPI releases fixes.
- Forward `security.*` events to your monitoring, and consider the [totp](/blocks/totp) block for two-factor authentication.

---

Source: https://docs.calmapi.dev/security-advisories

# Security advisories

CalmAPI copies its code into your project, so `npm audit` cannot see problems in it. Advisories for that code are published here and in the CLI, and `calm doctor` checks your project against every published advisory.

## Current advisories

Advisories for CalmAPI 1.x will be published here together with their fixes. Until then, and after every release, check your 1.x project with the latest CLI:

```bash
npx calmapi@next doctor
```

Inside a CalmAPI 2 project, use `npx calm doctor`. Each finding names the advisory, the affected files and the fix.

## Staying informed

- Watch the [calmapi repository](https://github.com/sunilksamanta/calmapi) on GitHub for security advisories and releases.
- Run `npx calm doctor --ci` in your CI pipeline, so new advisories are reported on the next build.
- Apply fixes to framework files with [`calm upgrade`](/upgrading).

To report a vulnerability, see [Security](/security#reporting-a-vulnerability).

---

Source: https://docs.calmapi.dev/migrate-v1

# Migrating from CalmAPI 1.x

CalmAPI 2 keeps the idea of 1.x (the framework code lives in your project) and replaces almost everything else: ESM, Express 5, resources instead of six files per module, policies, opaque sessions, devtools and an upgrade path. There is no in-place upgrade. You create a 2.0 project and move your modules over; most modules shrink to one or two files.

## Step 0: check your 1.x project first

Inside your 1.x project, run the doctor from the new CLI:

```bash
npx calmapi@next doctor
```

It checks the project against the advisories published for 1.x templates and prints the fix for each finding. Apply those fixes to the 1.x app running in production before you start migrating.

## Concept map

| 1.x | 2.0 |
|---|---|
| `src/modules/x/x.model.js` + `x.dto.js` (Get/Insert/Update DTOs) | `app/resources/x/x.resource.js`: fields with `f.*()`, validation and visibility in one place |
| `x.controller.js` (CalmController, autoBind, try/catch) | Gone: CRUD is generated. Custom endpoints go in `x.routes.js` and return values. |
| `x.service.js` (CalmService) | `x.service.js` extending `ResourceService`, with hooks (`beforeCreate`, `scope`...) |
| `x.route.js` + `AuthController.checkLogin` | `policy: { list, read, create, update, delete }`, and `{ policy }` on custom routes |
| `x.settings.js` (`moduleRoute`) | `resource('x', { path: '/custom-path' })` |
| `populateFields` | `f.ref('user').populate()` or `?include=author`, serialized with the target's rules |
| `system/` | `calm/`, upgradeable with `calm upgrade` |
| `calmapi generate module x` | `calm make resource x field:type ...` |
| `src/configs/config.js` | `calm.config.js` + `.env` |
| JWT tokens in the `auth` collection | Opaque session tokens, hashed, in `calm_sessions` |
| `media` module (S3) | `calm add storage-s3` (presigned uploads) or `calm add storage-local` |
| CommonJS (`require`) | ESM (`"type": "module"`), imports via `#calm` and `#app/*` |

### A module, before and after

In 1.x a post module is six files: a Mongoose model class, three DTO classes, a controller, a service, a router and settings. In 2.0:

```js
// app/resources/post/post.resource.js
import { resource, f } from '#calm';

export default resource('post', {
  fields: {
    title: f.string().required().max(200).searchable().sortable(),
    slug: f.string().readOnly().unique().filterable(),     // was set by a pre('save') hook
    content: f.text().required(),
    createdBy: f.ref('user').owner(),                      // was set by the controller
  },
  policy: {
    list: 'authenticated',
    read: 'authenticated',
    create: 'authenticated',
    update: 'owner | admin',
    delete: 'owner | admin',
  },
});
```

```js
// app/resources/post/post.service.js
import { ResourceService } from '#calm';

export default class PostService extends ResourceService {
  async beforeCreate(data) {
    return { ...data, slug: slugify(data.title) }; // your slug helper
  }
}
```

`updatedBy` has no direct equivalent; set it in `beforeUpdate` from `ctx.user.id` if you need it, or add the [audit-log](/blocks/audit-log) block for a full history. Keep the existing field names so the stored documents still match.

## API changes your clients will see

| | 1.x | 2.0 |
|---|---|---|
| Success | `{ error: false, status: true, statusCode, responseTimestamp, data, totalCount }` | `{ data }`; lists add `meta: { total, page, limit, pages }` |
| Errors | `{ error: true, name, message, statusCode }` | `{ error: { code, message, details?, requestId } }` |
| Status codes | `200` for every success | `201` on create, `204` on delete, specific 4xx codes |
| Ids | `_id` | `id` |
| Pagination | `skip`, `limit` | `page`, `limit` (max 100 by default) |
| Sorting | `sortBy=-createdAt` | `sort=-createdAt,title` (only `.sortable()` fields) |
| Filters | any field | only `.filterable()` fields: `status=x`, `price[gte]=10`, `tags[in]=a,b` |
| Updates | `PUT /:id` | `PATCH /:id` (PUT still works as an alias) |
| Auth header | `Authorization: Bearer <jwt>` | `Authorization: Bearer <session token>`, header only |
| Login response | `{ token, user }` | `{ data: { token, expiresAt, user } }` |
| Password reset | 6-digit code | Emailed single-use link (`/api/auth/password/forgot`, `/api/auth/password/reset`) |

See [Errors](/errors) and [Querying](/querying) for the details.

## Authentication changes

- **Users sign in again.** 1.x issued JWTs; 2.0 uses opaque session tokens stored as hashes in `calm_sessions`. Existing tokens are not accepted, so every user logs in once after the switch.
- **Password hashes.** 1.x stored bcrypt hashes; 2.0 uses scrypt. Either ask existing users to use "forgot password" once, or add bcrypt verification to `calm/auth/password.js` (it is your code) and let the rehash on login move them to scrypt.
- **Reset flow.** The reset email now contains a link to your frontend (`auth.resetUrl`, default `${APP_URL}/reset-password?token=...`). Build that page; it posts `{ token, password }` to `/api/auth/password/reset`.
- **Roles.** Use a `roles` array on the user (`['user', 'admin']`) and role names in policies.

## Step by step

1. **Create the project** and point it at a copy of your database:

   ```bash
   npm create calmapi@latest my-api-v2
   ```

   Set `MONGODB_URI` in `.env`. Keep collection names (`collection: 'posts'`) when they differ from the defaults.

2. **Recreate each module as a resource**: `npx calm make resource <name> ...fields`, then copy the types from the 1.x model. Mark visibility from your DTOs: what your GetDTO left out becomes `.hidden()` or `.writeOnly()`, and what InsertDTO and UpdateDTO left out becomes `.readOnly()`.

3. **Write explicit policies** for every action. Decide who may list, read and change each kind of record, and mark the creator field with `f.ref('user').owner()` so `'owner'` policies work.

4. **Move custom controller methods** into `<name>.routes.js` (return values, no `res`) and business logic into the service.

5. **Move the user model** into `app/resources/user/user.resource.js` and decide how existing passwords are handled (see above).

6. **Check and test**:

   ```bash
   npx calm doctor
   npx calm routes
   npm test
   ```

7. **Update your frontend** for the new response shape, status codes, pagination and auth.

8. **Switch over** and let users sign in again.

Questions are welcome in [GitHub Discussions](https://github.com/sunilksamanta/calmapi/discussions). The [1.x documentation](/v1) stays available while you migrate.

---

Source: https://docs.calmapi.dev/quick-reference

# Quick reference

CalmAPI 2 on one page. Follow the links for details.

## Commands

```bash
npm create calmapi@latest my-api           # new project (templates: api, minimal)
npm run dev                                 # watch mode + devtools at /_calm
npx calm make resource product name:string!+searchable price:number! status:enum:draft,live=draft category:ref --service --routes
npx calm add jobs storage-s3 api-docs       # blocks (calm add --list)
npx calm add gh:acme/blocks/billing         # a block from GitHub, reviewed before it is written
npx calm make block slack-notify            # your own block (calm block check | pack | list)
npx calm seed product --count 50            # sample data that looks real
npx calm routes                             # routes and policies
npx calm doctor --prod --ci                 # checks, CI friendly (--audit adds npm audit)
npx calm audit --ci                         # every route as every role, on a throwaway database
npx calm admin ada@example.com              # grant the admin role (--revoke to remove)
npx calm keygen --write                     # CALM_ENCRYPTION_KEYS for .encrypted() fields (rotates)
npx calm openapi --out openapi.json
npx calm upgrade --dry-run                  # merge framework updates into calm/
claude mcp add calm -- npx calm mcp         # MCP server for coding agents
npm test                                    # node --test, needs MongoDB
```

[CLI reference](/cli)

## Resource

```js
// app/resources/product/product.resource.js
import { resource, f } from '#calm';

export default resource('product', {
  fields: {
    name: f.string().required().max(120).searchable().sortable(),
    price: f.number().required().min(0).filterable().sortable(),
    cost: f.number().hidden(),
    status: f.enum(['draft', 'live']).default('draft').filterable(['eq', 'in']),
    category: f.ref('category').filterable(),
    tags: f.array(f.string()).default([]).filterable(),
    owner: f.ref('user').owner(),
  },
  policy: { list: 'public', read: 'public', create: 'authenticated', update: 'owner | admin', delete: 'owner | admin' },
  // path, collection, timestamps, defaultSort, crud: ['list', 'read'], indexes, owner: '_id', description
});
```

[Resources and fields](/resources)

## Fields

| | |
|---|---|
| Types | `f.string() text() email() url() password() number() integer() boolean() date() enum([...]) id() ref('name') array(f) object({...}) json()` |
| Validation | `.required() .optional() .default(v) .min(n) .max(n) .pattern(re) .trim() .lowercase() .uppercase() .unique() .index() .check(fn) .schema(standardSchema)` |
| Visibility | `.hidden() .writeOnly() .readOnly() .immutable() .writableBy('admin') .visibleTo('owner \| admin')` |
| Storage | `.encrypted()` (AES-256-GCM at rest, needs `CALM_ENCRYPTION_KEYS`, cannot be queried) |
| Queries | `.filterable([ops]) .sortable() .searchable()` |
| Relations | `.owner()` (on `f.ref('user')`) `.populate()` |
| Docs | `.describe(text) .example(value)` |

## Policies

`'public'`, `'authenticated'`, `'owner'`, `'admin'` or any role, `'none'`, combined with `|`, or functions `({ user, action, doc, req }) => boolean` in an array: `['owner | admin', isPublished]`.

Item routes: `401` signed out, `404` cannot read (or hidden by `scope()`), `403` can read but not act. `'owner'` on `list` filters to the user's records.

[Policies](/policies)

## CRUD routes

| | | |
|---|---|---|
| `GET /api/products` | list | `200 { data, meta: { total, page, limit, pages } }` |
| `GET /api/products/:id` | read | `200 { data }` |
| `POST /api/products` | create | `201 { data }` |
| `PATCH /api/products/:id` | update | `200 { data }` (PUT alias) |
| `DELETE /api/products/:id` | delete | `204` |

## Queries

```text
?status=live  ?price[gte]=10&price[lt]=50  ?tags[in]=a,b  ?tags[all]=a,b  ?category[exists]=true  ?id[in]=x,y
?q=saw  ?sort=-price,name  ?page=2&limit=20  ?include=category,owner  ?fields=name,price
```

Operators: `eq ne gt gte lt lte in nin all exists`. Anything undeclared is a `400`. [Querying](/querying)

## Service

```js
// app/resources/product/product.service.js
import { ResourceService, hasRole, conflict } from '#calm';

export default class ProductService extends ResourceService {
  scope({ user } = {}) { return hasRole(user, 'admin') ? {} : { status: 'live' }; }
  async beforeCreate(data, ctx) { return { ...data, cost: data.price / 2 }; }
  async beforeUpdate(data, existing, ctx) { return data; }
  async beforeDelete(doc, ctx) { if (doc.status === 'live') throw conflict('Unpublish it first'); }
  // afterCreate(doc, ctx), afterUpdate(doc, previous, ctx), afterDelete(doc, ctx)
}
```

Methods: `list({ filter, sort, skip, limit, populate }, ctx)`, `get(id, { populate }, ctx)`, `find(filter, ctx)`, `findOne(filter, ctx)`, `create(data, ctx)`, `update(id, data, ctx)`, `remove(id, ctx)`, `filterFor(ctx, extra)`, `service(name)`. Events: `product.created|updated|deleted`. [Services and hooks](/services)

## Custom routes

```js
// app/resources/product/product.routes.js (mounted before CRUD)
import { f, badRequest } from '#calm';

export default (r) => {
  r.get('/cheap', { policy: 'public' }, (ctx) => ctx.service.find({ price: { $lt: 10 } }, ctx));
  r.post('/:id/discount', { policy: 'owner', input: { percent: f.integer().required().min(1).max(90) } }, async (ctx) => {
    if (ctx.doc.price < 1) throw badRequest('Too cheap');
    return ctx.service.update(ctx.doc._id, { price: ctx.doc.price * (1 - ctx.body.percent / 100) }, ctx);
  });
  r.post('/import', { policy: 'admin', status: 202, rateLimit: { windowMs: 60_000, max: 5 } }, (ctx) => ctx.reply({ queued: true }, { status: 202 }));
};
```

Options: `policy input status summary description tags middleware rateLimit hidden`. Return a value (`200 { data }`), `undefined` (`204`) or `ctx.reply(data, { status, meta, headers })`. `ctx`: `user params query body doc service services serialize reply req res app config log events`. [Custom routes](/routes)

## Errors

`badRequest(msg, details)` 400 · `unauthorized(msg)` 401 · `forbidden(msg)` 403 · `notFound(msg)` 404 · `conflict(msg, details)` 409 · `validationError(details)` 422 · `tooManyRequests()` 429 · `new CalmError(status, code, message, details)`.

Shape: `{ error: { code, message, requestId, details? } }`. [Errors](/errors)

## Auth

```text
POST /api/auth/register          { name, email, password }        -> 201 { data: { user, token, expiresAt } }
POST /api/auth/login             { email, password }              -> 200 { data: { user, token, expiresAt } }
POST /api/auth/logout | logout-all                                -> 204
GET  /api/auth/me   PATCH /api/auth/me
POST /api/auth/password          { currentPassword, newPassword } -> 204
POST /api/auth/password/forgot   { email }                        -> 202
POST /api/auth/password/reset    { token, password }              -> 204
GET  /api/auth/sessions   DELETE /api/auth/sessions/:sessionId
```

Devices for push: `POST /api/auth/devices { token, platform }`, `GET /api/auth/devices`, `DELETE /api/auth/devices/:deviceId`, `POST /api/auth/devices/unregister { token }`. Signing out removes the session's devices.

Header: `Authorization: Bearer calm_...`. 5 failed sign-ins for an email lock it for 15 minutes (`429`). Two-factor: the [totp](/blocks/totp) block. [Authentication](/authentication)

## Push notifications

```js
await ctx.push.send({ to: userId, title: 'Your order shipped', body: 'Arrives Thursday', url: '/orders/42', data: { orderId: '42' } });
// -> { id, status: 'captured' | 'sent' | 'partial' | 'failed' | 'no-devices', devices, results }
```

Development: previews in devtools **Push**, simulated phones that are offline, muted or uninstalled, nothing delivered. Deliver: `npx calm add push-expo` and/or `push-fcm`. Inbox, push and email in one call: the [notifications](/blocks/notifications) block. Tests: `t.pushes`. [Push notifications](/push-notifications)

## Config and environment

```js
// calm.config.js
import { defineConfig } from '#calm';
export default defineConfig({ pagination: { maxLimit: 100 }, auth: { register: true }, mail: { from: 'App <no-reply@example.com>' } });
```

`NODE_ENV` (default production) · `MONGODB_URI` · `APP_URL` (required in production) · `PORT` (5001) · `CORS_ORIGINS` · `TRUST_PROXY` · `LOG_LEVEL` · `CALM_ENCRYPTION_KEYS`. [Configuration](/configuration)

## Testing

```js
import { createTestApp } from '#calm/testing.js';
const t = await createTestApp({ root: join(import.meta.dirname, '..') });
const alice = await t.signup();                          // { token, user, id, email, password }
const admin = await t.signup({ roles: ['user', 'admin'] });
const res = await t.post('/products', { name: 'Saw', price: 12 }, alice);  // { status, body, headers }
await t.idle(); await t.close();
```

[Testing](/testing)

## Imports

`#calm` (framework API), `#calm/testing.js` (any framework file), `#app/...` (your code). Other resources: `this.service('name')` in services, `ctx.services.name` in routes.