express-file-cluster 0.3.15 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-3VWD2ZED.js +60 -0
- package/dist/chunk-3VWD2ZED.js.map +1 -0
- package/dist/chunk-47K2532L.cjs +196 -0
- package/dist/chunk-47K2532L.cjs.map +1 -0
- package/dist/chunk-5PDAWMGF.js +438 -0
- package/dist/chunk-5PDAWMGF.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-ALBDM5R3.cjs +60 -0
- package/dist/chunk-ALBDM5R3.cjs.map +1 -0
- package/dist/chunk-JJJJTACK.js +196 -0
- package/dist/chunk-JJJJTACK.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-M7MUPWCE.js +116 -0
- package/dist/chunk-M7MUPWCE.js.map +1 -0
- package/dist/chunk-PMF4GMHD.js +154 -0
- package/dist/chunk-PMF4GMHD.js.map +1 -0
- package/dist/chunk-QTRGJ2EN.cjs +2635 -0
- package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
- package/dist/chunk-RSBW2B3D.cjs +126 -0
- package/dist/chunk-RSBW2B3D.cjs.map +1 -0
- package/dist/chunk-RTFJ32T5.js +2635 -0
- package/dist/chunk-RTFJ32T5.js.map +1 -0
- package/dist/chunk-SFVEQ2T5.cjs +438 -0
- package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
- package/dist/chunk-SZT36SGB.cjs +154 -0
- package/dist/chunk-SZT36SGB.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-ULQXD4YZ.cjs +116 -0
- package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
- package/dist/chunk-VYHJX54R.js +126 -0
- package/dist/chunk-VYHJX54R.js.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +323 -0
- package/dist/docs/api-reference/table.md +250 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +70 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +308 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +289 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +472 -7
- package/dist/index.d.ts +472 -7
- package/dist/index.js +283 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
- package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
- package/dist/pgboss-backend-UUJOVEYK.js +14 -0
- package/dist/pgboss-backend-UUJOVEYK.js.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-DJCPAsM4.d.cts +541 -0
- package/dist/types-DJCPAsM4.d.ts +541 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- package/dist/types-BusbSenn.d.ts +0 -162
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# EFC Documentation
|
|
2
|
+
|
|
3
|
+
**express-file-cluster (EFC)** is an opinionated backend framework built on Express. It removes routing ceremony, saturates every CPU core automatically, and ships a production-grade background-task subsystem — all from a single `ignite()` call.
|
|
4
|
+
|
|
5
|
+
> **Status: v0.5.0 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries), BullMQ and pg-boss tasks with cron and dead-letter tooling, and migrations are all implemented.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## What EFC solves
|
|
10
|
+
|
|
11
|
+
| Pain point | EFC's answer |
|
|
12
|
+
|---|---|
|
|
13
|
+
| Route registration boilerplate | The file tree **is** the route tree |
|
|
14
|
+
| Single-threaded Node under load | CPU-count auto-detection → worker processes |
|
|
15
|
+
| Blocking work on the request path | `enqueue()` ships it off-path with retries; `schedule` runs it on cron |
|
|
16
|
+
| Wiring DB, auth, and middleware by hand | `ignite()` bootstraps everything in one call |
|
|
17
|
+
| Different code per database | `defineModel` runs the same on MongoDB and PostgreSQL |
|
|
18
|
+
| Hand-rolled input checks | `export const schema` validates params, query and body |
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Documentation sections
|
|
23
|
+
|
|
24
|
+
| Section | What you'll find |
|
|
25
|
+
|---|---|
|
|
26
|
+
| [Getting Started](./getting-started/index.md) | Scaffold a project, understand the structure |
|
|
27
|
+
| [Core Concepts](./core-concepts/index.md) | The four pillars: routing, clustering, tasks, middleware |
|
|
28
|
+
| [API Reference](./api-reference/ignite.md) | Every exported function and type, fully documented |
|
|
29
|
+
| [Guides](./guides/authentication.md) | Deep-dives: auth, database, RBAC, mailer, error handling, deployment |
|
|
30
|
+
| [CLI](./cli/index.md) | All `efc` commands with flags and examples |
|
|
31
|
+
| [Contributing](./contributing/index.md) | Roadmap, branch conventions, PR requirements |
|
|
32
|
+
|
|
33
|
+
### Guides
|
|
34
|
+
|
|
35
|
+
| Guide | Covers |
|
|
36
|
+
|---|---|
|
|
37
|
+
| [Authentication](./guides/authentication.md) | JWT strategies, login/logout, `requireAuth` |
|
|
38
|
+
| [RBAC](./guides/rbac.md) | Role-based route protection via the `requireAuth('role')` shorthand |
|
|
39
|
+
| [Database](./guides/database.md) | `defineModel`, queries, transactions, MongoDB vs PostgreSQL |
|
|
40
|
+
| [defineTable](./api-reference/table.md) | PostgreSQL-native models: Prisma-style queries, SQL types, aggregation |
|
|
41
|
+
| [Migrations & Seeds](./guides/migrations.md) | `efc db migrate / rollback / seed / studio` |
|
|
42
|
+
| [Validation](./guides/validation.md) | Route `schema` exports with zod, valibot, arktype |
|
|
43
|
+
| [Logging](./guides/logging.md) | pino, request IDs, `getLogger()` |
|
|
44
|
+
| [Caching & Sessions](./guides/caching.md) | `cache`, `cacheResponse`, revoking JWT sessions |
|
|
45
|
+
| [Generated Portals](./guides/generated-portals.md) | Every model and route `create-efc-app` scaffolds for the User/Admin portals |
|
|
46
|
+
| [Mailer](./guides/mailer.md) | Gmail (app password) and custom SMTP setup, sending email from a task |
|
|
47
|
+
| [Environment Variables](./guides/environment-variables.md) | Full `.env` reference |
|
|
48
|
+
| [Error Handling](./guides/error-handling.md) | `HttpError`, custom handlers, task failures |
|
|
49
|
+
| [Deployment](./guides/deployment.md) | Build, start, and ship to production |
|
|
50
|
+
| [AI Coding Agents](./guides/ai-agents.md) | Docs bundled in the package, `AGENTS.md`, the `express-file-cluster-mcp` server |
|
|
51
|
+
|
|
52
|
+
### Tooling
|
|
53
|
+
|
|
54
|
+
An [MCP server](https://github.com/pr4shxnt/efc.js/tree/main/mcp) ships in this repo (`mcp/`) that exposes this documentation as tools, resources, and prompts to MCP-compatible AI assistants (Claude, Cursor, etc.) — useful if you want an assistant to scaffold routes/tasks or answer "does EFC support X?" without hallucinating. See `mcp/README.md` for setup.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Five-minute overview
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# 1. Scaffold
|
|
62
|
+
npx create-efc-app my-api
|
|
63
|
+
cd my-api
|
|
64
|
+
|
|
65
|
+
# 2. Run in dev mode (hot-reload, single process)
|
|
66
|
+
npm run dev # → efc start dev
|
|
67
|
+
|
|
68
|
+
# 3. Drop a file → get a route
|
|
69
|
+
# src/api/users/[id].ts → GET /users/:id
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
// src/api/users/[id].ts
|
|
74
|
+
import type { Request, Response } from 'express';
|
|
75
|
+
|
|
76
|
+
export const GET = async (req: Request, res: Response) => {
|
|
77
|
+
res.json({ id: req.params.id });
|
|
78
|
+
};
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// src/index.ts
|
|
83
|
+
import { ignite, gracefulShutdown } from 'express-file-cluster';
|
|
84
|
+
import config from '../efc.config.js';
|
|
85
|
+
|
|
86
|
+
// efc.config.ts reads PORT, DATABASE_URL, JWT_SECRET, CORS_ORIGINS from .env explicitly —
|
|
87
|
+
// ignite() itself never touches process.env for these (see Environment Variables guide)
|
|
88
|
+
ignite({
|
|
89
|
+
...config,
|
|
90
|
+
}).then(gracefulShutdown).catch(console.error);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The framework always scans `src/api/` on boot (this path is a fixed convention, not configurable), derives route paths from file names, forks `os.cpus().length` worker processes in production (single-process in dev — `ignite()`'s own default, don't override it with a hardcoded `cluster: true`), and handles `SIGTERM`/`SIGINT` gracefully — zero extra code required.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: efc
|
|
3
|
+
description: Ground-truth reference for express-file-cluster (EFC) — exact API surface, routing rules, Pre-Flight lifecycle, task internals, and a hard list of things that do NOT exist. Load before writing any EFC code to avoid hallucination.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Express File Cluster (EFC) — Skill
|
|
8
|
+
|
|
9
|
+
Use this skill whenever you're reading, writing, or debugging EFC code. It loads the exact source-derived facts about this framework so you never invent APIs, import paths, or behaviours that don't exist.
|
|
10
|
+
|
|
11
|
+
## When to load
|
|
12
|
+
|
|
13
|
+
- Writing a new route, task, model, or middleware
|
|
14
|
+
- Debugging a boot failure or a missing-route issue
|
|
15
|
+
- Answering "does EFC support X?" questions
|
|
16
|
+
- Any time you're about to type an `import` from `express-file-cluster`
|
|
17
|
+
|
|
18
|
+
## Routing table — open the module that matches the work
|
|
19
|
+
|
|
20
|
+
| Situation | Open |
|
|
21
|
+
|---|---|
|
|
22
|
+
| What is exported and from where | [api-surface.md](api-surface.md) |
|
|
23
|
+
| How file paths become URL paths | [routing-rules.md](routing-rules.md) |
|
|
24
|
+
| Worker boot sequence (Pre-Flight) | [pre-flight.md](pre-flight.md) |
|
|
25
|
+
| Background tasks — defineTask, enqueue, thread, cron, pg-boss, dead letters | [tasks-internals.md](tasks-internals.md) |
|
|
26
|
+
| Auth — issueToken, requireAuth internals | [auth-internals.md](auth-internals.md) |
|
|
27
|
+
| Things that do NOT exist (anti-hallucination) | [what-not-to-invent.md](what-not-to-invent.md) |
|
|
28
|
+
|
|
29
|
+
Load **only** the module the work points to. Each is self-contained.
|
|
30
|
+
|
|
31
|
+
## Project location
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
<repo root>/
|
|
35
|
+
packages/core/src/ ← framework source
|
|
36
|
+
packages/create-efc-app/src/ ← scaffolder
|
|
37
|
+
docs/ ← full documentation
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Status (v0.5.0 — Beta, Phase 2 complete + defineTable)
|
|
41
|
+
|
|
42
|
+
Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only + localStorage auth, structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`), full CLI.
|
|
43
|
+
|
|
44
|
+
**Not yet implemented (Phase 3+):** WebSockets, plugins, OpenAPI generation, OpenTelemetry, `efc lint`, `efc deploy`, schema-diff migration generation.
|
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
# EFC — Exact API Surface
|
|
2
|
+
|
|
3
|
+
Source of truth: `packages/core/src/`. Do not invent exports, types, or sub-paths not listed here.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Sub-path exports
|
|
8
|
+
|
|
9
|
+
Three import paths. No others exist.
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { ... } from 'express-file-cluster' // main
|
|
13
|
+
import { ... } from 'express-file-cluster/auth' // auth module
|
|
14
|
+
import { ... } from 'express-file-cluster/tasks' // tasks module
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## `express-file-cluster` (main)
|
|
20
|
+
|
|
21
|
+
Source: `packages/core/src/index.ts`
|
|
22
|
+
|
|
23
|
+
### Functions & values
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
async function ignite(config: EFCConfig): Promise<http.Server | undefined> // undefined on the cluster primary
|
|
27
|
+
function gracefulShutdown(server: http.Server | undefined, timeoutMs?: number): void
|
|
28
|
+
function compose(...handlers: RequestHandler[]): RequestHandler
|
|
29
|
+
|
|
30
|
+
// Models — one API on MongoDB (mongoose) and PostgreSQL (Drizzle); engine picked at first use
|
|
31
|
+
// Types are INFERRED from the schema literal — no interface needed:
|
|
32
|
+
// const User = defineModel('User', {...}); type User = InferRecord<typeof User>;
|
|
33
|
+
// Explicit defineModel<T>(...) still works (v0.4 behaviour: create() takes Partial<T>).
|
|
34
|
+
function defineModel(name: string, schema: ModelSchema, options?: ModelOptions): ModelCRUD<Record, CreateInput>
|
|
35
|
+
type InferRecord<typeof Model> // record incl. id + timestamps per options (defineModel and defineTable)
|
|
36
|
+
type InferCreate<typeof Model> // create() input: required w/o default/sequence mandatory; dates accept string|number
|
|
37
|
+
async function transaction<T>(fn: () => Promise<T>): Promise<T> // model calls inside join automatically
|
|
38
|
+
// PostgreSQL-native (Prisma vocabulary + SQL types); MongoDB → [EFC] error at first use
|
|
39
|
+
function defineTable(name: string, schema: TableSchema, options?: TableOptions): TableModel<S, O>
|
|
40
|
+
// types: + 'integer' (number) 'bigint' (bigint) 'decimal' {precision, scale} (string, exact) 'uuid' 'json'
|
|
41
|
+
// 'string'+maxLength → varchar(n); { type:'array', of: scalar } → native array; enum + nativeEnum → PG ENUM
|
|
42
|
+
// options: id: 'uuid' | 'serial' (number ids) | 'bigserial' (bigint ids); naming: 'snake_case'; field `column`
|
|
43
|
+
// findMany({ where, orderBy, take (neg = backwards), skip, cursor (unique where, inclusive), distinct, select | omit })
|
|
44
|
+
// findFirst / findFirstOrThrow / findUnique({ where: unique }) / findUniqueOrThrow → 404 HttpError
|
|
45
|
+
// count({ where, select?: { _all, field } }) · aggregate({ _count, _sum, _avg, _min, _max, where, ...page })
|
|
46
|
+
// groupBy({ by, where, having: { f: { _sum: { gt } } }, orderBy: { _sum: { f: 'desc' } }, take, skip })
|
|
47
|
+
// create({ data }) · createMany({ data, skipDuplicates }) → { count } · createManyAndReturn
|
|
48
|
+
// update({ where: unique, data }) 404 if missing · updateMany → { count } · updateManyAndReturn
|
|
49
|
+
// upsert({ where: unique, create, update }) = one INSERT … ON CONFLICT · delete({ where: unique }) · deleteMany → { count }
|
|
50
|
+
// where: value | null | equals not in notIn lt lte gt gte · strings: contains startsWith endsWith mode:'insensitive'
|
|
51
|
+
// arrays: has hasEvery hasSome isEmpty · jsonb: { path: [...], equals | string_contains | array_contains | gt… }
|
|
52
|
+
// AND / OR / NOT · undefined ignored · undeclared fields match nothing
|
|
53
|
+
// data ops: { increment | decrement | multiply | divide } (numbers), { push } (arrays), { set }, null unsets
|
|
54
|
+
// unique where: id | unique field | all fields of a unique index. No relations/include yet (M3).
|
|
55
|
+
|
|
56
|
+
class ModelValidationError extends HttpError { issues: { path: string; message: string }[] } // status 400
|
|
57
|
+
|
|
58
|
+
// Native client from Pre-Flight: mongoose Connection (MongoDB) or pg Pool (PostgreSQL)
|
|
59
|
+
const db: AnyClient // Proxy — throws before Pre-Flight; methods are bound to the real client
|
|
60
|
+
function setDbClient(client: Record<string, unknown>): void
|
|
61
|
+
function getDbClient(): Record<string, unknown>
|
|
62
|
+
|
|
63
|
+
// Logging (pino)
|
|
64
|
+
const logger: Logger // proxy for getLogger()
|
|
65
|
+
function getLogger(): Logger // request-scoped child (carries reqId) inside a request, root otherwise
|
|
66
|
+
|
|
67
|
+
// Cache — needs ignite({ cache }); throws "Cache not configured" otherwise.
|
|
68
|
+
// Redis outage → get = undefined, set/del no-ops, wrap computes (never throws).
|
|
69
|
+
const cache: {
|
|
70
|
+
get<T>(key): Promise<T | undefined>; set(key, value, { ttl?: seconds }?): Promise<void>;
|
|
71
|
+
has(key): Promise<boolean>; del(...keys): Promise<number>;
|
|
72
|
+
wrap<T>(key, ttlOrOptions, fn: () => Promise<T>): Promise<T>; // in-process stampede dedupe
|
|
73
|
+
clear(prefix?): Promise<number>;
|
|
74
|
+
}
|
|
75
|
+
function cacheResponse(ttl: number | { ttl; perUser?: boolean; key?: (req) => string }): RequestHandler
|
|
76
|
+
// GET/HEAD 200 JSON only; X-Cache: HIT|MISS; keys under 'res:' + originalUrl
|
|
77
|
+
|
|
78
|
+
function scanDir(dir: string, base?: string, maxDepth?: number): RouteEntry[]
|
|
79
|
+
function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
|
|
80
|
+
function workerCount(): number
|
|
81
|
+
class HttpError extends Error { readonly statusCode: number; static from(err, status?, fallback?): HttpError }
|
|
82
|
+
function isHttpError(value: unknown): value is HttpError
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Config types
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
interface EFCConfig {
|
|
89
|
+
port?: number; // default 3000
|
|
90
|
+
basePath?: string; // default '/v1/api'
|
|
91
|
+
dashboard?: boolean; // dev-only route docs at '/'
|
|
92
|
+
database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
|
|
93
|
+
databaseUrl?: string;
|
|
94
|
+
authStrategy?: 'http-only' | 'localStorage';
|
|
95
|
+
jwtSecret?: string;
|
|
96
|
+
jwtExpiresIn?: string; // default '7d'
|
|
97
|
+
cookieDomain?: string;
|
|
98
|
+
cluster?: boolean; // default NODE_ENV === 'production'
|
|
99
|
+
workers?: number; // default os.cpus().length
|
|
100
|
+
tasks?: TaskConfig | false;
|
|
101
|
+
cors?: boolean | CorsConfig; // default true
|
|
102
|
+
requestTimeout?: number; // ms → 408
|
|
103
|
+
logging?: LoggingConfig | false;
|
|
104
|
+
autoSync?: boolean; // default true — reconcile tables/collections + indexes on first use
|
|
105
|
+
cache?: ({ prefix?: string; onRevocationCheckError?: 'reject' | 'allow' /* default reject → 503 */ } & (
|
|
106
|
+
| { backend: 'redis'; url?: string; timeout?: number }
|
|
107
|
+
| { backend: 'memory'; maxEntries?: number } /* lives in the cluster primary; workers use IPC */
|
|
108
|
+
)) | false;
|
|
109
|
+
globalMiddlewares?: RequestHandler[];
|
|
110
|
+
onWorkerReady?: (id: number) => void;
|
|
111
|
+
onWorkerCrash?: (id: number, code: number) => void;
|
|
112
|
+
onError?: ErrorRequestHandler;
|
|
113
|
+
}
|
|
114
|
+
// NOTE: there is NO apiDir / tasksDir option — src/api and src/tasks are found by convention.
|
|
115
|
+
|
|
116
|
+
interface TaskConfig {
|
|
117
|
+
backend: 'bullmq' | 'pg-boss';
|
|
118
|
+
redisUrl?: string; // BullMQ, default redis://localhost:6379
|
|
119
|
+
connectionString?: string; // pg-boss, default databaseUrl
|
|
120
|
+
schema?: string; // pg-boss, default 'pgboss'
|
|
121
|
+
concurrency?: number; // default 5
|
|
122
|
+
enqueueTimeout?: number; // default 5000 ms — enqueue() rejects instead of hanging
|
|
123
|
+
queue?: string; // default 'efc'
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
interface LoggingConfig {
|
|
127
|
+
level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'; // default 'info'
|
|
128
|
+
pretty?: boolean; // default: non-production TTY
|
|
129
|
+
requests?: boolean; // default true
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Route file exports
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
export const GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS = async (req, res) => {}
|
|
137
|
+
export const middlewares: RequestHandler[]
|
|
138
|
+
export const schema: RouteSchema // { params?, query?, body? } or keyed by method
|
|
139
|
+
export const meta: RouteMeta // dashboard docs, keyed by method
|
|
140
|
+
|
|
141
|
+
type Validator = { '~standard': { validate } } | { safeParse } // Standard Schema (zod ≥3.24, valibot, arktype)
|
|
142
|
+
interface RequestSchema { params?: Validator; query?: Validator; body?: Validator }
|
|
143
|
+
type RouteSchema = RequestSchema | Partial<Record<string, RequestSchema>>
|
|
144
|
+
// Failure → 400 { error: 'Validation failed', statusCode: 400, issues: [{ location, path, message }] }
|
|
145
|
+
// Success → parsed output replaces req.params/query/body. Runs AFTER file middlewares.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`req.id` (request ID) and `req.log` (request logger) are added to Express's `Request` type.
|
|
149
|
+
|
|
150
|
+
### Model types
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
type PrimitiveFieldType = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'objectId';
|
|
154
|
+
|
|
155
|
+
interface FieldDefinition {
|
|
156
|
+
type: PrimitiveFieldType | 'array';
|
|
157
|
+
required?: boolean; unique?: boolean; index?: boolean;
|
|
158
|
+
default?: unknown; // literal, function, or DefaultOperator
|
|
159
|
+
enum?: readonly (string | number)[];
|
|
160
|
+
min?: number | Date; max?: number | Date; // number, date
|
|
161
|
+
minLength?: number; maxLength?: number; // string
|
|
162
|
+
match?: RegExp; // string
|
|
163
|
+
validate?: (v: unknown) => boolean | string | Promise<boolean | string>; // string = error message
|
|
164
|
+
ref?: string; // objectId / objectId arrays → populate
|
|
165
|
+
of?: PrimitiveFieldType | ModelSchema; // array item: primitive or embedded doc schema
|
|
166
|
+
fields?: ModelSchema; // typed embedded object (type: 'object')
|
|
167
|
+
sequence?: boolean | string; // auto-increment; Mongo efc_counters / PG SEQUENCE
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// A field: FieldDefinition | nested ModelSchema (embedded object shorthand) | [ModelSchema] (array of embedded docs)
|
|
171
|
+
type SchemaField = FieldDefinition | ModelSchema | [ModelSchema] | readonly [ModelSchema];
|
|
172
|
+
interface ModelSchema { [field: string]: SchemaField }
|
|
173
|
+
|
|
174
|
+
type DefaultOperator = '$now' | '$uuid' | '$objectId' | '$timestamp' | '$shortId' | '$currentUser' | `$currentUser.${string}`;
|
|
175
|
+
// '$increment' is NOT an operator — use `sequence`.
|
|
176
|
+
|
|
177
|
+
interface ModelOptions {
|
|
178
|
+
timestamps?: boolean | { createdAt?: string | false; updatedAt?: string | false }; // default true
|
|
179
|
+
indexes?: { fields: Record<string, 1 | -1 | 'text'>; unique?: boolean; expireAfterSeconds?: number; name?: string }[];
|
|
180
|
+
collection?: string; // collection/table name, default lowercase plural of the model name
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
interface FindOptions { populate?: string | string[]; select?: string[]; sort?: Record<string, 1 | -1 | 'asc' | 'desc'>; limit?: number; skip?: number }
|
|
184
|
+
|
|
185
|
+
// Filter<T>: equality (array fields: contains), $eq $ne $gt $gte $lt $lte $in $nin $exists $regex,
|
|
186
|
+
// $and / $or, dotted paths ('address.city'), `id` for the primary key. Typed — no casts.
|
|
187
|
+
// Update<T>: plain fields (= $set) and/or $set (dotted ok) $inc $push ({$each}) $pull $unset.
|
|
188
|
+
|
|
189
|
+
// Inferred: record type = required/default/sequence fields non-optional, enum → literal union,
|
|
190
|
+
// 'date' → Date (nested too, both engines), 'objectId' → string, untyped object/array → unknown.
|
|
191
|
+
interface ModelCRUD<T, TCreate = Partial<T>> {
|
|
192
|
+
readonly name: string;
|
|
193
|
+
find(filter?: Filter<T>, options?: FindOptions): Promise<ModelRecord<T>[]>;
|
|
194
|
+
findById(id: string, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>; // malformed id → null
|
|
195
|
+
findOne(filter: Filter<T>, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>;
|
|
196
|
+
exists(filter: Filter<T>): Promise<boolean>;
|
|
197
|
+
distinct(field: ScalarKeys<T>, filter?: Filter<T>): Promise<T[field][]>; // non-null, sorted; arrays/objects rejected
|
|
198
|
+
create(data: TCreate): Promise<ModelRecord<T>>;
|
|
199
|
+
createMany(data: TCreate[]): Promise<ModelRecord<T>[]>;
|
|
200
|
+
update(id: string, data: Update<T>): Promise<ModelRecord<T> | null>; // VALIDATES changed fields
|
|
201
|
+
updateOne(filter: Filter<T>, data: Update<T>): Promise<ModelRecord<T> | null>; // first match, one statement
|
|
202
|
+
updateMany(filter: Filter<T>, data: Update<T>): Promise<number>;
|
|
203
|
+
upsert(filter: Filter<T>, create: TCreate, update: Update<T>): Promise<ModelRecord<T>>; // filter NOT merged into create; 409 on create retried once as update
|
|
204
|
+
delete(id: string): Promise<void>;
|
|
205
|
+
deleteOne(filter: Filter<T>): Promise<ModelRecord<T> | null>; // returns the deleted record
|
|
206
|
+
deleteMany(filter: Filter<T>): Promise<number>;
|
|
207
|
+
count(filter?: Filter<T>): Promise<number>;
|
|
208
|
+
aggregate<R>(pipeline: object[]): Promise<R[]>; // MongoDB only — rejects on PostgreSQL
|
|
209
|
+
raw(): Promise<unknown>; // mongoose Model / Drizzle pgTable
|
|
210
|
+
sync(opts?: { dryRun?: boolean }): Promise<string[]>; // reconcile (auto on first use); returns changes / planned SQL
|
|
211
|
+
drop(): Promise<void>;
|
|
212
|
+
}
|
|
213
|
+
type ModelRecord<T> = T & { id: string };
|
|
214
|
+
// Errors: ModelValidationError (400, issues), duplicate unique → HttpError 409.
|
|
215
|
+
|
|
216
|
+
interface MigrationContext { db: unknown; engine: 'mongodb' | 'postgresql' } // passed to up/down/seed
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## `express-file-cluster/auth`
|
|
222
|
+
|
|
223
|
+
Source: `packages/core/src/auth/index.ts`
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
// Set cookie (http-only strategy)
|
|
227
|
+
async function issueToken(res: Response, payload: Record<string, unknown>): Promise<void>
|
|
228
|
+
|
|
229
|
+
// Clear cookie (http-only strategy)
|
|
230
|
+
function revokeToken(res: Response): void
|
|
231
|
+
|
|
232
|
+
// Return token string (localStorage strategy)
|
|
233
|
+
async function signToken(payload: Record<string, unknown>): Promise<string>
|
|
234
|
+
|
|
235
|
+
// Need ignite({ cache }). Every signed token carries jti + iat + efc_iat (ms).
|
|
236
|
+
async function revokeSession(req: Request, res?: Response): Promise<void> // denylist this token until exp
|
|
237
|
+
async function revokeAllSessions(userId: string | number): Promise<void> // reject tokens issued before now
|
|
238
|
+
|
|
239
|
+
// Express middleware — verifies JWT, attaches payload to req.user.
|
|
240
|
+
// Dual-purpose: bare it's just auth; called with role names it returns a
|
|
241
|
+
// middleware that also enforces payload.role (403 if it doesn't match).
|
|
242
|
+
interface RequireAuth {
|
|
243
|
+
(req: Request, res: Response, next: NextFunction): void;
|
|
244
|
+
(...roles: string[]): RequestHandler;
|
|
245
|
+
}
|
|
246
|
+
const requireAuth: RequireAuth
|
|
247
|
+
|
|
248
|
+
// Internal — called by ignite()
|
|
249
|
+
function configureAuth(config: { secret: string; strategy: AuthStrategy; expiresIn: string; cookieDomain?: string }): void
|
|
250
|
+
|
|
251
|
+
// Reads the JWT payload requireAuth attached to the in-flight request, from
|
|
252
|
+
// anywhere in the async call chain (backed by AsyncLocalStorage — see context.ts).
|
|
253
|
+
// Returns undefined outside a request, or on a route that never ran requireAuth.
|
|
254
|
+
// Also what powers the '$currentUser'/'$currentUser.<key>' defineModel default codes.
|
|
255
|
+
function getCurrentUser(): Record<string, unknown> | undefined
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Cookie name: `efc_token`. Algorithm: HS256. Library: `jose`.
|
|
259
|
+
|
|
260
|
+
Every request run through `ignite()` is wrapped in its own `AsyncLocalStorage` context (`packages/core/src/context.ts`) before any other middleware runs; `requireAuth` populates it with the verified JWT payload. This DOES exist now — it's no longer accurate to say EFC has no request context (see `what-not-to-invent.md`, which has been updated).
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## `express-file-cluster/tasks`
|
|
265
|
+
|
|
266
|
+
Source: `packages/core/src/tasks/index.ts`
|
|
267
|
+
|
|
268
|
+
```ts
|
|
269
|
+
function defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
270
|
+
function defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
271
|
+
|
|
272
|
+
// Rejects: backend not configured | unknown task | backend unreachable within tasks.enqueueTimeout
|
|
273
|
+
async function enqueue<T>(name: string, payload: T): Promise<void>
|
|
274
|
+
|
|
275
|
+
interface TaskOptions {
|
|
276
|
+
thread?: boolean; // run in worker_threads
|
|
277
|
+
retries?: number; // re-runs; up to retries + 1 attempts. Default 3
|
|
278
|
+
backoff?: 'fixed' | 'exponential'; // 1 s base. Default 'exponential'
|
|
279
|
+
concurrency?: number;
|
|
280
|
+
schedule?: string; // cron; scheduled runs get payload {}
|
|
281
|
+
timezone?: string; // IANA tz for schedule
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
// Internal
|
|
285
|
+
function registerTask(name: string, def: TaskDefinition): void
|
|
286
|
+
function setEnqueueImpl(impl: (name: string, payload: unknown) => Promise<void>): void
|
|
287
|
+
const taskRegistry: Map<string, TaskDefinition>
|
|
288
|
+
function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## `ignite()` does NOT read app config from `process.env` — `NODE_ENV` is the one exception
|
|
294
|
+
|
|
295
|
+
`ignite()` never reads `PORT`, `DATABASE_URL`, `JWT_SECRET`, `JWT_EXPIRES_IN`, `COOKIE_DOMAIN`, or `CORS_ORIGINS` itself. Each must be passed explicitly in the `EFCConfig` object — the scaffolder generates an `efc.config.ts` that reads `process.env.X` for each of these and builds that object; `src/index.ts` just spreads it into `ignite()`. See `what-not-to-invent.md` for the full "does not auto-read" list.
|
|
296
|
+
|
|
297
|
+
| Config field | Typically wired from | Fallback if unset |
|
|
298
|
+
|---|---|---|
|
|
299
|
+
| `port` | `process.env.PORT` | `3000` |
|
|
300
|
+
| `databaseUrl` | `process.env.DATABASE_URL` | none (no DB connects) |
|
|
301
|
+
| `jwtSecret` | `process.env.JWT_SECRET` | none (auth disabled) |
|
|
302
|
+
| `jwtExpiresIn` | `process.env.JWT_EXPIRES_IN` | `'7d'` |
|
|
303
|
+
| `cookieDomain` | `process.env.COOKIE_DOMAIN` | unset (host-only cookie) |
|
|
304
|
+
| `cors.origin` | `process.env.CORS_ORIGINS?.split(',')` | `true` (allow all) |
|
|
305
|
+
| `tasks.redisUrl` | `process.env.REDIS_URL` | `'redis://localhost:6379'` |
|
|
306
|
+
| `tasks.connectionString` (pg-boss) | — | `databaseUrl` |
|
|
307
|
+
|
|
308
|
+
`NODE_ENV` is the sole exception — a Node/Express-wide runtime-mode signal, not an app secret — and is still read directly via `process.env['NODE_ENV']` in three places: `ignite()`'s cluster-in-production default, the dev-only dashboard toggle, and the `http-only` auth strategy's cookie `Secure` flag.
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# EFC — Auth Internals (Exact)
|
|
2
|
+
|
|
3
|
+
Source: `packages/core/src/auth/index.ts`
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Configuration (happens in Pre-Flight)
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// Called by ignite() at Pre-Flight step 2
|
|
11
|
+
configureAuth({
|
|
12
|
+
secret: jwtSecret,
|
|
13
|
+
strategy: authStrategy, // 'http-only' | 'localStorage'
|
|
14
|
+
expiresIn: JWT_EXPIRES_IN ?? '7d',
|
|
15
|
+
cookieDomain: COOKIE_DOMAIN, // optional
|
|
16
|
+
})
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`_config` is a module-level singleton. All auth functions throw `'[EFC] Auth not configured — pass jwtSecret to ignite()'` if called before `configureAuth`.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## `issueToken(res, payload)`
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
// Signs JWT (HS256), sets HttpOnly cookie
|
|
27
|
+
const token = await new SignJWT(payload)
|
|
28
|
+
.setProtectedHeader({ alg: 'HS256' })
|
|
29
|
+
.setExpirationTime(expiresIn)
|
|
30
|
+
.sign(new TextEncoder().encode(secret))
|
|
31
|
+
|
|
32
|
+
res.cookie('efc_token', token, {
|
|
33
|
+
httpOnly: true,
|
|
34
|
+
secure: process.env['NODE_ENV'] === 'production',
|
|
35
|
+
sameSite: 'strict',
|
|
36
|
+
...(cookieDomain && { domain: cookieDomain }),
|
|
37
|
+
})
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Cookie name: exactly `'efc_token'` (hardcoded).
|
|
41
|
+
`secure` is only set in production. In dev, the cookie is sent over HTTP.
|
|
42
|
+
**Does NOT set `path` explicitly** — defaults to `/`.
|
|
43
|
+
**Does NOT set `maxAge` or `expires`** — cookie is session-scoped (expires when browser closes), but the JWT itself has an expiry enforced server-side by `jwtVerify`.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## `revokeToken(res)`
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
res.clearCookie('efc_token')
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
That's the entire implementation. Clears the cookie. The JWT itself is not invalidated — use `revokeSession` for that.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Session revocation (`revokeSession`, `revokeAllSessions`) — needs `cache`
|
|
58
|
+
|
|
59
|
+
Every signed token now carries `jti` (randomUUID), `iat`, and `efc_iat` (ms) — via the shared `sign()` used by
|
|
60
|
+
both `issueToken` and `signToken`.
|
|
61
|
+
|
|
62
|
+
- `revokeSession(req, res?)`: verifies the request's token, sets cache key `sess:jti:<jti>` with TTL = `exp - now`;
|
|
63
|
+
clears the cookie when `res` is given and strategy is http-only. Throws if no cache / cache unreachable.
|
|
64
|
+
- `revokeAllSessions(userId)`: sets `sess:user:<id>` = `Date.now()` with TTL = `jwtExpiresIn` in seconds.
|
|
65
|
+
- `requireAuth` (only when a cache is configured): after `jwtVerify`, rejects with 401 if `sess:jti:<jti>` exists,
|
|
66
|
+
or if `efc_iat` (fallback `iat*1000`) < the user's cutoff. User id = `payload.sub ?? payload.id`.
|
|
67
|
+
If the cache read throws → `cache.onRevocationCheckError`: `'reject'` (default) → **503**
|
|
68
|
+
`{ error: 'Service Unavailable', statusCode: 503 }`; `'allow'` → request passes. Logged at most every 30 s.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## `signToken(payload)`
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
// Signs JWT, returns string (no cookie)
|
|
76
|
+
return await new SignJWT(payload)
|
|
77
|
+
.setProtectedHeader({ alg: 'HS256' })
|
|
78
|
+
.setExpirationTime(expiresIn)
|
|
79
|
+
.sign(new TextEncoder().encode(secret))
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
No `res` argument. Token must be sent in the response body by the route handler.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## `requireAuth` — middleware internals
|
|
87
|
+
|
|
88
|
+
`requireAuth` is dual-purpose, dispatched at runtime on the first argument:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
// Bare — Express calls it as (req, res, next). First arg is an object → auth-only path.
|
|
92
|
+
export const middlewares = [requireAuth];
|
|
93
|
+
|
|
94
|
+
// Role-checked — called by user code with string args first, returns a new
|
|
95
|
+
// RequestHandler that Express later invokes as (req, res, next).
|
|
96
|
+
export const middlewares = [requireAuth('admin')]; // any of these roles
|
|
97
|
+
export const middlewares = [requireAuth('user', 'admin')]; // multiple allowed
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
// Strategy 'http-only': reads req.cookies.efc_token
|
|
102
|
+
// Strategy 'localStorage': reads Authorization header → strips 'Bearer '
|
|
103
|
+
|
|
104
|
+
if (!token) → res.status(401).json({ error: 'Unauthorized' }); return
|
|
105
|
+
|
|
106
|
+
const { payload } = await jwtVerify(token, new TextEncoder().encode(secret))
|
|
107
|
+
|
|
108
|
+
// only when called with role names:
|
|
109
|
+
if (roles.length > 0 && !roles.includes(payload.role)) →
|
|
110
|
+
res.status(403).json({ error: 'Forbidden' }); return
|
|
111
|
+
|
|
112
|
+
(req as any).user = payload // ← attaches to req.user
|
|
113
|
+
next()
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
On any auth error (expired, invalid signature, malformed, missing token): catches and returns `{ error: 'Unauthorized' }` with status 401. A role mismatch returns `{ error: 'Forbidden' }` with status 403 instead. **Does NOT call next(err)** in either case — it handles the response itself and returns.
|
|
117
|
+
|
|
118
|
+
`req.user` is typed as `unknown` in the source. Cast to your payload type or use `(req as any).user`.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## JWT library
|
|
123
|
+
|
|
124
|
+
Uses `jose` (not `jsonwebtoken`). Key is UTF-8 encoded via `new TextEncoder().encode(secret)` before every call — no pre-computed key object is cached between requests.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Token expiry
|
|
129
|
+
|
|
130
|
+
`expiresIn` is passed into `configureAuth` as a plain string by `ignite()` (`config.jwtExpiresIn ?? '7d'`) — `configureAuth` itself never touches `process.env`. All tokens issued in the same process lifetime use the same expiry value.
|
|
131
|
+
|
|
132
|
+
Format accepted by `jose`: `'15m'`, `'1h'`, `'7d'`, `'30d'`, integer seconds, etc.
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## What auth does NOT do
|
|
137
|
+
|
|
138
|
+
- No refresh tokens in the framework itself (the scaffolder can generate an app-level `/auth/refresh` route backed by a DB-stored token — that's app code, not a core export).
|
|
139
|
+
- No revocation without a `cache` configured (then `revokeToken` just clears the cookie and a copied token stays valid until it expires). With a cache: `revokeSession` / `revokeAllSessions`.
|
|
140
|
+
- No CSRF token — relies on `SameSite: Strict` for http-only strategy.
|
|
141
|
+
- No multi-strategy per-route override — `authStrategy` is global, set once in `ignite()`.
|