rossa 0.1.1 → 0.1.2
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/CHANGELOG.md +50 -0
- package/README.md +39 -10
- package/dist/index.d.ts +366 -25
- package/dist/index.js +27 -25
- package/package.json +3 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable changes to this project are documented here. The format is based on
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [0.1.2] - 2026-11-23
|
|
8
|
+
|
|
9
|
+
### ⚠️ Behavior change
|
|
10
|
+
|
|
11
|
+
- `sendError` no longer adds `Access-Control-Allow-Origin: *` to error responses,
|
|
12
|
+
so guard rejections are no longer readable by every origin in the browser.
|
|
13
|
+
Apps that relied on the wildcard must set the header explicitly — through the
|
|
14
|
+
`cors()` guard or through a guard's error config, e.g.
|
|
15
|
+
`{ headers: { "Access-Control-Allow-Origin": "..." } }`.
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- `serve()` hands the actually bound port to the ready callback and logs the
|
|
20
|
+
bound URL, so `port: 0` reports the OS-assigned port (and `https` with TLS)
|
|
21
|
+
instead of the configured value.
|
|
22
|
+
- `multipart()` preserves the MIME type declared on uploaded parts, so `File.type`
|
|
23
|
+
keeps its value instead of being empty.
|
|
24
|
+
- `validateUrl` also rejects path-traversal markers in the query string rather
|
|
25
|
+
than checking the path alone.
|
|
26
|
+
- `createGuard` honours a per-call `overrideConfig.code` over the guard default.
|
|
27
|
+
- Session and cookie lifetimes accept fractional days with millisecond
|
|
28
|
+
precision instead of truncating to whole days.
|
|
29
|
+
- A `MAX_COOKIE_SIZE` overflow no longer leaves an orphaned session record or
|
|
30
|
+
surfaces as an empty 500 response.
|
|
31
|
+
- Routes that combine `jwtAuth` and `jwtRefresh` no longer overwrite
|
|
32
|
+
`ctx.jwtData`, and a rejected refresh no longer consumes the refresh token.
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
|
|
36
|
+
- `urlencoded({ strict: true })` opt-in strict parsing mode.
|
|
37
|
+
- `json()` also populates `ctx.body` (alongside the existing `ctx.req._json`).
|
|
38
|
+
- `session({ auth, readonly })` mounts, `ctx.session.rotate()`, and a typed
|
|
39
|
+
`SessionContext<T>`.
|
|
40
|
+
- `jwtRotate` guard: verifies the access token and rotates the refresh token in
|
|
41
|
+
one step.
|
|
42
|
+
- Machine-readable refresh rejection reasons in `error_code`
|
|
43
|
+
(`invalid` | `expired` | `reused`).
|
|
44
|
+
- `WWW-Authenticate: Bearer` on JWT 401 responses.
|
|
45
|
+
- Per-call JWT lifetimes with `sign(payload, lifetimeSeconds?)`.
|
|
46
|
+
- Optional `deleteExpired(before)` hook on refresh-token stores for cleanup of
|
|
47
|
+
expired rows.
|
|
48
|
+
- Documented claim-once semantics for refresh-token stores (deleting the row or
|
|
49
|
+
marking it consumed are both valid).
|
|
50
|
+
- Guard rejection shapes documented in `doc/` and pinned by smoke tests.
|
package/README.md
CHANGED
|
@@ -57,9 +57,13 @@ any `basePath`, with parameter colons removed (for example `["/users/id"]`).
|
|
|
57
57
|
| `Encoding` | `"br"` | Response encoding; supports the `ContentEncodingType` values. |
|
|
58
58
|
|
|
59
59
|
`app.serve(serverOptions, websocketOptions)` starts Bun's server. The first
|
|
60
|
-
argument accepts Bun serve options plus an optional `fn(port)`
|
|
61
|
-
|
|
62
|
-
|
|
60
|
+
argument accepts Bun serve options plus an optional `fn(port, server)` ready
|
|
61
|
+
callback. It runs after Bun binds the socket, so `port` is the actual bound port
|
|
62
|
+
(including an OS-assigned ephemeral port when `port: 0`); the second argument is
|
|
63
|
+
the bound `Bun.Server`. Without `fn`, the startup log prints the bound URL,
|
|
64
|
+
including `https` when `tls` is set. The second argument accepts Bun WebSocket
|
|
65
|
+
options plus Rossa's optional `messageRateLimit`. If no port is provided, Rossa
|
|
66
|
+
uses `3000`.
|
|
63
67
|
|
|
64
68
|
`app.test(request, encoding?)` runs a `Request` through the same pipeline
|
|
65
69
|
without binding a socket. `app.registerWSS(...)` registers WebSocket
|
|
@@ -84,7 +88,9 @@ class Notes extends Methods {
|
|
|
84
88
|
|
|
85
89
|
Rossa supplies an inherited `options` handler for each declared path. It
|
|
86
90
|
returns `204` with an `Allow` header built from the methods registered for that
|
|
87
|
-
path
|
|
91
|
+
path, including `OPTIONS`. OPTIONS on an undeclared path returns `404`, and a
|
|
92
|
+
`HEAD` request without an implemented `head` handler also returns `404` — there
|
|
93
|
+
is no automatic GET fallback.
|
|
88
94
|
|
|
89
95
|
Useful response methods include `text`, `html`, `json`, `success`, `error`,
|
|
90
96
|
`redirect`, `null`, `file`, and `fileServer`. Route parameters are exposed as
|
|
@@ -124,11 +130,31 @@ The public entry point exports guard factories for authentication
|
|
|
124
130
|
(`authBearer`, `apiKey`, `auth`, `authorize`), caching (`smartCache`), content
|
|
125
131
|
type, cookies, CORS, CSRF, error boundaries (`errorHandler`), headers, IP
|
|
126
132
|
filtering, JSON body validation, required JSON keys (`keys`), JWT (`jwtAuth`,
|
|
127
|
-
`jwtRefresh`), logging (`logger`, `loggerFN`), multipart and
|
|
128
|
-
query and form validation, rate limiting, sanitization,
|
|
129
|
-
sessions, static files, timeouts, and URL validation. Define
|
|
130
|
-
guards with `createGuard`. See [`doc/guards.md`](doc/guards.md)
|
|
131
|
-
behavior and examples.
|
|
133
|
+
`jwtRefresh`, `jwtRotate`), logging (`logger`, `loggerFN`), multipart and
|
|
134
|
+
URL-encoded forms, query and form validation, rate limiting, sanitization,
|
|
135
|
+
security headers, sessions, static files, timeouts, and URL validation. Define
|
|
136
|
+
reusable custom guards with `createGuard`. See [`doc/guards.md`](doc/guards.md)
|
|
137
|
+
for guard behavior and examples.
|
|
138
|
+
|
|
139
|
+
Sessions accept the service or `{ auth, readonly }`, can be typed with
|
|
140
|
+
`session<TData>()` plus `SessionContext<TData>`, and expose
|
|
141
|
+
`ctx.session.rotate()` after login. JWT guards expose refresh claims in
|
|
142
|
+
`ctx.data.jwtRefreshData`, reject refresh failures with `error_code`
|
|
143
|
+
(`invalid`, `expired`, `reused`) and `WWW-Authenticate: Bearer`, and require
|
|
144
|
+
`jwtAuth` before `jwtRefresh` on combined routes.
|
|
145
|
+
|
|
146
|
+
### Rejection and response defaults
|
|
147
|
+
|
|
148
|
+
- `security()` adds `Referrer-Policy: strict-origin-when-cross-origin`,
|
|
149
|
+
`X-Content-Type-Options: nosniff`, and `X-Frame-Options: DENY`. CSP, HSTS, and
|
|
150
|
+
the other policies are opt-in.
|
|
151
|
+
- `sendError()` returns JSON `{ success: false, error }` and only the headers
|
|
152
|
+
you pass. **Behavior change:** it no longer adds
|
|
153
|
+
`Access-Control-Allow-Origin: *`; the `cors` guard owns CORS.
|
|
154
|
+
- The `errorHandler()` guard returns a plain-text `500`
|
|
155
|
+
`Internal Server Error`, not JSON.
|
|
156
|
+
- A per-call guard `code` overrides the factory default
|
|
157
|
+
(`createGuard(..., { code: 403 })(options, { code: 451 })` answers `451`).
|
|
132
158
|
|
|
133
159
|
## Static files
|
|
134
160
|
|
|
@@ -264,7 +290,10 @@ console.log(response.status, await response.text());
|
|
|
264
290
|
`src/index.ts` exports `Rossa` and its option types; `Methods`, `RouterManager`,
|
|
265
291
|
`route`, and `wss`; guard factories with `use` and `createGuard`; `ctx`, `Req`,
|
|
266
292
|
`Res`, and `sendError`; WebSocket classes and `WSSMAN`; MCP (`McpController`,
|
|
267
|
-
`McpServer`, `mcp`); authentication
|
|
293
|
+
`McpServer`, `mcp`); authentication (`JWTAuthService`, `JwtEngine`,
|
|
294
|
+
`SessionAuthInterface`, `ServerSide`, and the session/JWT types), database, and
|
|
295
|
+
`Field`/`Scope` APIs. `JWTAuthService.sign(payload, lifetimeSeconds?)` accepts a
|
|
296
|
+
per-call lifetime; the lower-level `JwtEngine.signSeconds` is exported too. See
|
|
268
297
|
[`doc/features.md`](doc/features.md) for names.
|
|
269
298
|
|
|
270
299
|
## Documentation and examples
|