@venizia/ignis-atlas 0.1.0 → 0.1.1-0

package/dist/corpus/changelogs/2026-09-25-mail-attachment-limits.md

@@ -0,0 +1,135 @@
+---
+title: Mail Attachments Read Only Under a Root, and Stop at a Size Limit
+description: "An attachment path is read only inside the new attachmentRoot option and refused without it, a text or html body must be a string, a new maxAttachmentBytes option (default 25 MB) caps the attachments of one message, and a failed send no longer echoes the raw error text."
+---
+
+# Changelog - 2026-09-25
+
+The mail component no longer reads a file or URL a caller names, and no longer buffers attachments without limit. Every change applies to every transport - Nodemailer, Mailgun and Amazon SES.
+
+| Change | Who is affected |
+|---|---|
+| [An attachment `path` is read only under `attachmentRoot`](#an-attachment-path-is-read-only-under-attachmentroot) | Applications that send an attachment by `path` |
+| [`text` and `html` must be strings](#text-and-html-must-be-strings) | Applications that pass anything but a string as the body |
+| [Attachments stop at `maxAttachmentBytes`](#attachments-stop-at-maxattachmentbytes) | Applications that send more than 25 MB of attachments in one message, or stream them |
+| [A failed send no longer echoes the raw error](#a-failed-send-no-longer-echoes-the-raw-error) | Code that reads the text of `core.mail.send_failed` |
+| [Every breaking change at a glance](#every-breaking-change-at-a-glance) | Everyone upgrading |
+
+## An attachment `path` is read only under `attachmentRoot`
+
+<Badge type="danger" text="Security" /> <Badge type="danger" text="Breaking" />
+
+**In one line.** `attachment.path` no longer reads any file the caller names - set `attachmentRoot`, or pass the bytes as `content`.
+
+Before, `{ path: '/etc/passwd' }` put that file on the email. An application that copied `attachments` from a request body let its caller mail any file the process could read. Nodemailer and the SES transport read `path` themselves; the Mailgun transport forwarded the `path` string as the attachment data.
+
+Now `MailService.send()` reads every attachment into `content` bytes before the transport sees it:
+
+- With no `attachmentRoot` set, any `path` is refused.
+- With `attachmentRoot` set, a `path` is resolved against it and refused if it lands outside. Symlinks and `..` are followed first, so neither can escape.
+- A missing file, a directory, a FIFO, an unreadable file and an escape all answer the same error and the same message, so a caller cannot probe which files exist.
+- Nodemailer's `href` (a URL) and `raw` sources are refused too. The Nodemailer transport also sets Nodemailer's own `disableFileAccess` and `disableUrlAccess`.
+- An attachment read from `path` keeps the file's name as `filename`, and gets a `contentType` from its extension, when you set neither.
+
+Every refusal is `400 core.mail.attachment_path_refused`. `attachmentRoot` must be an absolute path to an existing directory; anything else fails the application at startup with `Invalid mail options | attachmentRoot ...`.
+
+**Who is affected:** applications that send an attachment by `path`. Those sends now fail until you migrate. Messages with `content` attachments, or none, behave as before.
+
+**Migration.** Pick one:
+
+```typescript
+// Option 1 - keep path, and name the one directory it may read from
+this.component(MailComponent, {
+  options: {
+    provider: MailProviders.NODEMAILER,
+    config: { host, port, secure, auth },
+    attachmentRoot: '/srv/app/mail-assets',
+  },
+});
+
+await mailService.send({
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<img src="cid:logo">',
+  attachments: [{ path: 'logo.png', cid: 'logo' }], // relative to the root; filename and type follow from it
+});
+
+// Option 2 - pass the bytes yourself
+attachments: [{ filename: 'logo.png', content: await readFile('./assets/logo.png'), cid: 'logo' }], // readFile from node:fs/promises
+```
+
+An absolute `path` still works when it lies inside the root. A `path` is always a file name now: Nodemailer's `path: 'https://...'` (a URL fetch) and `path: 'data:...'` (a data URI) no longer work - fetch or decode the bytes yourself and pass them as `content`. A built-in transport called directly, outside `MailService`, has no root and refuses every `path`.
+
+See [Attachments](/extensions/components/mail/usage#attachments).
+
+## `text` and `html` must be strings
+
+<Badge type="danger" text="Security" /> <Badge type="danger" text="Breaking" />
+
+**In one line.** A body that is not a string - a `Buffer`, a stream, a number, `{ path }`, `{ href }`, any object - is refused. Pass the content itself as a string.
+
+Nodemailer treats `html: { path: '/etc/passwd' }` like an attachment path: it reads that file and sends it as the body. `IMailMessage` types `text` and `html` as strings, but a caller that forwards a request body is not bound by that type.
+
+Now `MailService.send()` refuses a `text` or `html` that is not a string with `400 core.mail.body_source_refused`, before any transport runs. The Nodemailer transport checks the same when called directly. `null` and `undefined` count as absent, so a body built from a database row with `html: null` still sends its `text`.
+
+**Who is affected:** code that passes a `Buffer`, a stream or any other non-string as the body. String bodies are unchanged.
+
+**Migration.** Pass the string: `html: buffer.toString('utf-8')`, or `html: await readFile('./templates/welcome.html', 'utf-8')`.
+
+## Attachments stop at `maxAttachmentBytes`
+
+<Badge type="tip" text="Enhancement" /> <Badge type="warning" text="Behavior Change" />
+
+**In one line.** A message's attachments may carry at most `maxAttachmentBytes` bytes, 25 MB by default.
+
+Before, every attachment was read whole into memory with no limit. A 200 MB attachment stayed resident for the whole send, with a base64 copy on top.
+
+The limit counts all attachments of one message together, so it also bounds each one:
+
+| Content | When it is checked |
+|---|---|
+| `Buffer`, `Uint8Array` or string | Before the send, by byte length |
+| File under `attachmentRoot` | By its size on disk before it is opened, then again while it is read - a file that grows in between is still capped |
+| Node `Readable` or web `ReadableStream` | Per chunk while it drains - the read stops as soon as the total passes the limit, and the rest is never buffered |
+
+Over the limit, `send()` throws `413 core.mail.attachment_too_large`. Any other `content` - `{ path }`, a number, a plain object - answers `400 core.mail.invalid_configuration` instead of a `500`. When a send is refused for any reason, every attachment stream it was given is destroyed, so no file descriptor stays open.
+
+`maxAttachmentBytes` must be a positive integer; anything else (`NaN`, `0`, `Infinity`, a string) fails the application at startup.
+
+**Who is affected:**
+
+- Applications that send more than 25 MB of attachments in one message. Raise the limit on the mail options.
+- Applications that pass streams to Nodemailer or Mailgun. Those transports now receive the stream's bytes, buffered whole (within the limit), instead of the stream itself.
+
+```typescript
+{
+  provider: MailProviders.AMAZON_SES,
+  config: { region: 'us-east-1' },
+  maxAttachmentBytes: 35 * 1024 * 1024,
+}
+```
+
+The limit counts decoded bytes. Base64 makes the message about 37% larger on the wire, so the 25 MB default becomes about 34 MB - over the 25 MB message cap of Gmail and of Mailgun. For those, set `maxAttachmentBytes: 18 * 1024 * 1024`. Plan memory for roughly four times `maxAttachmentBytes` per send in flight: the bytes, their base64 copy, and the built message. `sendBatch()` runs five sends at once by default.
+
+## A failed send no longer echoes the raw error
+
+<Badge type="danger" text="Security" /> <Badge type="warning" text="Behavior Change" />
+
+**In one line.** `core.mail.send_failed`, `core.mail.batch_send_failed` and `core.mail.verification_failed` now carry a fixed message; the original error moves to `cause`.
+
+Before, the message was `Failed to send email: <error text>`, and the error envelope sends it in every environment. A stream error such as `ENOENT: no such file or directory, open '/srv/...'` put a server path in the response. Now the message is `Failed to send email` (and `Failed to send batch emails`, `Mail transport verification failed`). The original error is logged, and rides in `cause`, which only a `development` response shows.
+
+**Who is affected:** code that parsed the text after `Failed to send email:`. Read `error.cause` instead.
+
+## Every breaking change at a glance
+
+| Before | Now | What to do |
+|---|---|---|
+| `attachment.path` read any file | Refused without `attachmentRoot`, and outside it | Set `attachmentRoot`, or pass `content` |
+| `path: 'https://...'` or `path: 'data:...'` (Nodemailer) | Refused - a `path` is a file under the root | Fetch or decode the bytes, pass `content` |
+| `href` and `raw` attachments (Nodemailer) | Refused | Pass `content` |
+| A built-in transport called directly read `path` | It refuses every `path` | Send through `MailService`, or pass `content` |
+| `text`/`html` as a `Buffer`, stream or object | Refused (`null` still counts as absent) | Pass a string |
+| No attachment size limit | 25 MB per message by default | Raise `maxAttachmentBytes` if you need more |
+| Nodemailer and Mailgun streamed a stream attachment | They receive its bytes, buffered within the limit | Nothing, unless you relied on streaming past the limit |
+| `send_failed` text carried the raw error | Fixed text; the error is in `cause` | Read `error.cause` |

package/dist/corpus/changelogs/2026-09-25-static-asset-and-storage-fixes.md

@@ -0,0 +1,202 @@
+---
+title: Static Asset Scoping, a Real Body Limit, and Storage File Names
+description: "A shared bucket can be scoped per controller and per route, configs.middlewares.bodyLimit finally does what its type promised, a recreated MetaLink refreshes every row instead of one, non-ASCII file names survive a direct-upload commit, and office files resolve to their registered MIME type."
+---
+
+# Changelog - 2026-09-25
+
+Rebuilding the static-asset and storage examples exposed these defects. Each one is fixed at its root.
+
+| Fix | Who is affected |
+|---|---|
+| [`controller.keyPrefix` scopes a shared bucket](#controller-keyprefix-scopes-a-shared-bucket) | Two controllers or tenants sharing one bucket |
+| [`routes.<key>.enabled` drops a built-in route](#routes-key-enabled-drops-a-built-in-route) | Applications that closed a route with a middleware override |
+| [`PUT .../meta-links/{objectName}` refreshes every row](#put-meta-links-objectname-refreshes-every-row) | Anyone calling the recreate route on a MetaLink table of their own |
+| [`configs.middlewares.bodyLimit` is applied](#configs-middlewares-bodylimit-is-applied) | Applications passing `middlewares` through the constructor `config`; a hook-time assignment still has no effect and now fails the boot |
+| [Request spy parses forms only in development](#request-spy-parses-forms-only-in-development) | Any route that reads a form body |
+| [`extra.maxBytes` checks `content-length` before the body is read](#extra-maxbytes-checks-content-length-before-the-body-is-read) | Applications with their own upload size guard |
+| [The error envelope honors the status on a thrown HTTPException](#the-error-envelope-honors-the-status-on-a-thrown-httpexception) | Every JSON-body route (malformed JSON is now `400`, not `500`), and any route whose handler throws an `HTTPException` |
+| [Storage accepts non-ASCII and unusual file names](#storage-accepts-non-ascii-and-unusual-file-names) | Direct upload commits; uploads with a generated key; `MinioHelper` metadata; `Content-Disposition` |
+| [Office file types resolve to their registered MIME type](#office-file-types-resolve-to-their-registered-mime-type) | `.xlsx`, `.xls`, `.docx`, `.doc`, `.pptx`, `.ppt`, `.odt`, `.ods` |
+| [`presignPost` stops naming the bucket twice in virtual-hosted style](#presignpost-stops-naming-the-bucket-twice-in-virtual-hosted-style) | `BunS3Helper` with `virtualHostedStyle: true` |
+
+## `controller.keyPrefix` scopes a shared bucket
+
+<Badge type="tip" text="Enhancement" />
+
+**In one line.** Two controllers can now point at the same bucket without either one seeing the other's keys.
+
+Set `controller.keyPrefix` and every route on that controller is confined to it:
+
+```typescript
+{
+  controller: { name: 'TenantAAssets', basePath: '/tenant-a/assets', bucket: 'shared', keyPrefix: 'tenant-a' },
+  storage: StaticAssetStorageTypes.BUN_S3,
+  helper: bunS3Helper,
+}
+```
+
+- `getObjectByName`, `downloadObjectByName`, `deleteObject`, and `recreateMetaLink` answer `404 core.storage.object_not_found` for a key outside the prefix - before any storage call, so a caller learns nothing about a key it does not own.
+- `listObjects` narrows a caller `prefix` that is wider than the scope, and returns `[]` for one that is disjoint from it, without calling storage.
+- `upload` places its own default key under the prefix. A `resolveObjectName` or `extra.normalizeNameFn` key outside it is refused with `400 core.static_asset.object_key_out_of_scope` - never rewritten, because the application may have recorded that key elsewhere.
+- With **neither** hook set, the component's own default naming under a scope keeps the original file name to one segment - a `/` in it is `400 [upload] Invalid original file name`, exactly as without `keyPrefix`. Set `resolveObjectName` or `extra.normalizeNameFn` to relax that.
+- Direct upload's pending key and policy `starts-with` condition also carry the prefix, and the commit route re-checks it.
+- `maxFolderDepth` counts folders below the prefix, not from the bucket root.
+- `keyPrefix` requires `controller.bucket` and throws at registration without it - the same requirement `directUpload` already has. Without a configured bucket the four bucket-management routes stay unscoped, so `keyPrefix` alone would isolate only part of the controller's surface.
+- Not scoped: `defineRoutesBefore` and `defineExtraRoutes`. The bucket-management routes are not registered at all once `controller.bucket` is set.
+
+**Who is affected:** nobody who leaves `keyPrefix` unset - behavior is unchanged. A controller that set `keyPrefix` without `bucket` (bucket-in-URL mode) now fails to register - add `controller.bucket`. See [`controller.keyPrefix`](/extensions/components/static-asset/api#controller-keyprefix) for the full reference and [Share one bucket between controllers](/extensions/components/static-asset/usage#share-one-bucket-between-controllers) for a worked example.
+
+## `routes.<key>.enabled` drops a built-in route
+
+<Badge type="tip" text="Enhancement" />
+
+Every built-in static-asset route now takes `enabled: false`, the same switch name the CRUD controller factory uses:
+
+```typescript
+routes: {
+  deleteBucket: { enabled: false },
+  deleteObject: { enabled: false },
+}
+```
+
+Before, closing a route meant overriding it with a middleware that always refused the request. `enabled` is stripped before the route reaches Hono, so a disabled route is not registered at all - no path, no entry in the OpenAPI document.
+
+**Who is affected:** nobody who leaves `routes` unset. An application that closed a route with a hand-written middleware can replace it with `enabled: false`.
+
+## `PUT .../meta-links/{objectName}` refreshes every row
+
+<Badge type="warning" text="Behavior Change" />
+
+**In one line.** Recreating a MetaLink row now refreshes every row for that object, keeps each row's own `storageType` and labels, and only creates a new row when none existed.
+
+Before, the route did a plain `findOne` then `updateById`/`create`: on a table with two rows for the same object - a product image attached to the product and to a variant, the documented case for the table's non-unique pair - only the first row found was touched, and a refresh silently overwrote the row's own `storageType` with the storage backend this controller was configured for.
+
+```typescript
+const response = await fetch(`/assets/buckets/uploads/meta-links/${encodeURIComponent(objectName)}`, { method: 'PUT' });
+const { success, action, count, metaLink, metaLinks } = await response.json();
+// action: 'refreshed' when rows for the object existed, 'created' when none did
+```
+
+- `action`, `count`, and `metaLinks` are new on the response. `success` and `metaLink` (now `metaLinks[0]`) are unchanged in shape. `action` is a real OpenAPI enum, `'refreshed' | 'created'`, not a bare `string` - a generated client now gets the narrow type.
+- A refresh always updates `mimetype`, `size`, `etag`, and `isSynced: true` on every row of the pair, and leaves each row's `storageType`, `variant`, `principalType`, `principalId`, and `sequence` untouched.
+- **`link` and `metadata` depend on `metaLink.createMetaLink`.** With a hook configured, a refresh writes only `mimetype`, `size`, `etag`, `isSynced` - `link` and `metadata` are left alone, because the hook already owns them, so an enrichment it wrote (dimensions, a placeholder, anything beyond `getStat()`) survives a recreate. Without a hook, one statement refreshes `link` plus the stat columns on every row, then one more statement **per row** merges that row's own `metadata` with the stat's - the stat's keys win, everything else the row had survives, and the step is skipped entirely when the stat carries no metadata.
+- That merge is a read-then-write: the first statement's own result supplies the "read", and each row's update is a separate statement after it. A concurrent write to that row's `metadata` landing in between is lost.
+- A create (no existing rows) goes through the same `createMetaLink` hook and builder an upload uses, so it gets your `storageType` and defaults - not a bare guess.
+- Refresh-then-create is still not atomic: two concurrent calls on an object with no existing row can both create one. Rows per pair are deliberately not unique, so the table allows it.
+
+> [!IMPORTANT]
+> The MetaLink type contract checks the **select row** only - the columns the component reads and writes, on whatever table `metaLink.model`/`metaLink.repository` point at. A column you add of your own must be nullable or carry a default: the component's default insert writes exactly the columns it knows about, so a `NOT NULL` column with no default passes the type check and then fails every insert the component makes without your own `createMetaLink` hook.
+
+**Who is affected:** anyone calling `PUT .../meta-links/{objectName}` on a table with more than one row per `(bucketName, objectName)` pair, or reading `metaLink.storageType` after a refresh - it now keeps the value your `createMetaLink` hook wrote, instead of the component's own. A `createMetaLink` hook that enriches `metadata` (for example BANA inventory's width, height, and placeholder) is no longer overwritten by a recreate call. Code reading `metaLink` off the response is unaffected; code that assumed one row per object should read `metaLinks` instead.
+
+## `configs.middlewares.bodyLimit` is applied
+
+<Badge type="info" text="Bug Fix" /> <Badge type="warning" text="Behavior Change" />
+
+`IMiddlewareConfigs.bodyLimit` existed as a type with nothing reading it. `RestApplication.registerDefaultMiddlewares()` now installs it - right after the request id, ahead of every other middleware, the request spy included:
+
+```typescript
+const application = new MyApplication({
+  scope: 'MyApp',
+  config: {
+    // ...the rest of IApplicationConfigs
+    middlewares: { bodyLimit: { enable: true, maxSize: 10 * 1024 * 1024 } },
+  },
+});
+```
+
+> [!IMPORTANT]
+> `configs.middlewares` is read inside `registerDefaultMiddlewares()`, before `staticConfigure()` runs. Pass `middlewares` through the constructor's `config` - or an application-config factory that builds that object - not by assigning `this.configs.middlewares` in `staticConfigure()` or a later hook: it is read too late to take effect, and the application refuses to boot when it detects the value changed after the fact.
+
+Over the limit answers `413 core.request.body_too_large`, or your own `onError`. A missing `enable` still applies the limit - fail-closed for a security control, even though the type marks `enable` required. A `maxSize` that is not a finite non-negative number throws at boot. Every other `IMiddlewareConfigs` key (`compress`, `cors`, `csrf`, `ipRestriction`) is still a type only - wire it yourself in `setupMiddlewares()`.
+
+`bodyLimit` bounds the request stream; it does not replace `extra.maxBytes` or the other way around. `extra.maxBytes` only checks a declared `Content-Length`, so a chunked request with none skips it - pair the two. Raise `configs.server.maxRequestBodySize` above `bodyLimit.maxSize`, or Bun's own limit answers first, with no IGNIS envelope. Keep `bodyLimit.path` away from a route that streams a body through - the limiter buffers the whole body on any path it covers.
+
+**Who is affected:** an application that assigns `configs.middlewares.bodyLimit` inside a hook like `staticConfigure()`, expecting it to take effect - it still does not, and the boot now fails instead of accepting it silently. Passed through the constructor, the limit is enforced for the first time. Everyone who never touched `configs.middlewares`: no action needed. See [Body limit](/references/base/middlewares#body-limit-configs-middlewares-bodylimit).
+
+## Request spy parses forms only in development
+
+<Badge type="warning" text="Behavior Change" />
+
+**In one line.** Outside a development environment, the request spy no longer parses a form body - and a malformed form is still `400 core.request.body_malformed` everywhere it matters, through a new shared reader.
+
+Before, `RequestSpyMiddleware` parsed every content type in every environment, just to log it - a multipart upload was fully read once by the spy and again by the route. Outside development the spy now parses only `application/json`, for its own malformed-body check; forms, `text/*`, and everything else reach the route unread.
+
+A route whose `request.body.content` declares `multipart/form-data` or `application/x-www-form-urlencoded` now gets a `formBodyReader` middleware appended, after every application middleware and just ahead of the route's own validator. It parses the form through a new shared reader and maps a parse failure to `400 core.request.body_malformed`, before the validator gets a chance to throw its own generic, uncoded 400 - see [the error envelope fix](#the-error-envelope-honors-the-status-on-a-thrown-httpexception) for what happens when it does.
+
+```typescript
+import { readFormBody } from '@venizia/ignis-helpers';
+
+const formData = await readFormBody({ req: context.req });
+```
+
+`readFormBody` is new in `@venizia/ignis-helpers` (and `/core`). `parseMultipartBody` now goes through it too.
+
+> [!WARNING]
+> An application that calls `context.req.formData()` itself - middleware running ahead of any framework reader, such as an upload authorization guard - is **not** covered by `formBodyReader`. A malformed body there is a `500` in production, not a `400`, unless that middleware calls `readFormBody({ req: context.req })` instead. It returns the same cached `FormData`, so the swap is a one-line change.
+
+**Who is affected:** a route that reads a form body by hand, ahead of the framework's own reader, must switch to `readFormBody`. A route that declares its form body in OpenAPI (the static-asset upload, any `@hono/zod-openapi` form route) needs no change - its `400` on a malformed body is unchanged. Code that relied on the spy logging a non-JSON body outside development already saw nothing logged; this only changes whether it is *parsed*, which was never observable from the log line.
+
+## `extra.maxBytes` checks `content-length` before the body is read
+
+<Badge type="info" text="Bug Fix" />
+
+The `content-length` pre-check moved from the upload handler into route middleware, appended **after** your own `routes.upload.middleware` - so an application's own size guard (for example BANA inventory's `REQUEST_TOO_LARGE`) still answers first.
+
+It moved because `@hono/zod-openapi`'s form validator already reads the whole multipart body before any handler runs: a check inside the handler saw a body that was already fully read, so it never saved the memory it was written to save. The per-file `buffer.length` check - the authoritative one, since a multipart envelope is larger than the files inside it - stays in the handler.
+
+`extra.maxBytes` bounds only a **declared** `content-length` - a chunked request with none skips it entirely. Pair it with [`configs.middlewares.bodyLimit`](#configs-middlewares-bodylimit-is-applied) for a ceiling nothing can skip.
+
+**Who is affected:** nobody by default. An application with its own upload size middleware keeps answering first, unchanged. An application relying on `extra.maxBytes` alone against a chunked client should add `configs.middlewares.bodyLimit`.
+
+## The error envelope honors the status on a thrown HTTPException
+
+<Badge type="info" text="Bug Fix" />
+
+The error handler read `statusCode` only. A Hono `HTTPException` - thrown by `@hono/zod-openapi`'s own request validator, or by your own code - carries its status on `.status`, so every 4xx `HTTPException` rendered as a generic `500 core.system_error` instead of its real status. The handler now reads `.status` too: a 4xx `HTTPException` renders as its own status and keeps its own message, sanitized environment or not; a 5xx one still stays an unexpected `500` whose message never reaches the client.
+
+This is a general correctness fix, not specific to forms: any route whose validator or handler throws an `HTTPException` is affected. The clearest case is JSON: malformed JSON on **any** JSON-body route - every `@hono/zod-openapi` route with a `jsonContent` body, including the generated CRUD controllers - now answers `400 Malformed JSON in request body` instead of `500 core.system_error`. It does not cover a raw runtime error - a `TypeError`, for instance - which still renders as a `500`; see [`readFormBody`](#request-spy-parses-forms-only-in-development) for that case on a form body specifically.
+
+**Who is affected:** any route whose validator or handler throws a Hono `HTTPException` - in practice, every JSON-body and form-body route, through the request validator, and any consumer code that throws one by hand. A response that used to be a `500` for one of these now carries the exception's own 4xx status and its own message (malformed JSON, for example, now reads `Malformed JSON in request body`). Code that matched on `statusCode: 500` for one of these cases should match on the new status instead.
+
+## Storage accepts non-ASCII and unusual file names
+
+<Badge type="info" text="Bug Fix" /> <Badge type="tip" text="Enhancement" />
+
+**In one line.** A file called `Kiểm kê.xlsx` or `Báo cáo [Q3] & tổng hợp #1!.xlsx` now uploads, commits, and downloads under its own name.
+
+- **`BunS3Helper.copyObject` encodes the copy source.** The `x-amz-copy-source` header is now built with per-segment SigV4 encoding. Before, a non-ASCII key made Bun throw `Header 'x-amz-copy-source' has invalid value`, so a direct-upload commit failed outright; a key with `+`, `%`, `?`, or `#` risked copying the wrong object, because S3 URL-decodes the header and splits `?versionId=` off it.
+- **A generated key no longer rejects the original name.** When `upload` gets a naming hook (`normalizeNameFn`, or the static-asset controller's own default, `resolveObjectName`, or `controller.keyPrefix`), the original name is only metadata, not the key. Names containing `& # ! [ ] { } ;` or a leading dot are now accepted; control characters, an empty name, and more than 255 characters are still refused. Without a naming hook, the name is the key, and the key rules apply exactly as before.
+- **Every key in a batch is checked before the first write.** One bad name in a multi-file upload now stores nothing, instead of writing the files ahead of the bad one.
+- **`MinioHelper` stores a non-ASCII name.** The `originalName` and `normalizeName` metadata values are RFC 2047-encoded outside printable ASCII. Before, the upload crashed with `ERR_INVALID_CHAR`.
+- **`createContentDispositionHeader` keeps the real name, and now keeps emoji and script-joining marks too.** `filename*` carries the UTF-8 name with every control, bidi-override, and other format character replaced by `_` (so a right-to-left override in a name can no longer relabel the extension a user sees) - **except** the zero-width joiner and non-joiner, which are left alone, because they build emoji sequences (a family emoji is several code points joined by U+200D) and join letters in Persian and other scripts, and reorder nothing. The `filename` fallback stays printable ASCII only. ASCII names produce the same header as before.
+
+**Who is affected:** direct upload and static-asset uploads with non-ASCII or punctuated file names - fixed, no action needed. Code that matched the old error text `[upload] Invalid original file name` for a name copied into a generated key now sees `[upload] Invalid normalized object name | name: ...` instead. `MinioHelper` consumers reading `originalName` metadata get an RFC 2047 value (`=?UTF-8?B?...?=`) for a non-ASCII name; ASCII values are unchanged. A file name with a bidi override or another format character now downloads under a sanitized `filename*`, where it previously carried the raw character through.
+
+## Office file types resolve to their registered MIME type
+
+<Badge type="info" text="Bug Fix" />
+
+`.xlsx`, `.xls`, `.docx`, `.doc`, `.pptx`, `.ppt`, `.odt`, and `.ods` resolve to their real content type in `ContentTypeTable`, instead of falling back to `application/octet-stream`. `.csv`, `.zip`, and `.txt` were already in the table.
+
+This changes what the MetaLink `mimetype` column, `DiskHelper.getStat`, `writeStream`'s default type, and `AssetIngest` record - not what the static-asset routes serve. None of the office types is on `RENDERABLE_CONTENT_TYPES`, so the served `Content-Type` is still `application/octet-stream` with `Content-Disposition: attachment`, unchanged.
+
+**Who is affected:** anyone reading a stored office file's recorded MIME type. Served behavior is unchanged.
+
+## `presignPost` stops naming the bucket twice in virtual-hosted style
+
+<Badge type="info" text="Bug Fix" />
+
+With `virtualHostedStyle: true`, `presignPost`'s `postURL` was `https://<bucket>.<host>/<bucket>` - the bucket named in the host and repeated as a path segment, so the browser posted to a path that does not exist. It is now `https://<bucket>.<host>`. Path-style addressing (the common case, and what every current `BunS3Helper` construction in BANA uses) is unchanged: `http://minio:9000/<bucket>`.
+
+**Who is affected:** `BunS3Helper` constructed with `virtualHostedStyle: true` and used with `directUpload` or a hand-called `presignPost`. Nobody using path-style addressing (the default) sees any change.
+
+## See also
+
+- [Static Asset Component](/extensions/components/static-asset/) - overview and quick start
+- [Static Asset Component - Full Reference](/extensions/components/static-asset/api) - `controller.keyPrefix`, per-route `enabled`, recreate-metalink
+- [Static Asset Component - Error Reference](/extensions/components/static-asset/errors) - every code, including the two new ones
+- [Middlewares Reference](/references/base/middlewares) - body limit, the form body reader, the request spy
+- [Storage Helpers - Full Reference](/extensions/helpers/storage/api) - `upload`, MIME table, name validation
+- [Request Utility](/references/utilities/request) - `readFormBody`, `createContentDispositionHeader`

package/dist/corpus/changelogs/2026-09-26-json-path-column-qualification.md

@@ -0,0 +1,34 @@
+---
+title: JSON-Path Where and Order Keys Are Now Qualified With the Table
+description: "A JSON-path filter or order key now renders qualified with its table or query alias, in Postgres and SQLite, so a query joining two tables that share a JSON column name no longer fails with an ambiguous-column error."
+---
+
+# Changelog - 2026-09-26
+
+## JSON-path where and order keys are qualified
+
+<Badge type="info" text="Bug Fix" />
+
+**In one line.** A `where` or `order` key on a JSON/JSONB column now renders qualified with the table - or the query alias, on an included relation - exactly like a plain column already did, in both Postgres and SQLite.
+
+## What changed
+
+- **Postgres.** A JSON-path `where` (`#>>`) and `order` (`#>`) extraction now qualifies the column: `"orders"."metadata" #>> '{tier}'` instead of `"metadata" #>> '{tier}'`. The numeric-cast branch (`::numeric`) and a JSON path nested under `not` qualify the same way.
+- **SQLite.** `json_extract` now takes the qualified column: `json_extract("orders"."metadata", '$."tier"')` instead of `json_extract("metadata", '$."tier"')`. A numeric path component that doubles the candidate reads still works - both extractions inside the `coalesce(...)` qualify.
+- **The path segment is unchanged.** Only the column part renders differently; the validated path literal (`'{tier}'`, `'$."tier"'`) is exactly as before, and no new injection surface opens.
+
+## Who is affected
+
+- **A query that joins a second table with a same-named JSON column.** Before, Postgres rejected it with `column reference "metadata" is ambiguous` and SQLite with `SQLITE_ERROR: ambiguous column name: metadata`; it now runs on both. This is the defect this change fixes.
+- **A test or a log line that asserts the exact rendered SQL string for a JSON-path filter or order key.** It now sees the table (or alias) prefix on that fragment. Update the expected string - the filter shape and the returned rows are unchanged.
+- **A `FilterBuilder` subclass author.** The protected `buildJsonOperatorConditions` now receives `jsonPath`/`safeNumericCast` typed `string | SQL`, not `string`. An existing override still compiles either way (parameters are bivariant) and one that only forwards the value (to `super`, or straight into an operator function) keeps working, still qualified. But one still typed `string` that treats the value as text (`sql.raw(opts.jsonPath)`, or interpolating it into a template string) now receives an `SQL` object and emits `[object Object]` - the query then fails. Retype it to `string | SQL` and pass the value through instead of stringifying it.
+- **Everyone else.** No action needed. The filter API, the rows returned, and their order are all unchanged.
+
+## Migration
+
+None. This is a defect fix with no public API change - a filter such as `{ 'metadata.tier': 'gold' }` is written exactly as before.
+
+## See also
+
+- [JSON/JSONB Filtering](/references/base/filter-system/json-filtering)
+- [Fields, Order & Pagination](/references/base/filter-system/fields-order-pagination)

package/dist/corpus/changelogs/2026-09-26-order-entry-parsing-and-sort-expressions.md

@@ -0,0 +1,83 @@
+---
+title: Order Entries Get One Parser, and toOrderBy Can Sort by an Expression
+description: "parseOrderEntry is now a public export every relational and search dialect shares, toOrderBy gains an expressions option for sorting by a joined column or a computed SQL expression, and a malformed order entry is now a 400 instead of a silent truncation."
+packages: [connectors, core-server, filter, kernel]
+---
+
+# Changelog - 2026-09-26
+
+## Order entries: one parser, and new failure modes for malformed input
+
+<Badge type="tip" text="Feature" /> <Badge type="warning" text="Behavior Change" />
+
+**In one line.** Every `order` entry - relational, Typesense, Meilisearch - is now read by one exported `parseOrderEntry` function, and an entry it cannot make sense of is a `400` instead of a silent truncation.
+
+```typescript
+import { parseOrderEntry } from '@venizia/ignis-filter';
+
+parseOrderEntry({ entry: 'createdAt DESC' }); // { field: 'createdAt', direction: 'desc' }
+parseOrderEntry({ entry: 'name' }); // { field: 'name', direction: 'asc' }
+```
+
+## What changed
+
+- **`parseOrderEntry` is a new export** of `@venizia/ignis-filter` (also from `@venizia/ignis-kernel` and `@venizia/ignis`), alongside the new `TSortDirection` and `TParsedOrderEntry` types. It replaces three private copies of the same parsing logic in the relational, Typesense, and Meilisearch dialects.
+- **An entry with more than two tokens is now a 400.** `'createdAt DESC NULLS LAST'` used to sort on `createdAt DESC` and silently drop `NULLS LAST` - IGNIS order entries never gave a `NULLS LAST`/`FIRST` clause any effect, so the tail was always dead weight, just quietly accepted. It now throws before the query runs.
+- **An empty entry (`''`, or all whitespace) is now a 400.** It used to reach the relational dialect as an empty field name and read as "column not found"; it now fails at the parser with a clearer message.
+- **Direction error messages changed.** They now come from `parseOrderEntry` and carry the whole entry text, not the table name or the field alone. See the table below.
+- **The entry in a message is now `JSON.stringify`-quoted**, not interpolated raw - `entry: "name DESC NULLS LAST"` rather than `entry: 'name DESC NULLS LAST'`. A newline or other ASCII control character inside a malformed entry is escaped instead of reaching the log or the response as a literal character. DEL, the C1 range, and the Unicode line separators `U+2028`/`U+2029` still pass through raw - `JSON.stringify` does not escape them (tracked in #65).
+- **Only ASCII whitespace separates a field from its direction.** A non-breaking space (`<NBSP>`) or another Unicode space no longer splits `'name<NBSP>DESC'` into two tokens - the old `split(/\s+/)` did split on it. The whole string is now read as one field name.
+- **`toOrderBy` (relational dialects) gains an `expressions` option**, for sorting by a column on a joined table or a computed SQL expression - see the next section.
+
+## Error messages, before and after
+
+| Case | Relational, before | Relational, after |
+|---|---|---|
+| Invalid direction | `[FilterBuilder][toOrderBy] Table: <t> \| Invalid direction: 'RANDOM' \| Expected: 'ASC' or 'DESC'` | `[parseOrderEntry] Invalid direction \| entry: "name RANDOM" \| Expected: 'ASC' or 'DESC'` |
+| Extra tokens | Silently accepted; the tail was dropped | `[parseOrderEntry] Too many tokens \| entry: "name DESC NULLS LAST" \| Expected: '<field>' or '<field> ASC\|DESC'` |
+| Empty entry | Reached the dialect as an unknown column | `[parseOrderEntry] Order entry has no field \| entry: ""` |
+
+| Case | Search (Typesense/Meilisearch), before | Search, after |
+|---|---|---|
+| Invalid direction | `Invalid sort direction '<direction>' for field '<field>'` | Same `[parseOrderEntry] Invalid direction` message as relational |
+| Extra tokens | Silently accepted; the tail was dropped | Same `[parseOrderEntry] Too many tokens` message |
+| Empty entry | Silently accepted as an empty field | Same `[parseOrderEntry] Order entry has no field` message |
+
+Status codes: every case that was already an error was a `400` and still is; the "silently accepted" cases (extra tokens, an empty entry) are now `400` for the first time. Unknown-column messages (`Column NOT FOUND | key: '<key>'`) are unchanged and still name the key.
+
+## `toOrderBy` can sort by a joined column or a computed expression
+
+<Badge type="tip" text="Feature" />
+
+**In one line.** `IRelationalQueryDialect.toOrderBy` takes a new `expressions` option: a map from the name an order entry uses to a Drizzle column or `SQL`, for sort targets the model's own schema cannot name.
+
+```typescript
+import { sql } from 'drizzle-orm';
+
+const orderBy = queryDialect.toOrderBy({
+  tableName: 'item',
+  schema: itemTable,
+  order: ['groupLabel ASC', 'displayName DESC'],
+  expressions: {
+    groupLabel: groupTable.label, // a column on a joined table
+    displayName: sql`COALESCE(${itemTable.nickname}, ${itemTable.name})`, // a computed value
+  },
+});
+// ORDER BY "group"."label" asc, COALESCE("item"."nickname", "item"."name") desc, "item"."id" asc
+```
+
+A key resolves as an own key of `expressions` first (`Object.hasOwn`, so an inherited name like `constructor` never matches), then as a JSON path, then as a schema column. The `id ASC` tie-breaker still closes the list unless an entry names `id`; an expression keyed `id` never counts as naming it. Omitting `expressions` costs nothing extra. See [Fields, Order & Pagination](/references/base/filter-system/fields-order-pagination#sorting-by-a-joined-column-or-a-computed-expression) for the full reference.
+
+## Who is affected
+
+- **Everyone calling `order` with well-formed entries (`'field'` or `'field ASC|DESC'`, ASCII whitespace):** no change in behavior.
+- **An order entry with more than two tokens, or an empty entry:** now a `400` instead of a silently accepted (relational and search dialects alike). Drop the extra tokens from the entry - IGNIS never honored them.
+- **An order entry using a non-ASCII space to separate field and direction:** now reads as one field name and likely resolves to an unknown column. Use a regular space or tab.
+- **Code matching the old relational or search direction-error text** (`Invalid direction: '...' | Expected:`, `Invalid sort direction '...' for field '...'`): match the new `[parseOrderEntry] Invalid direction` message instead. The status code is unchanged.
+- **Nobody needs to opt in to keep the old parser** - there is no flag; every dialect calls `parseOrderEntry` unconditionally. Applications wanting a joined-column or computed sort should adopt `toOrderBy`'s new `expressions` option; nothing is required if none is passed.
+
+## See also
+
+- [Fields, Order & Pagination](/references/base/filter-system/fields-order-pagination) - `order`, `parseOrderEntry`, `toOrderBy`'s `expressions` option
+- [Filter System Overview](/references/base/filter-system/) - the `filter` shape and every operator family
+- [Quick Reference](/references/base/filter-system/quick-reference) - every filter property, one line each

package/dist/corpus/changelogs/2026-09-26-run-in-transaction-and-transaction-double.md

@@ -0,0 +1,125 @@
+---
+title: A Repository Method Runs Its Own Transaction, and a Double Stubs One In Tests
+description: "runInTransaction begins, commits, and rolls back for you; TransactionDouble from @venizia/ignis/testing stubs beginTransaction() with no database behind it. The real transaction handle is now backed by a shared class - behavior unchanged."
+---
+
+# Changelog - 2026-09-26
+
+## `runInTransaction` runs commit and rollback for you
+
+<Badge type="tip" text="Feature" />
+
+Hand-written begin / try / commit / catch / rollback blocks repeat wherever a repository method needs
+a transaction. `runInTransaction` writes that block once:
+
+```typescript
+const order = await orderRepository.runInTransaction({
+  execute: async ({ transaction }) => {
+    const { data: created } = await orderRepository.create({
+      data: orderData,
+      options: { transaction },
+    });
+
+    await orderItemRepository.create({
+      data: { orderId: created.id, ...itemData },
+      options: { transaction },
+    });
+
+    return created;
+  },
+});
+```
+
+## Join or own, never both
+
+Pass a `transaction` and `runInTransaction` joins it: it never commits or rolls back, and
+`transactionOptions` is ignored. Pass none and it owns one: begins, commits on success, and rolls
+back on failure - rethrowing the original error even when the rollback itself fails.
+
+| | Joined (`transaction` passed) | Owned (none passed) |
+|---|---|---|
+| Begin | Never | `beginTransaction(transactionOptions)` |
+| Commit | Never | After `execute` resolves |
+| Rollback | Never | On failure, then rethrows the original error |
+
+That turns a service method that must work stand-alone and nested inside a caller's transaction into
+a one-line forward, not two code paths:
+
+```typescript
+async function createOrder(opts: { data: TOrderCreate; transaction?: IDatabaseTransaction }) {
+  return orderRepository.runInTransaction({
+    transaction: opts.transaction,
+    execute: async ({ transaction }) =>
+      orderRepository.create({ data: opts.data, options: { transaction } }),
+  });
+}
+```
+
+See [Transactions](/guides/core-concepts/persistent/transactions#runintransaction) for the full
+rules, including what happens to an inactive handle and a failed rollback.
+
+## `TransactionDouble` stubs a transaction with no database
+
+<Badge type="tip" text="Feature" />
+
+Unit-testing `runInTransaction` used to mean standing up Postgres or SQLite. `TransactionDouble`,
+from the new `@venizia/ignis/testing` entry (`@venizia/ignis-connectors/testing` in the connectors
+package), is a transaction handle with no database behind it:
+
+```typescript
+import { spyOn } from 'bun:test';
+import { PostgresTransactionDouble } from '@venizia/ignis/testing';
+
+const double = new PostgresTransactionDouble();
+spyOn(orderRepository, 'beginTransaction').mockResolvedValue(double);
+
+await orderRepository.runInTransaction({ execute: async () => 'ok' });
+
+expect(double.commitCount).toBe(1);
+```
+
+Reading `double.connector` throws - a repository method that reaches the database must be stubbed
+too. Inject `commitError` or `rollbackError` to test a failed end. See
+[Transaction Doubles](/best-practices/testing-strategies#transaction-doubles) for the full guide,
+including the limit: a double proves control flow, not SQL atomicity.
+
+## If `execute` ends the owned transaction itself
+
+`runInTransaction` expects `execute` to leave an owned transaction open for it to commit. Call
+`commit()` or `rollback()` from inside `execute` instead, and `runInTransaction` never ends it a
+second time: committed by `execute` - the result is returned, with no second commit attempt. Rolled
+back or left failed by `execute` - a dedicated error, naming that `execute` ended the transaction
+before it could be committed, with no rollback attempt. `execute` rejects after ending the
+transaction itself - the ORIGINAL rejection, with no further rollback attempt. This reads the
+transaction's own internal state through a registry symbol, so it recognises the real handle or
+`TransactionDouble` even across a CommonJS/ESM mix (a `@venizia/ignis/testing` double with an
+`@venizia/ignis-connectors` repository, or the reverse) - only a transaction from an entirely
+different `ITransaction` implementation is unreadable, and reports the "ended before it could be
+committed" error even when `execute` committed it successfully.
+
+Always `await` `commit()`/`rollback()` when calling them from inside `execute`. A commit call that
+`execute` does not await is read as COMMITTED before the COMMIT statement itself has settled, so
+`runInTransaction` returns `execute`'s result while that commit can still go on to fail.
+
+## Who is affected
+
+Additive. Nothing existing changes behavior, and adopting either API is optional.
+
+One shape changed under the hood, not in behavior: the handle `beginTransaction()` returns is now a
+class, `ConnectionTransaction`, instead of a closure building a fresh object literal each time. Its
+datasource, connection, and internal state are ES private fields - invisible to `JSON.stringify`,
+`util.inspect`, `Object.keys`, and a spread copy, exactly as before. `commit()`, `rollback()`, and
+`connector` behave exactly as before, and reading `isActive` on the handle itself still works.
+
+The one real difference: `isActive` now lives on the shared prototype, not as an own property. A
+spread copy - `{ ...transaction }` - no longer carries it, so passing a spread copy to a repository
+now throws "Transaction is no longer active" instead of working. Reading `isActive` through a `Proxy`
+or an `Object.create(transaction)` wrapper now throws a `TypeError` too - ES private fields are not
+proxyable and are not inherited. Nothing in IGNIS does either.
+
+**Files:**
+
+- [`packages/connectors/src/relational/core/datasources/transaction-lifecycle.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/relational/core/datasources/transaction-lifecycle.ts) - the shared end-of-transaction state machine
+- [`packages/connectors/src/relational/core/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/relational/core/datasources/base.ts) - the real handle, `ConnectionTransaction`
+- [`packages/connectors/src/relational/core/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/relational/core/repositories/core/base.ts) - `runInTransaction`
+- [`packages/connectors/src/testing/transaction-double.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/testing/transaction-double.ts) - `TransactionDouble`, `PostgresTransactionDouble`, `SqliteTransactionDouble`