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 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)` callback. The
61
- second argument accepts Bun WebSocket options plus Rossa's optional
62
- `messageRateLimit`. If no port is provided, Rossa uses `3000`.
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 URL-encoded forms,
128
- query and form validation, rate limiting, sanitization, security headers,
129
- sessions, static files, timeouts, and URL validation. Define reusable custom
130
- guards with `createGuard`. See [`doc/guards.md`](doc/guards.md) for guard
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, database, and `Field`/`Scope` APIs. See
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