express-file-cluster 0.9.3 → 0.9.6
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/dist/auth/index.cjs +4 -5
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +7 -2
- package/dist/auth/index.d.ts +7 -2
- package/dist/auth/index.js +3 -4
- package/dist/{chunk-ATL4GYFU.js → chunk-2SETEVMO.js} +10 -8
- package/dist/{chunk-ATL4GYFU.js.map → chunk-2SETEVMO.js.map} +1 -1
- package/dist/{chunk-UBQYQPBU.js → chunk-45BWAR6P.js} +2 -2
- package/dist/{chunk-TYR2GZZE.cjs → chunk-6KHBJOLB.cjs} +13 -8
- package/dist/chunk-6KHBJOLB.cjs.map +1 -0
- package/dist/chunk-73XJUT2S.js +366 -0
- package/dist/chunk-73XJUT2S.js.map +1 -0
- package/dist/{chunk-UTM4PEVG.js → chunk-7ZESZG3J.js} +8 -3
- package/dist/chunk-7ZESZG3J.js.map +1 -0
- package/dist/{chunk-R34R7QPD.cjs → chunk-DCJOWFVD.cjs} +3 -3
- package/dist/{chunk-R34R7QPD.cjs.map → chunk-DCJOWFVD.cjs.map} +1 -1
- package/dist/chunk-DUADUR6R.cjs +366 -0
- package/dist/chunk-DUADUR6R.cjs.map +1 -0
- package/dist/{chunk-T4OHFU5T.cjs → chunk-FMA76PRH.cjs} +8 -8
- package/dist/{chunk-T4OHFU5T.cjs.map → chunk-FMA76PRH.cjs.map} +1 -1
- package/dist/{chunk-RS4MXCPW.js → chunk-NI2BNGGV.js} +2 -2
- package/dist/{chunk-RRQ2RK5M.js → chunk-OFA7OGN5.js} +26 -6
- package/dist/chunk-OFA7OGN5.js.map +1 -0
- package/dist/{chunk-ANUSWEAP.cjs → chunk-RGT4ZVHL.cjs} +17 -15
- package/dist/chunk-RGT4ZVHL.cjs.map +1 -0
- package/dist/{chunk-X2US4RAM.cjs → chunk-TYCYYLLM.cjs} +11 -13
- package/dist/chunk-TYCYYLLM.cjs.map +1 -0
- package/dist/{chunk-QKQZF573.js → chunk-ULWNHN6P.js} +4 -6
- package/dist/{chunk-QKQZF573.js.map → chunk-ULWNHN6P.js.map} +1 -1
- package/dist/{chunk-RTF7PHS2.cjs → chunk-VWSUQKCJ.cjs} +116 -96
- package/dist/chunk-VWSUQKCJ.cjs.map +1 -0
- package/dist/cli/db-runner.cjs +20 -22
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +4 -6
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +70 -35
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +50 -15
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +10 -8
- package/dist/docs/api-reference/ignite.md +13 -3
- package/dist/docs/cli/add.md +1 -1
- package/dist/docs/contributing/index.md +1 -1
- package/dist/docs/getting-started/index.md +1 -1
- package/dist/docs/guides/authentication.md +34 -24
- package/dist/docs/guides/database.md +12 -0
- package/dist/docs/guides/oauth.md +15 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/skills/SKILL.md +2 -2
- package/dist/docs/skills/api-surface.md +5 -4
- package/dist/docs/skills/auth-internals.md +3 -3
- package/dist/docs/versioning.md +42 -0
- package/dist/index.cjs +73 -49
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +36 -12
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-DSO3QTNK.cjs +14 -0
- package/dist/{pgboss-backend-TCHI7CHM.cjs.map → pgboss-backend-DSO3QTNK.cjs.map} +1 -1
- package/dist/{pgboss-backend-QKBXVJ6B.js → pgboss-backend-I6DFUNRM.js} +3 -3
- package/dist/registry/index.json +22 -3
- package/dist/registry/js-mongo/account-security.json +1 -1
- package/dist/registry/js-mongo/admin-users.json +1 -1
- package/dist/registry/js-mongo/auth.json +1 -1
- package/dist/registry/js-mongo/auth@apple.json +1 -1
- package/dist/registry/js-mongo/auth@google.json +1 -1
- package/dist/registry/js-mongo/email-verification.json +1 -1
- package/dist/registry/js-mongo/forgot-password.json +1 -1
- package/dist/registry/js-mongo/user-profile.json +1 -1
- package/dist/registry/js-pg-model/account-security.json +1 -1
- package/dist/registry/js-pg-model/admin-users.json +1 -1
- package/dist/registry/js-pg-model/auth.json +1 -1
- package/dist/registry/js-pg-model/auth@apple.json +1 -1
- package/dist/registry/js-pg-model/auth@google.json +1 -1
- package/dist/registry/js-pg-model/email-verification.json +1 -1
- package/dist/registry/js-pg-model/forgot-password.json +1 -1
- package/dist/registry/js-pg-model/user-profile.json +1 -1
- package/dist/registry/js-pg-table/account-security.json +1 -1
- package/dist/registry/js-pg-table/admin-users.json +1 -1
- package/dist/registry/js-pg-table/auth.json +1 -1
- package/dist/registry/js-pg-table/auth@apple.json +1 -1
- package/dist/registry/js-pg-table/auth@google.json +1 -1
- package/dist/registry/js-pg-table/email-verification.json +1 -1
- package/dist/registry/js-pg-table/forgot-password.json +1 -1
- package/dist/registry/js-pg-table/user-profile.json +1 -1
- package/dist/registry/ts-mongo/account-security.json +1 -1
- package/dist/registry/ts-mongo/admin-users.json +1 -1
- package/dist/registry/ts-mongo/auth.json +1 -1
- package/dist/registry/ts-mongo/auth@apple.json +1 -1
- package/dist/registry/ts-mongo/auth@google.json +1 -1
- package/dist/registry/ts-mongo/email-verification.json +1 -1
- package/dist/registry/ts-mongo/forgot-password.json +1 -1
- package/dist/registry/ts-mongo/user-profile.json +1 -1
- package/dist/registry/ts-pg-model/account-security.json +1 -1
- package/dist/registry/ts-pg-model/admin-users.json +1 -1
- package/dist/registry/ts-pg-model/auth.json +1 -1
- package/dist/registry/ts-pg-model/auth@apple.json +1 -1
- package/dist/registry/ts-pg-model/auth@google.json +1 -1
- package/dist/registry/ts-pg-model/email-verification.json +1 -1
- package/dist/registry/ts-pg-model/forgot-password.json +1 -1
- package/dist/registry/ts-pg-model/user-profile.json +1 -1
- package/dist/registry/ts-pg-table/account-security.json +1 -1
- package/dist/registry/ts-pg-table/admin-users.json +1 -1
- package/dist/registry/ts-pg-table/auth.json +1 -1
- package/dist/registry/ts-pg-table/auth@apple.json +1 -1
- package/dist/registry/ts-pg-table/auth@google.json +1 -1
- package/dist/registry/ts-pg-table/email-verification.json +1 -1
- package/dist/registry/ts-pg-table/forgot-password.json +1 -1
- package/dist/registry/ts-pg-table/user-profile.json +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/{types-BY-ObnZH.d.cts → types-DAsBKVM-.d.cts} +7 -1
- package/dist/{types-BY-ObnZH.d.ts → types-DAsBKVM-.d.ts} +7 -1
- package/package.json +1 -1
- package/dist/chunk-277BSYVH.js +0 -127
- package/dist/chunk-277BSYVH.js.map +0 -1
- package/dist/chunk-ANUSWEAP.cjs.map +0 -1
- package/dist/chunk-HXV543HZ.js +0 -177
- package/dist/chunk-HXV543HZ.js.map +0 -1
- package/dist/chunk-RRQ2RK5M.js.map +0 -1
- package/dist/chunk-RTF7PHS2.cjs.map +0 -1
- package/dist/chunk-TYR2GZZE.cjs.map +0 -1
- package/dist/chunk-UTM4PEVG.js.map +0 -1
- package/dist/chunk-VQSWSYK6.cjs +0 -177
- package/dist/chunk-VQSWSYK6.cjs.map +0 -1
- package/dist/chunk-X2US4RAM.cjs.map +0 -1
- package/dist/chunk-YL37D6KM.cjs +0 -127
- package/dist/chunk-YL37D6KM.cjs.map +0 -1
- package/dist/pgboss-backend-TCHI7CHM.cjs +0 -14
- /package/dist/{chunk-UBQYQPBU.js.map → chunk-45BWAR6P.js.map} +0 -0
- /package/dist/{chunk-RS4MXCPW.js.map → chunk-NI2BNGGV.js.map} +0 -0
- /package/dist/{pgboss-backend-QKBXVJ6B.js.map → pgboss-backend-I6DFUNRM.js.map} +0 -0
|
@@ -23,13 +23,13 @@ Auth must be configured before any of these functions are called. Configuration
|
|
|
23
23
|
|
|
24
24
|
## `issueToken(res, payload)`
|
|
25
25
|
|
|
26
|
-
Signs a JWT and
|
|
26
|
+
Signs a JWT and delivers it the way `authStrategy` says: with `'http-only'` it sets an `HttpOnly` cookie and resolves `undefined`; with `'bearer'` it sets no cookie and resolves the token, for you to put in the response body. Writing `res.json({ ...(token ? { token } : {}) })` makes one route work under both.
|
|
27
27
|
|
|
28
28
|
```ts
|
|
29
29
|
async function issueToken(
|
|
30
30
|
res: Response,
|
|
31
31
|
payload: Record<string, unknown>,
|
|
32
|
-
): Promise<
|
|
32
|
+
): Promise<string | undefined>
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
| Parameter | Type | Description |
|
|
@@ -37,7 +37,7 @@ async function issueToken(
|
|
|
37
37
|
| `res` | `Response` | Express response object |
|
|
38
38
|
| `payload` | `Record<string, unknown>` | JWT claims (e.g. `{ sub: user.id, role: user.role }`) |
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
With `'http-only'`, the cookie is named `efc_token` and is set with:
|
|
41
41
|
|
|
42
42
|
- `HttpOnly: true` — not accessible via `document.cookie`
|
|
43
43
|
- `Secure: true` — only sent over HTTPS (when `NODE_ENV === 'production'`)
|
|
@@ -52,11 +52,13 @@ import { issueToken } from 'express-file-cluster/auth';
|
|
|
52
52
|
|
|
53
53
|
export const POST = async (req, res) => {
|
|
54
54
|
const user = await verifyCredentials(req.body.email, req.body.password);
|
|
55
|
-
await issueToken(res, { sub: user.id, role: user.role });
|
|
56
|
-
res.json({ message: 'Logged in' });
|
|
55
|
+
const token = await issueToken(res, { sub: user.id, role: user.role });
|
|
56
|
+
res.json({ message: 'Logged in', ...(token ? { token } : {}) });
|
|
57
57
|
};
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
+
> Before 0.9.4, `issueToken` always set the cookie and resolved `undefined`, even with the Bearer strategy — bearer clients never received a token. Use the return value.
|
|
61
|
+
|
|
60
62
|
---
|
|
61
63
|
|
|
62
64
|
## `revokeToken(res)`
|
|
@@ -105,7 +107,7 @@ Every token EFC signs carries a `jti` and an issue time, which these checks use.
|
|
|
105
107
|
|
|
106
108
|
## `signToken(payload)`
|
|
107
109
|
|
|
108
|
-
Signs a JWT and returns the token string
|
|
110
|
+
Signs a JWT and returns the token string, whatever the strategy — for tokens you hand out yourself (e.g. to a service). For login, prefer `issueToken`, which follows `authStrategy`.
|
|
109
111
|
|
|
110
112
|
```ts
|
|
111
113
|
async function signToken(
|
|
@@ -126,7 +128,7 @@ export const POST = async (req, res) => {
|
|
|
126
128
|
};
|
|
127
129
|
```
|
|
128
130
|
|
|
129
|
-
|
|
131
|
+
A bearer client keeps the token in secure storage (Keychain / Keystore — not browser `localStorage`) and sends it on subsequent requests:
|
|
130
132
|
|
|
131
133
|
```http
|
|
132
134
|
Authorization: Bearer <token>
|
|
@@ -153,7 +155,7 @@ Behaviour depends on the configured `authStrategy`:
|
|
|
153
155
|
| Strategy | Token source |
|
|
154
156
|
|---|---|
|
|
155
157
|
| `'http-only'` | `req.cookies.efc_token` |
|
|
156
|
-
| `'localStorage'` | `Authorization: Bearer <token>` header |
|
|
158
|
+
| `'bearer'` (or the old name `'localStorage'`) | `Authorization: Bearer <token>` header |
|
|
157
159
|
|
|
158
160
|
**Route-level, auth only (protects all handlers in the file):**
|
|
159
161
|
|
|
@@ -34,7 +34,7 @@ interface EFCConfig {
|
|
|
34
34
|
databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number };
|
|
35
35
|
|
|
36
36
|
// Auth
|
|
37
|
-
authStrategy?: 'http-only' | 'localStorage'
|
|
37
|
+
authStrategy?: 'http-only' | 'bearer'; // 'localStorage' = old name for 'bearer'
|
|
38
38
|
jwtSecret?: string;
|
|
39
39
|
jwtExpiresIn?: string;
|
|
40
40
|
cookieDomain?: string;
|
|
@@ -167,6 +167,16 @@ databasePool: { max: 5, idleTimeoutMs: 30_000, connectionTimeoutMs: 5_000 },
|
|
|
167
167
|
|
|
168
168
|
Unset options keep the driver's default. `efc db` commands use the defaults.
|
|
169
169
|
|
|
170
|
+
At boot, one process per machine logs the total — `workers × (max + 10 for pg-boss on the same database)` on PostgreSQL, `workers × max` on MongoDB. On PostgreSQL it compares that with the server's `max_connections` (minus the superuser reserve) and **warns** when this machine alone could exhaust it:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
[EFC] PostgreSQL connections: up to 110 from this machine (11 worker(s) × (pool 10)), but the server allows 97 …
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Several instances share the server, so multiply by the instance count — or put PgBouncer in front.
|
|
177
|
+
|
|
178
|
+
Failed connections name the fix instead of echoing the driver: a `DATABASE_URL` without a password, a wrong password, a missing database or role, a server that needs `?sslmode=require`, nothing listening at the host/port (PostgreSQL); a rejected login or an unreachable server (MongoDB). The password is never printed; the driver's error is kept as `cause`.
|
|
179
|
+
|
|
170
180
|
---
|
|
171
181
|
|
|
172
182
|
### `authStrategy`
|
|
@@ -176,9 +186,9 @@ How JWTs are delivered to clients:
|
|
|
176
186
|
| Value | Mechanism |
|
|
177
187
|
|---|---|
|
|
178
188
|
| `'http-only'` | `HttpOnly + Secure + SameSite=Strict` cookie named `efc_token` |
|
|
179
|
-
| `'
|
|
189
|
+
| `'bearer'` | `issueToken` returns the token for the response body; the client sends `Authorization: Bearer <token>` |
|
|
180
190
|
|
|
181
|
-
Default: `'http-only'`.
|
|
191
|
+
Default: `'http-only'`. Use `'http-only'` for browsers (websites and SPAs) and `'bearer'` for mobile/desktop apps and API clients — see [Choosing a strategy](../guides/authentication.md#choosing-a-strategy). `'localStorage'` is the pre-0.9.4 name for `'bearer'` and still works; any other value is treated as `'bearer'` with a startup warning (an error from 1.0).
|
|
182
192
|
|
|
183
193
|
---
|
|
184
194
|
|
package/dist/docs/cli/add.md
CHANGED
|
@@ -77,7 +77,7 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
77
77
|
```
|
|
78
78
|
feat(router): support catch-all wildcard routes
|
|
79
79
|
fix(cluster): prevent infinite respawn loop on startup crash
|
|
80
|
-
docs(auth): add
|
|
80
|
+
docs(auth): add bearer strategy example
|
|
81
81
|
chore(deps): upgrade jose to v5
|
|
82
82
|
```
|
|
83
83
|
|
|
@@ -41,7 +41,7 @@ On **PostgreSQL**, models default to [`defineTable`](../api-reference/table.md):
|
|
|
41
41
|
Depending on what you pick, you'll see follow-up questions:
|
|
42
42
|
|
|
43
43
|
- **Task queue backend.** `pg-boss` stores jobs in your PostgreSQL, so there's no Redis to run. `BullMQ` uses Redis (`REDIS_URL` in `.env`).
|
|
44
|
-
- **Authentication** (
|
|
44
|
+
- **Authentication** → `http-only cookie` (browsers — websites and SPAs, recommended), `Bearer token` (mobile/desktop apps, API clients), or `None` (add it later with `efc add auth`). Asked before the feature list; picking a strategy ticks the Authentication feature.
|
|
45
45
|
- **Sign in with Google / Apple** → the OAuth client credentials (Apple: Services ID, Team ID, Key ID and the path to your `.p8` key). See [Sign in with Google & Apple](../guides/oauth.md).
|
|
46
46
|
- **Email client** → pick an email provider: `Gmail` (preconfigured `smtp.gmail.com`, no host or port to type) or `Other (custom SMTP)` (asks for host + port). Either way you're then asked for the sending email address and password. **For Gmail this must be a 16-character App Password, not your normal Gmail password.** The prompt rejects anything that isn't 16 characters. See [Mailer](../guides/mailer.md) for the full walkthrough, including how to generate an App Password.
|
|
47
47
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Authentication Guide
|
|
2
2
|
|
|
3
|
-
EFC ships a complete JWT authentication system. Choose between two delivery strategies depending on your
|
|
3
|
+
EFC ships a complete JWT authentication system. Choose between two delivery strategies depending on who your clients are.
|
|
4
4
|
|
|
5
5
|
> Ready-made routes: `efc add auth` (register / login / logout / me) and `efc add auth@google` / `auth@apple` ([Sign in with Google & Apple](./oauth.md)). See [efc add](../cli/add.md).
|
|
6
6
|
|
|
@@ -8,21 +8,28 @@ EFC ships a complete JWT authentication system. Choose between two delivery stra
|
|
|
8
8
|
|
|
9
9
|
## Choosing a strategy
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The question is **who the client is**, not "website or app":
|
|
12
|
+
|
|
13
|
+
| | `http-only` (default) | `bearer` |
|
|
12
14
|
|---|---|---|
|
|
13
|
-
| **
|
|
14
|
-
| **
|
|
15
|
-
| **
|
|
16
|
-
| **
|
|
17
|
-
|
|
|
15
|
+
| **For** | Browsers — websites **and** SPAs (React, Vue, …) | Mobile / desktop apps, CLIs, server-to-server API clients |
|
|
16
|
+
| **Token travels as** | `HttpOnly` cookie | `Authorization: Bearer <token>` header |
|
|
17
|
+
| **Client stores it in** | Nothing — the browser handles the cookie | iOS Keychain / Android Keystore / OS credential store |
|
|
18
|
+
| **XSS** | Script can't read the token | A token kept in browser `localStorage` can be stolen by any script on the page |
|
|
19
|
+
| **CSRF** | Mitigated by `SameSite=Strict` | Not applicable (no cookie) |
|
|
20
|
+
| **`requireAuth` reads** | `req.cookies.efc_token` | the `Authorization` header |
|
|
21
|
+
|
|
22
|
+
Pick `http-only` for anything that runs in a browser — including SPAs. `bearer` is for clients that have no cookie jar (native apps) or that call the API on behalf of something else. The one browser case for `bearer` is an SPA on a completely different site than the API, where cookies would need `SameSite=None` and credentialed CORS.
|
|
18
23
|
|
|
19
|
-
|
|
24
|
+
`create-efc-app` asks this up front; `efc add auth` asks it too and writes the answer to `efc.config`. To switch later, change one line — the generated routes work with both:
|
|
20
25
|
|
|
21
26
|
```ts
|
|
22
|
-
|
|
23
|
-
|
|
27
|
+
// efc.config.ts
|
|
28
|
+
authStrategy: 'http-only', // or 'bearer'
|
|
24
29
|
```
|
|
25
30
|
|
|
31
|
+
> `'localStorage'` is the pre-0.9.4 name for `'bearer'` and still works. Any other value is treated as `'bearer'` and logs a warning at startup; from 1.0 it's an error.
|
|
32
|
+
|
|
26
33
|
---
|
|
27
34
|
|
|
28
35
|
## `http-only` strategy
|
|
@@ -90,15 +97,17 @@ export const GET = async (req, res) => {
|
|
|
90
97
|
|
|
91
98
|
---
|
|
92
99
|
|
|
93
|
-
## `
|
|
100
|
+
## `bearer` strategy
|
|
94
101
|
|
|
95
102
|
### Login
|
|
96
103
|
|
|
104
|
+
`issueToken` hands the token back instead of setting a cookie, so the same route serves both strategies:
|
|
105
|
+
|
|
97
106
|
```ts
|
|
98
107
|
// src/api/auth/login.ts
|
|
99
108
|
import type { Request, Response } from 'express';
|
|
100
109
|
import { HttpError } from 'express-file-cluster';
|
|
101
|
-
import {
|
|
110
|
+
import { issueToken, verifyPassword } from 'express-file-cluster/auth';
|
|
102
111
|
import { User } from '../../model/User.js';
|
|
103
112
|
|
|
104
113
|
export const POST = async (req: Request, res: Response) => {
|
|
@@ -107,27 +116,28 @@ export const POST = async (req: Request, res: Response) => {
|
|
|
107
116
|
throw new HttpError(401, 'Invalid credentials');
|
|
108
117
|
}
|
|
109
118
|
|
|
110
|
-
|
|
111
|
-
res
|
|
119
|
+
// http-only: sets the cookie, returns undefined. bearer: returns the token.
|
|
120
|
+
const token = await issueToken(res, { sub: user.id, role: user.role });
|
|
121
|
+
res.json({ message: 'Logged in', ...(token ? { token } : {}) });
|
|
112
122
|
};
|
|
113
123
|
```
|
|
114
124
|
|
|
115
|
-
The
|
|
125
|
+
The scaffolded login and `/auth/refresh` routes also return `refreshToken` in bearer mode; post it back as `{ refreshToken }` to `/auth/refresh` for a new pair. Google/Apple sign-in never puts the JWT in a URL: the app starts it with a PKCE `code_challenge`, gets `OAUTH_SUCCESS_REDIRECT#code=<code>` back and posts `{ code, code_verifier }` to `/auth/oauth/exchange` for the token. The code works once, for 60 seconds, and only with the app's verifier — see [Sign in with Google & Apple](./oauth.md#bearer-apps-mobile--desktop).
|
|
116
126
|
|
|
117
|
-
|
|
118
|
-
// frontend
|
|
119
|
-
const { token } = await fetch('/auth/login', { method: 'POST', body: ... }).then(r => r.json());
|
|
120
|
-
localStorage.setItem('authToken', token);
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
And attaches it on protected requests:
|
|
127
|
+
The client keeps the token in secure storage and sends it on every request:
|
|
124
128
|
|
|
125
129
|
```js
|
|
126
|
-
|
|
127
|
-
|
|
130
|
+
// React Native (expo-secure-store); on iOS/Android natively: Keychain / Keystore
|
|
131
|
+
const { token } = await fetch(`${API}/auth/login`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) }).then(r => r.json());
|
|
132
|
+
await SecureStore.setItemAsync('token', token);
|
|
133
|
+
|
|
134
|
+
await fetch(`${API}/profile`, {
|
|
135
|
+
headers: { Authorization: `Bearer ${await SecureStore.getItemAsync('token')}` },
|
|
128
136
|
});
|
|
129
137
|
```
|
|
130
138
|
|
|
139
|
+
Avoid browser `localStorage` for the token — that's what `http-only` is for.
|
|
140
|
+
|
|
131
141
|
### Protecting routes
|
|
132
142
|
|
|
133
143
|
Identical to `http-only` — `requireAuth` reads from the correct source based on the configured strategy:
|
|
@@ -115,6 +115,18 @@ Filters, sorting and pagination behave the same on both engines.
|
|
|
115
115
|
|
|
116
116
|
---
|
|
117
117
|
|
|
118
|
+
### Check request values before they reach a filter
|
|
119
|
+
|
|
120
|
+
Filters accept operator objects, and JSON bodies (and `?a[b]=c` query strings) can carry objects where you expect a string. Check the type of anything from `req.body` / `req.query` before using it in a lookup:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
const { refreshToken } = req.body;
|
|
124
|
+
if (typeof refreshToken !== 'string') return res.status(400).json({ error: 'Invalid refresh token' });
|
|
125
|
+
const user = await User.findOne({ refreshToken });
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
— or validate the body with `export const schema` ([validation](./validation.md)), which replaces it with the parsed, typed output.
|
|
129
|
+
|
|
118
130
|
## Writing
|
|
119
131
|
|
|
120
132
|
```ts
|
|
@@ -61,7 +61,21 @@ Send the browser (not `fetch`) to the start route:
|
|
|
61
61
|
|
|
62
62
|
After the provider sends the user back, the callback sets the usual `efc_token` cookie (the same one `/auth/login` sets) and redirects to `OAUTH_SUCCESS_REDIRECT`. From there, requests with credentials work as after a password login, and `GET /auth/me` returns the user.
|
|
63
63
|
|
|
64
|
-
>
|
|
64
|
+
> With `authStrategy: 'http-only'` the callbacks set the session cookie and redirect to `OAUTH_SUCCESS_REDIRECT`. With `'bearer'` they redirect to `OAUTH_SUCCESS_REDIRECT#code=<code>` instead — a one-time code, never the JWT itself (URLs end up in history, logs and screenshots).
|
|
65
|
+
|
|
66
|
+
### Bearer apps (mobile / desktop)
|
|
67
|
+
|
|
68
|
+
The app proves it's the one that started the sign-in with PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)), so another app that registers the same `myapp://` link and catches the redirect can't use the code:
|
|
69
|
+
|
|
70
|
+
1. Make a random `code_verifier` (43–128 characters, e.g. 32 random bytes as base64url) and keep it in memory.
|
|
71
|
+
2. Open `/auth/google?code_challenge=<base64url(SHA-256(code_verifier))>` (or `/auth/apple?…`) in the system browser (`ASWebAuthenticationSession`, Custom Tabs).
|
|
72
|
+
3. `OAUTH_SUCCESS_REDIRECT` (e.g. `myapp://signed-in`) receives `#code=<code>`. Trade it within 60 seconds:
|
|
73
|
+
|
|
74
|
+
```http
|
|
75
|
+
POST /auth/oauth/exchange { "code": "<code>", "code_verifier": "<code_verifier>" } → 200 { "token": "<jwt>" }
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The code works once — a second use, even a simultaneous one, gets 400. A wrong verifier gets 400 without using the code up. Without a `code_challenge`, bearer sign-in stops with 400 at the callback. The code lives in `cache`: with several instances, use Redis (`REDIS_URL`).
|
|
65
79
|
|
|
66
80
|
---
|
|
67
81
|
|
package/dist/docs/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
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
4
|
|
|
5
|
-
> **Status: v0.9.
|
|
5
|
+
> **Status: v0.9.6 — 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 and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, migrations (written for you from model changes: `efc db generate`, plus `efc db pull` and `efc import-prisma`), and the `efc add` feature registry (auth, admin, billing… copied into your app as source you own) are all implemented.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
| [Guides](./guides/authentication.md) | Deep-dives: auth, OAuth, database, RBAC, mailer, error handling, deployment |
|
|
30
30
|
| [CLI](./cli/index.md) | All `efc` commands with flags and examples |
|
|
31
31
|
| [Contributing](./contributing/index.md) | Roadmap, branch conventions, PR requirements |
|
|
32
|
+
| [Versioning & support](./versioning.md) | What patch/minor/major may contain, LTS from 1.0, supported Node versions, security reports |
|
|
32
33
|
|
|
33
34
|
### Guides
|
|
34
35
|
|
|
@@ -37,8 +37,8 @@ Load **only** the module the work points to. Each is self-contained.
|
|
|
37
37
|
docs/ ← full documentation
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
## Status (v0.9.
|
|
40
|
+
## Status (v0.9.6 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
|
|
41
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 +
|
|
42
|
+
Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only cookie + Bearer token auth (scrypt password hashing built in), structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, PostgreSQL-native `defineTable` (Prisma-style queries, foreign keys, many-to-many, `include`, relation filters, nested writes), MongoDB-native `defineCollection` (mongoose vocabulary, BSON types, geo/text, `bulkWrite`, change streams), query logging (`logging.queries`), BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`) incl. migrations generated from model diffs (`efc db generate`), `efc db pull` and `efc import-prisma`, full CLI.
|
|
43
43
|
|
|
44
44
|
**Not yet implemented (Phase 3+):** WebSockets, plugins, OpenAPI generation, OpenTelemetry, `efc lint`, `efc deploy`.
|
|
@@ -100,7 +100,7 @@ interface EFCConfig {
|
|
|
100
100
|
database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
|
|
101
101
|
databaseUrl?: string;
|
|
102
102
|
databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number }; // per worker
|
|
103
|
-
authStrategy?: 'http-only' | 'localStorage';
|
|
103
|
+
authStrategy?: 'http-only' | 'bearer'; // default 'http-only'; 'localStorage' = old name for 'bearer'; anything else = bearer + warning (error in 1.0)
|
|
104
104
|
jwtSecret?: string;
|
|
105
105
|
jwtExpiresIn?: string; // default '7d'
|
|
106
106
|
cookieDomain?: string;
|
|
@@ -233,13 +233,14 @@ interface MigrationContext { db: unknown; engine: 'mongodb' | 'postgresql' } //
|
|
|
233
233
|
Source: `packages/core/src/auth/index.ts`
|
|
234
234
|
|
|
235
235
|
```ts
|
|
236
|
-
//
|
|
237
|
-
|
|
236
|
+
// http-only: sets the efc_token cookie, resolves undefined. bearer: no cookie, resolves the token.
|
|
237
|
+
// One route for both: const token = await issueToken(res, p); res.json({ ...(token ? { token } : {}) })
|
|
238
|
+
async function issueToken(res: Response, payload: Record<string, unknown>): Promise<string | undefined>
|
|
238
239
|
|
|
239
240
|
// Clear cookie (http-only strategy)
|
|
240
241
|
function revokeToken(res: Response): void
|
|
241
242
|
|
|
242
|
-
//
|
|
243
|
+
// Always returns the token string, no cookie (any strategy)
|
|
243
244
|
async function signToken(payload: Record<string, unknown>): Promise<string>
|
|
244
245
|
|
|
245
246
|
// Need ignite({ cache }). Every signed token carries jti + iat + efc_iat (ms).
|
|
@@ -10,7 +10,7 @@ Source: `packages/core/src/auth/index.ts`
|
|
|
10
10
|
// Called by ignite() at Pre-Flight step 2
|
|
11
11
|
configureAuth({
|
|
12
12
|
secret: jwtSecret,
|
|
13
|
-
strategy: authStrategy, // 'http-only' | 'localStorage'
|
|
13
|
+
strategy: authStrategy, // 'http-only' | 'bearer' ('localStorage' = old name); anything else = bearer + startup warning (error in 1.0)
|
|
14
14
|
expiresIn: JWT_EXPIRES_IN ?? '7d',
|
|
15
15
|
cookieDomain: COOKIE_DOMAIN, // optional
|
|
16
16
|
})
|
|
@@ -23,7 +23,7 @@ configureAuth({
|
|
|
23
23
|
## `issueToken(res, payload)`
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
|
-
// Signs JWT (HS256)
|
|
26
|
+
// Signs JWT (HS256). bearer → `return token` (no cookie). http-only → sets the cookie, returns undefined
|
|
27
27
|
const token = await new SignJWT(payload)
|
|
28
28
|
.setProtectedHeader({ alg: 'HS256' })
|
|
29
29
|
.setExpirationTime(expiresIn)
|
|
@@ -99,7 +99,7 @@ export const middlewares = [requireAuth('user', 'admin')]; // multiple allowed
|
|
|
99
99
|
|
|
100
100
|
```ts
|
|
101
101
|
// Strategy 'http-only': reads req.cookies.efc_token
|
|
102
|
-
// Strategy 'localStorage': reads Authorization header → strips 'Bearer '
|
|
102
|
+
// Strategy 'bearer' / 'localStorage': reads Authorization header → strips 'Bearer '
|
|
103
103
|
|
|
104
104
|
if (!token) → res.status(401).json({ error: 'Unauthorized' }); return
|
|
105
105
|
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Versioning & Support Policy
|
|
2
|
+
|
|
3
|
+
`express-file-cluster`, `create-efc-app` and `express-file-cluster-mcp` are released together under one version number, following [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## Before 1.0 (now: 0.x)
|
|
6
|
+
|
|
7
|
+
| Bump | Example | What it may contain |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| **Patch** | 0.9.4 → 0.9.5 | Bug fixes, security fixes, clearer errors, docs. No new public API. A fix can change behaviour that was wrong (e.g. a route that leaked data); the changelog says so and gives upgrade steps. |
|
|
10
|
+
| **Minor** | 0.9.x → 0.10.0 | New features and APIs. May include breaking changes — each one is listed in [`CHANGELOG.md`](https://github.com/pr4shxnt/efc.js/blob/main/CHANGELOG.md) with upgrade steps. |
|
|
11
|
+
|
|
12
|
+
Pin a minor range (`~0.9.5`) if you want fixes without features; `^0.9.5` behaves the same way on 0.x (npm treats the minor as the breaking digit).
|
|
13
|
+
|
|
14
|
+
Deprecations are announced at least one minor release before removal, with a startup warning where possible (e.g. an unknown `authStrategy` warns in 0.9.x and becomes an error in 1.0).
|
|
15
|
+
|
|
16
|
+
## From 1.0
|
|
17
|
+
|
|
18
|
+
- **Major** (1.x → 2.0): breaking changes only, each with upgrade steps.
|
|
19
|
+
- **Minor** (1.1 → 1.2): new features, backwards compatible.
|
|
20
|
+
- **Patch** (1.1.0 → 1.1.1): fixes and security fixes only.
|
|
21
|
+
- The three import paths (`express-file-cluster`, `/auth`, `/tasks`) and everything they export are the public API. Anything else — internal modules, generated file layouts, log message wording — can change in a minor.
|
|
22
|
+
|
|
23
|
+
## Long-term support (from 1.0)
|
|
24
|
+
|
|
25
|
+
| Line | Gets | For |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| **Current** major | Features, fixes, security fixes | Until the next major |
|
|
28
|
+
| **Previous** major | Security fixes and critical bug fixes | 12 months after the next major ships |
|
|
29
|
+
|
|
30
|
+
Before 1.0 only the latest 0.x minor gets fixes — upgrade to it to get them.
|
|
31
|
+
|
|
32
|
+
## Node.js
|
|
33
|
+
|
|
34
|
+
EFC supports the Node.js versions in **active or maintenance LTS** and is tested on **Node 22 and 24** in CI. A Node version that reaches end-of-life stops being supported in the next minor release. (`engines` still says `>=18`; it will be raised to the supported range at 1.0. Node 18 and 20 are end-of-life and untested — scaffolded apps' email client already needs Node 20+.)
|
|
35
|
+
|
|
36
|
+
## Generated code
|
|
37
|
+
|
|
38
|
+
`create-efc-app` and `efc add` copy source files into your app; after that the code is yours, and upgrading the framework doesn't change it. When a release fixes generated code, the changelog says which files and how — re-add an untouched file with `efc add <item>`, or a changed one with `efc add <item> --overwrite` (then reapply your edits), or apply the shown change by hand.
|
|
39
|
+
|
|
40
|
+
## Security
|
|
41
|
+
|
|
42
|
+
See [`SECURITY.md`](https://github.com/pr4shxnt/efc.js/blob/main/SECURITY.md) for how to report a vulnerability. Security fixes ship as patch releases and are marked **Security** in the changelog.
|