gina 0.6.9 → 0.6.10

package/CHANGELOG.md

@@ -6,6 +6,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.10 - 2026-08-16
+
+### Added
+* Maintenance mode — a bundle can now be closed to the public without being stopped, via `settings.json > server.maintenance` (#MAINT1). When active, every request EXCEPT the `/_gina/*` family is answered `503` with `Retry-After` and `Cache-Control: no-store`, carrying a self-contained maintenance page for a browser navigation and the framework's standard `503` JSON body for XHR / SPA-fragment / json-only callers. The gate runs on BOTH engines, placed after every `/_gina/*` handler and before the webroot filter, static-asset serving, both render/output-cache serve points and routing — so unlike a route middleware (which only runs once a route has matched) it also covers static assets and unmatched URLs. `/_gina/health/check` deliberately keeps answering 200 so an orchestrator does not restart pods over a declared window. Config is `{enabled, retryAfter, message, bypassKey, allowFrom}`; `enabled` must be a strict boolean, every other key falls back per key with a boot warning, and a malformed block never refuses a boot. Two bypasses let chosen visitors through an open window: `bypassKey` (constant-time compare, presented as the `x-gina-maintenance-key` header or once as `?gina-maintenance-key=`, which sets a stateless 12h HttpOnly cookie and redirects to the same URL without the secret) works under ANY topology, while `allowFrom` is honoured only for requests that do not classify as proxied — behind a reverse proxy every socket address is the proxy's, so an unconditioned IP allowlist would admit either everyone or no one. Flip it at runtime with the admin-gated `GET/POST /_gina/maintenance` (optional `ttlSeconds` dead-man switch); a runtime override is not persisted, and an expired TTL reverts to the configured state rather than to off, so a forgotten timer can never re-open a site that configuration says is closed. Scope is per bundle, so merged-process projects isolate correctly. Server-side only — no browser-bundle change, so pickup is a bundle restart with no re-bake.
+
+### Fixed
+* Boot-time bundle mounts are now idempotent, atomic and concurrency-safe (#B381). A mount symlink that already resolves to the intended source is kept untouched, so the steady-state boot writes nothing; a wrong or missing link is published atomically (temp sibling + rename), so the mount name never disappears mid-rewrite; and a concurrent process publishing the identical link is treated as success instead of killing the boot. Previously every boot re-created every declared bundle link in two non-atomic steps (unlink, then create) with no mutual exclusion — with several processes booting one shared project tree (e.g. replicas over a POSIX network filesystem), the contended rewrites could fail a boot outright or abort the shared config load for every bundle. The project bundles/tmp/cache directories and the generator path creation are race-free now as well (recursive create instead of check-then-create). Behaviour note: a real directory occupying a mount path is no longer silently deleted and re-linked — the boot refuses loudly instead.
+
+### Security
+* Closed a cross-site request forgery hole in the admin `/_gina/*` control endpoints (#B384), present in every release up to and including 0.6.9. These endpoints authorise callers by IP allowlist alone (`app.json` `admin.allowFrom`, loopback by default) and a browser attaches that ambient credential automatically, so an operator browsing from an allowlisted machine could be lured to a page that silently issued writes to `/_gina/storage/gc`, `/_gina/cache/clear`, `/_gina/release/rebuild` or `/_gina/maintenance`. The first three read their whole input from the query string and never read a body, so the attack needed no JavaScript and no CORS involvement at all: a plain auto-submitting form was enough. A cross-origin write to any `/_gina/*` endpoint is now refused with 403 on both engines, consulting `Sec-Fetch-Site` where the browser sends it and comparing `Origin` against the connected authority otherwise, never against a forwarded header. Two things are deliberately unaffected: requests carrying no browser origin signal (curl, the gina CLI, deploy scripts) still work, so operator tooling is unchanged; and safe methods (GET, HEAD, OPTIONS, TRACE) are untouched, so the Inspector cross-origin SSE and GET channels keep working. No configuration change is required.
+
 ## 0.6.9 - 2026-08-16
 ### Added
 * `gina.pushToSession(sessionID, payload[, option][, callback])` — a sanctioned way to push to a session from OUTSIDE a request (#B366). `self.push()` needs a live request-bound controller, so code that has none (a `lib/job` handler, a cron tick, a boot hook) had no route to a user's socket at all; the pattern consumers reached for instead — a background worker making an HTTP hop carrying the user's session id in the request body — was the #B364 vulnerability, and closing it left that shape with nowhere to go. This is the replacement, and it is deliberately narrow. The recipient is a REQUIRED argument: an absent or empty `sessionID` is an error, never a fan-out, and no broadcast is reachable from this API at all — the deliberate all-clients send stays in-request as `self.push(payload, { broadcast: true })`. Source the recipient from server-held state (capture it when the work is queued, keep it server-side); round-tripping a recipient id, or a token naming one, through the browser hands the choice back to the caller and re-opens #B364 one layer up. Delivery is reported rather than assumed: `callback(err, { delivered })` fires exactly once with the number of sockets written, and `delivered: 0` is a normal outcome (the user closed the tab), not an error — the shape this replaces was fire-and-forget and blind. Errors carry a machine-readable `err.code` (`PUSH_INVALID_RECIPIENT`, `PUSH_INVALID_PAYLOAD`, `PUSH_CHANNEL_NOT_CONFIGURED`, `PUSH_CHANNEL_NOT_READY`, `PUSH_PAYLOAD_SERIALIZE_FAILED`). Requires the isaac engine with `settings.json > server.ioServer` attached; the express engine has no engine.io channel and now says so by name instead of failing as a 500. Available as `lib.push.toSession()` for code holding its own server instance.

package/README.md

@@ -61,34 +61,28 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.6.9
+## What's in 0.6.10
 
 > **Restart your bundles — no re-bake.** The browser bundle is byte-identical to
-> `0.6.8`, so `gina bundle:restart` is enough; everything below is server-side
-> or CLI.
+> `0.6.9` (verified), so `gina bundle:restart` is enough; this release is
+> server-side only.
 
-> **No settings reset.** `0.6.9` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.10` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**This release fixes one security flaw, live in every published version that
-attaches `server.ioServer`.** It closes the receiver half of the axis `0.6.8`
-opened, and it fails closed — so if you use targeted pushes, confirm they still
-arrive after upgrading. Separately, two malformed `settings.secrets.file` shapes
-now refuse to boot; check that config if you use the file tier. Both are covered
-in the [migration guide](https://gina.io/docs/migration).
-
-- **Security — an engine.io socket's session is now proven, not claimed.** A socket's `sessionId` — the value every targeted `self.push()` matches against — was set from `payload.session.id`, a field the browser sends, on every message, and was never checked against the connection's own session. Any client could therefore claim another user's session and receive the pushes addressed to it; and because a rendered page carries the *bare* session id in its bootstrap script while the cookie carries the signed form, doing so took strictly less than stealing the cookie the signature exists to protect. The binding now happens once, at connection, from the upgrade request's own cookie: gina replays the bundle's own session middleware over that request, so the same secret, store and cookie name apply with no new configuration and no framework access to your secret — and it works whether or not the bundle adopted `gina.plugins.Session()`. The response handed to that middleware is inert, so a socket upgrade can never emit `Set-Cookie` or persist a session. It fails closed: no session middleware, no cookie, or a cookie that does not verify leaves the socket with no id, and an id-less socket matches no targeted push. A client that still asserts an id is logged and ignored, which doubles as an impersonation detector. No code change is needed — but because the failure direction is silence rather than an error, verify your targeted pushes still land.
-- **Added — `gina.pushToSession()`, a sanctioned push from outside a request.** `self.push()` needs a live request-bound controller, so a `lib/job` handler, a cron tick or a boot hook had no route to a user's socket at all — and the pattern reached for instead, a worker making an HTTP hop carrying the session id in the request body, *was* the flaw `0.6.8` closed. This is the replacement `0.6.8` promised, and it is deliberately narrow: the recipient is a required argument, an absent or empty `sessionID` is an error rather than a fan-out, and no broadcast is reachable from this API at all (a deliberate all-clients send stays in-request as `self.push(payload, { broadcast: true })`). Source the recipient from server-held state — round-tripping a recipient id, or a token naming one, through the browser hands the choice back to the caller and re-opens the same flaw one layer up. Delivery is reported rather than assumed: `callback(err, { delivered })` fires exactly once with the number of sockets written, and `delivered: 0` is a normal outcome, not an error. Errors carry a machine-readable `err.code`. Requires the `isaac` engine with `server.ioServer` attached; also available as `lib.push.toSession()`.
-- **Added — a bundle can declare which scopes it is deployed in.** An optional `scopes` allow-list on a bundle's `manifest.json` entry replaces the all-or-nothing choice between "registered everywhere" and "not in the manifest at all". The motivating case is a bundle you are still building: `"scopes": ["local"]` keeps it running locally while every other scope behaves as though it does not exist. An absent or null key means every scope, so existing manifests are completely unaffected; an empty array parks the bundle everywhere; a non-array value is reported as a manifest error by name. How an exclusion is reported depends on whether you asked for it — the boot and `gina project:build` skip an excluded bundle with a notice, so one parked bundle never blocks a project build, while starting it or naming it in `gina bundle:build --scope=` is refused by name, because silently producing no artifact would read as success in a deploy script.
-- **Fixed — `engine: "express"` bundles boot and serve on Express 5.** Express 5 broke the engine twice over: its router rejected the bare-string `'*'` catch-all at mount time, so the bundle aborted before ever listening, and it turned `req.query` into a prototype getter, so even past the mount every request died on the framework's strict-mode query assignment. Both are fixed, and the supported range is declared for the first time — `>= 4 < 6`, with both majors verified live. An out-of-range major logs a loud warning but still boots, since a wrong refusal is a total outage while a wrong warning is a log line. Express remains yours to provide: it is deliberately neither a dependency nor a peer dependency.
-- **Fixed — `project:add` / `project:import` no longer rebuild the `bundles` block destructively.** Any mismatch between the declared bundle count and what was on disk made those commands empty the whole block and rebuild it from the directory listing — dropping every key the rebuild template does not carry (the new `scopes` allow-list, `gina_version`, any custom key) and resetting each bundle's version, tag and release targets. The reset hit *every* registered project on the machine, not just the one being named: a bystander project got no rebuild at all and was left with a permanently empty `bundles` block that fails its next boot. The manifest is now the authority — declared bundles are preserved untouched, bundles found on disk but missing from the manifest are still registered additively on import, and a declared bundle whose directory is absent is reported with a warning rather than auto-pruned. A related path bug is fixed with it: the rescan built a wrong `settings.json` path for every bundle after the first, so only the first bundle's settings could ever be found.
-- **Fixed — registration no longer adopts invalid protocol/scheme declarations, nor reads other projects' bundles.** `project:add`/`project:import` adopted whatever `server.protocol` or `server.scheme` a bundle declared straight into the project's registry lists, unchecked — an arbitrary string became a registered "valid" value, persisted, and `gina image:build` then baked the polluted list into the synthesized image's environment. The same pass also resolved *every* registered project's bundles against the path of the project being added, so when two projects each had a bundle of the same name, one project's declarations leaked into the other's registry entry from a command that never named it. The framework's supported sets are now the authority, a project's lists stay a subset of them, an unsupported value is reported by name and adopted nowhere, and each project's bundles are resolved against that project's own path.
-- **Fixed — `project:add` writes the project's `.gitignore`.** The framework has always shipped a `core/template/_gitignore` whose underscore prefix implies a rename at scaffold time, but nothing performed that rename — so the template had zero consumers and every scaffolded project came out with no `.gitignore` at all, leaving the secret-file globs it carries protecting nothing. The copy is skip-if-exists, so your own file is never replaced or appended to, and re-running the command changes nothing.
-- **Fixed — a failed file copy can no longer destroy the destination it was replacing.** The path helper's copier — the byte-writer behind `_().cp()` and `PathObject.mv()`, which CLI copy, build and rename paths all ride — wrote directly to the final name and unlinked an existing destination *before* the copy started. Bytes now stage to a temp sibling and publish with an atomic rename, so a reader never observes a partial file and the destination is replaced only on success. A source-side read error is handled instead of killing the process, a failed copy settles its callback exactly once, and failures propagate a real `Error` rather than a plain string. **Contract note:** code matching the exact former failure string now receives an `Error` instead.
-- **Fixed — the environment beats the secrets file again, and three malformed `secrets.file` shapes are caught.** The two environment tiers were joined with `||`, and the CLI stores swept `GINA_*`/`VENDOR_*`/`USER_*` values as real booleans — so a key whose swept value was boolean `true` satisfied the short-circuit, `process.env` was never consulted, and the file tier won over a perfectly good environment variable, letting a stale plaintext file shadow a platform-injected credential. The tiers are now read independently. **Action required if you use the file tier:** a whitespace-only entry and a path containing an empty segment (`//`) now refuse to boot rather than failing as a suppressed debug line. The empty segment is worth a look — it is what a `${...}` token that resolved to nothing leaves behind, but a token carrying a *trailing slash* produces the same shape and resolves to exactly the intended file, so a config that worked before will now refuse; removing the doubled separator resolves it.
-- **Fixed — a bundle whose release tree cannot be linked says which bundle, and why.** The config loader built a useful error carrying the offending path, but the receiving callback never inspected it and dereferenced the absent configuration object instead — so the reason was discarded and the process died on an opaque `TypeError`. Because the configuration load is shared across the project, one bundle's missing release tree took down every bundle in it. The error is now reported through the same sink the bundle-configuration loader already used, naming the bundle, env and scope.
-- **Fixed — `self.push()` refuses by name when there is no engine.io channel.** The push channel is an isaac-engine facility, so on the Express engine the client lookup dereferenced an absent `eio` and surfaced as an opaque 500 that named neither push nor the missing channel. It now warns, hands a supplied callback a `PUSH_CHANNEL_NOT_CONFIGURED` error, and sends nothing — without failing the request, so a notification side-channel no longer takes down the response it rode in on. This is also the first time `push()` honours the `callback(err, result)` contract its documentation always described.
-- **Fixed — the port-setup merge read the wrong list.** The pass that folds newly seen protocols and schemes into a project's registry lists indexed the project's own list by the contextual list's position, so once the contextual list outgrew it the overshoot read `undefined`. No user-visible consequence was demonstrated, so this ships as a correctness fix.
+**This release adds maintenance mode and closes a cross-site request forgery hole
+in the admin endpoints.** It also makes boot-time bundle mounts safe when several
+processes share one project tree — replicas over a POSIX network filesystem, or
+containers bind-mounting a single checkout. **Two behaviour changes to check
+before you upgrade** — a real directory sitting at a bundle's mount path is now
+refused loudly instead of being silently deleted, and cross-origin writes to the
+`/_gina/*` control endpoints are now refused. Both are covered in the
+[migration guide](https://gina.io/docs/migration).
+
+- **Added — maintenance mode.** A bundle can now be closed to the public without being stopped, via `settings.json > server.maintenance`. While a window is open every request except the framework's own `/_gina/*` endpoints is answered `503` with a `Retry-After` header and `Cache-Control: no-store`, carrying a self-contained page for a browser navigation and the standard JSON body for XHR, SPA-fragment and JSON callers. The gate runs on **both engines**, placed ahead of static assets, both output-cache serve points and routing — so unlike a route middleware, which only runs once a route has matched, it also covers static files and URLs that match no route at all. The liveness endpoint deliberately keeps answering `200`, so an orchestrator does not restart healthy instances over a declared window, and the toggle itself stays reachable so you are never stranded outside your own off switch. Chosen visitors can still browse: a shared bypass key works as a header, or once in the address bar — which then sets a short-lived cookie and redirects without the secret — under any deployment; the supplementary IP allowlist applies only to requests that did not arrive through a reverse proxy, since behind one every address is the proxy's. Maintenance can also be flipped at runtime through an admin-gated endpoint with an optional expiry; a runtime flip is not persisted, and a lapsed expiry reverts to your *configuration* rather than to "off", so a forgotten timer cannot re-open a site that configuration says is closed.
+- **Security — cross-origin writes to admin `/_gina/*` endpoints are refused (#B384).** Present in every release up to and including `0.6.9`. These endpoints authorise callers by IP allowlist alone (`app.json` `admin.allowFrom`, loopback by default), and a browser attaches that ambient credential automatically — so an operator browsing from an allowlisted machine could be lured to a page that silently issued writes to `/_gina/storage/gc`, `/_gina/cache/clear`, `/_gina/release/rebuild` or `/_gina/maintenance`. The first three read their entire input from the query string and never read a body, so the attack needed no JavaScript and no CORS involvement at all: a plain auto-submitting form was enough. Such a write is now refused with `403` on both engines, using `Sec-Fetch-Site` where the browser sends it and comparing `Origin` against the connected authority otherwise — never against a forwarded header. **Two things are deliberately unaffected:** requests carrying no browser origin signal (`curl`, the gina CLI, deploy scripts) still work, so operator tooling is unchanged; and safe methods are untouched, so cross-origin `GET`/SSE channels keep working. No configuration change is required.
+- **Fixed — boot-time bundle mounts are idempotent, atomic and concurrency-safe.** Every boot re-created every declared bundle's mount symlink in two non-atomic steps — unlink, then create — with no mutual exclusion anywhere in the framework, and the config loader did it for *every* declared bundle on *every* load. With a single process that is invisible. With several processes booting one shared project tree it is a race on the same directory entries: the mount name genuinely disappears between the two steps, so a boot could fail outright on a contended create, and because the configuration load is shared, one contended link could abort it for every bundle in the project. Mounting is now idempotent and atomic. A link that already resolves to its intended source is left completely alone — the steady-state boot writes nothing at all, which is what removes the contention rather than merely surviving it. A wrong or missing link is published atomically through a temporary sibling and a rename, so the name is never absent and two processes cannot collide. And a process that loses the race to another one publishing the *identical* link now treats that as success instead of refusing to boot. Genuine failures are still loud: a release whose source has vanished, or a real directory occupying the mount path, refuse by name. The same class of race is closed on the directory creation that accompanies a mount. **Contract note:** a real directory at a bundle's mount path used to be deleted and replaced with the link during config load, and now refuses the boot instead — if you hit that, remove or relocate the directory.
+- **Docs — the guidance on addressing an out-of-request push is corrected.** `0.6.9` introduced `gina.pushToSession()` and warned against sourcing its recipient from the browser. That warning was written broadly enough to read as forbidding a **server-minted, integrity-protected token** that names the recipient — which is in fact the sanctioned shape, and the one the authenticated-hop pattern already relied on. The prohibition is now scoped to what it always meant: a *bare* recipient id in a client-writable field. The sanctioned shape is documented with the conditions that make it safe — verify the token and derive the recipient only from its verified claims, fail closed when it is absent or unverifiable, and keep it short-lived, since targeting integrity is not replay immunity.
 
 ## Documentation
 

package/ROADMAP.md

@@ -60,6 +60,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.6` ✅ | **Fixed**: the logging-transport release. A slow boot no longer silences a bundle's logging for the life of the process — a two-second connect deadline added in `0.6.5` read a socket flag Node clears one event-loop phase later, so any boot that blocked the loop past it destroyed a connection the kernel had already established (every container start and network-filesystem mount was exposed, and the transport never redialled). The MQ and file log transports also stopped dialling `host_v4`, which on a `~/.gina` shared across hosts silently shipped every log line off-host while all connection lines read healthy. Plus: the popin `success` event fires again instead of raising a 422 carrying the successful response body; a link request belongs to the anchor you clicked rather than the first anchor sharing its url; and constructing the link handler twice no longer corrupts the first instance · **Added**: the log transport reconnects — exponential backoff to a 30-second ceiling, one report per outage, frames dropped rather than queued while down so an outage cannot grow memory |
 | **Q4 2026** | `0.6.7` ✅ | **Added**: the object-storage release — a `storage` block declares named drivers (an adapter crossed with a strategy) reachable as `gina.storage()`, publishing objects atomically under opaque keys with their metadata written through a pluggable store seam; a content-addressed `cas` strategy deduplicates identical bytes behind a reference count, reclaiming them only after a grace-gated sweep; size tiering keeps sub-`64KB` objects inline in the metadata store, measurably faster than per-file writes; `storage:stats` / `storage:gc` / `storage:verify` operate a bundle's drivers whether it is running or stopped, through always-on admin-gated endpoints; and an upload group can route its `self.store()` step straight into a driver · **Security**: bound query parameter values no longer reach dev consoles or the Inspector query log — count and type markers replace them, with `inspector.queries.captureValues` to opt back in · **Fixed**: the `is` rule compiles regex literals as authored instead of stripping their parentheses (stricter — review patterns containing parens), forms with an async `query` rule complete correctly across a cluster of interacting defects (a submit leaving before the verdict landed, a completion carrying only the query field's slice, a re-click clearing later fields' errors, a clean form whose query field was not declared last never submitting at all, replayed submits from stale listeners, and an id-less trigger bound twice), `getConfig().settings` resolves path placeholders, `req.files[].group` reports the resolved group instead of `undefined`, and the Inspector's Data and Forms tabs stop putting framework-internal keys and the bundle catalog above your own data · **Changed**: framework default looks ship inside a `@layer gina` cascade layer, so any un-layered project rule overrides them without `!important` |
 | **Q4 2026** | `0.6.8` ✅ | **Security**: `self.push()` decides its recipient server-side instead of reading it from the request, where a supplied session id aimed the push at any session and an absent one broadcast to every connected client (ACTION REQUIRED — a bare worker push over an HTTP hop that carried the recipient IN THE REQUEST stops delivering; where the hop is authenticated the controller can pass `{ sessionID }` explicitly and keep working, and a worker with no request context at all polls `GET /_gina/jobs/:id`) · forwarded headers (`X-Forwarded-Host`, `-Proto`, `-Prefix` and the request's own `Host`) are validated where they are read, closing a reflected-XSS path that spliced them unescaped into the client bootstrap script emitted on every rendered page · **Added**: storage metadata can live on Couchbase, which is what makes a driver root shareable across bundles and replicas; a `stream` strategy for large sequential media brings resumable, out-of-order, restart-surviving uploads whose finalise verifies coverage as an interval union and refuses to publish a gap; HTTP Range serving through `self.serveFromStorage()` on both engines, with conditional GET and a fail-closed content-type downgrade; the `s3` adapter completes the pluggable object-storage layer, storeless by design and able to offload GET/HEAD to a presigned URL; `getRange()` on every local strategy; machine-readable `err.code` on storage read verbs; and the Couchbase soak probes ship in the package · **Changed**: `renderStream()` is byte-serving-capable — `Buffer` chunks pass through verbatim on non-SSE content types (binary payloads previously arrived corrupted), HEAD answers headers-only without consuming the iterable, and caller-set headers are no longer clobbered · **Fixed**: `renderStream()` honours a caller-set status on both engines and stops throwing a swallowed error at the end of every streamed response, a redirect treats `HEAD` as the safe method it is and keeps the caller's query string under `keep-params: true`, and a local storage driver reclaims the temp files left behind by a crashed or refused `put()` |
+| **Q4 2026** | `0.6.10` ✅ | **Added**: maintenance mode — a bundle can be closed to the public without being stopped. When it is active every request except the framework's own built-in endpoints is answered `503` with a `Retry-After` header and a self-contained maintenance page, and the response is marked never to be stored so a cached copy cannot outlive the window. The gate runs on both engines ahead of static assets, the output cache and routing, so it also covers files and URLs that a route middleware never sees. The liveness endpoint deliberately keeps answering normally, so an orchestrator does not restart healthy instances over a declared window. Chosen visitors can still browse: a shared bypass key presented as a header or once in the address bar (which then sets a short-lived cookie and redirects without the secret) works under any deployment, while the supplementary IP allowlist applies only to requests that did not arrive through a reverse proxy — behind one, every address is the proxy's, so an unconditioned list would let either everybody or nobody through. Maintenance can be flipped at runtime through an administrator-gated endpoint with an optional expiry; a runtime flip is not persisted, and an expiry reverts to the configured state rather than to off, so a forgotten timer cannot re-open a site that configuration says is closed. **Fixed**: boot-time bundle mounts are idempotent, atomic and concurrency-safe — a mount symlink that already resolves to its source is left untouched (so the steady-state boot writes nothing), a wrong or missing one is published atomically through a temp sibling and a rename, and a process that loses the race to another publishing the identical link treats that as success instead of refusing to boot. Previously every boot re-created every declared bundle's link in two non-atomic steps with no mutual exclusion, so several processes sharing one project tree raced the same directory entries and a contended link could fail a boot or abort the shared configuration load for every bundle in the project. The same race is closed on the directory creation that accompanies a mount. Behaviour change: a real directory occupying a mount path is now refused by name instead of silently deleted. **Security**: cross-origin writes to the administrator-gated built-in endpoints are refused. Those endpoints authorise callers by network address alone — a credential a browser attaches automatically — so an operator browsing from an allowed machine could be lured to a page that silently issued writes to them; and because several of them read their whole input from the address rather than from a request body, the attack needed no scripting and no cross-origin negotiation at all. Such a write is now refused on both engines, using the browser's own request-context signal where it is sent, and otherwise comparing the stated origin against the address the client actually connected to — never against a forwarded header, which an attacker controls. Clients that send no browser origin signal, such as command-line tooling and deployment scripts, are deliberately unaffected, as are safe methods, so existing cross-origin read channels keep working. | `0.6.10` | 2026-08-16 |
 | **Q4 2026** | `0.6.9` ✅ | **Security**: an engine.io socket's session identity is derived server-side from the upgrade request's own cookie instead of a field the browser asserts on every message — any client could previously claim another user's session and receive the pushes addressed to it, which took strictly less than stealing the cookie, since a rendered page carries the bare session id while the cookie carries the signed form; the binding replays the bundle's own session middleware (same secret, store and cookie name, no new configuration) and fails closed, so an id-less socket receives only deliberate broadcasts · **Added**: `gina.pushToSession()` gives code with no request context — a job handler, a cron tick, a boot hook — a sanctioned route to a user's socket, with a required recipient, no reachable broadcast, and delivery reported rather than assumed; and a bundle can declare which scopes it is deployed in through a `scopes` allow-list on its manifest entry, so one still under development stays out of every other scope · **Fixed**: `engine: "express"` bundles boot and serve on Express 5, with the supported range declared for the first time (`>= 4 < 6`, both majors verified live) · `project:add`/`project:import` no longer empty a project's `bundles` block on a declared-count mismatch, no longer adopt a bundle's invalid `server.protocol`/`server.scheme` into the project's registry lists, and no longer resolve one project's bundles against another project's path · `project:add` writes the `.gitignore` the shipped template's underscore prefix has always implied · the path helper's copier stages to a temp sibling and publishes with an atomic rename, so a failed copy can no longer destroy the destination it was replacing · the secrets resolver reads its two environment tiers independently, so a swept boolean no longer lets a plaintext file shadow `process.env`, and three malformed `settings.secrets.file` shapes that used to pass in silence are caught (ACTION REQUIRED — two of them now refuse to boot) · a bundle whose release tree cannot be linked refuses by name instead of dying as an opaque TypeError · `self.push()` refuses by name when the server instance has no engine.io channel |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |

package/framework/v0.6.10/VERSION

@@ -0,0 +1 @@
+0.6.10

package/framework/{v0.6.9 → v0.6.10}/core/config.js

@@ -844,20 +844,28 @@ function Config(opt, contextResetNeeded) {
 
             appPath = _(root +'/'+ pkg[app].link, true);
             console.debug('[CONFIG] Checking appPath [ '+ appPath +' ] ');
-            // cleanup symlinks
-            let targetAppPathObj = new _(appPath, true);
-            if ( targetAppPathObj.existsSync() ) {
-                targetAppPathObj.rmSync()
-            }
+            // #B381 — this loop runs for EVERY declared bundle on EVERY config
+            // load, and it used to unlink-then-recreate each bundle's link in
+            // two non-atomic steps: with N processes sharing one project tree
+            // that is N×M unserialised rewrites of the same names, and a lost
+            // race aborted the whole shared config load. ensureSymlinkSync()
+            // keeps a correct link untouched — the steady-state load now
+            // writes nothing — and publishes a wrong/missing one atomically.
+            // was:
+            // let targetAppPathObj = new _(appPath, true);
+            // if ( targetAppPathObj.existsSync() ) {
+            //     targetAppPathObj.rmSync()
+            // }
+            let targetAppPathObj = null;
             try {
                 if (envIsDev) {
                     targetAppPathObj = new _(root +'/'+ pkg[app].src, true);
                     console.debug('[CONFIG][env:'+env+'][envIsDev:'+ envIsDev +'] Linking ['+ targetAppPathObj.toString() +'] to [ '+ appPath +' ] ');
-                    targetAppPathObj.symlinkSync(appPath);
+                    targetAppPathObj.ensureSymlinkSync(appPath);
                 } else {
                     targetAppPathObj = new _(root +'/'+ pkg[app].releases[scope][env].target, true);
                     console.debug('[CONFIG][env'+env+'][envIsDev:'+ envIsDev +'] Linking ['+ targetAppPathObj.toString() +'] to [ '+ appPath +' ] ');
-                    targetAppPathObj.symlinkSync(appPath);
+                    targetAppPathObj.ensureSymlinkSync(appPath);
                 }
             } catch (releaseError) {
                 console.error('[ releaseError ] ', releaseError);

package/framework/{v0.6.9 → v0.6.10}/core/gna.js

@@ -598,7 +598,12 @@ var isBundleMounted = function(projects, bundlesPath, bundle, cb) {
 
     console.debug('Is `'+ bundle +'` mounted ?', isMounted);
     if (!gna.started && isMounted) {
-        new _( project.path +'/'+ manifest.bundles[bundle].link ).rmSync();
+        // #B381 — no pre-unlink here: removing the mount before re-creating it
+        // left a window where a sibling process booting the same project tree
+        // observed a missing link. gna.mount() is idempotent now (it keeps a
+        // correct link as-is and atomically replaces a wrong one), so forcing
+        // the mount call is enough.
+        // was: new _( project.path +'/'+ manifest.bundles[bundle].link ).rmSync();
         isMounted = false;
     }
     if (!isMounted) {
@@ -711,6 +716,11 @@ gna.getProjectConfiguration = function (callback){
 /**
  * Mounts a bundle release directory into the project's bundles/ directory
  * by creating required folders (bundles, tmp, cache) and symlinking the source.
+ * Idempotent and concurrency-safe (#B381): a link that already resolves to the
+ * source is kept untouched, a wrong or missing one is published atomically,
+ * and a concurrent identical creator is treated as success — so several
+ * processes may boot one shared project tree without racing each other's
+ * mounts.
  * When `type` is omitted it defaults to `'dir'`.
  *
  * Also exposed as `process.mount`.
@@ -731,28 +741,21 @@ gna.mount = process.mount = function(bundlesPath, source, target, type, callback
 
     //creating folders.
     //use junction when using Win XP os.release == '5.1.2600'
+    // #B381 — create-if-missing WITHOUT the exists/mkdir two-step: two
+    // processes booting the same project tree raced the check-then-create,
+    // and the loser threw EEXIST out of the mount, uncaught. `recursive: true`
+    // never throws on an existing directory, so the race disappears.
     var mountingPath = getPath('project') + '/bundles';
     console.debug('mounting path: ', mountingPath);
-    if ( !fs.existsSync(mountingPath) ) {
-        new _(mountingPath).mkdirSync();
-    }
+    fs.mkdirSync(mountingPath, { recursive: true });
     // /tmp
     var tmpPath = getPath('project') + '/tmp';
     console.debug('tmp path: ', tmpPath);
-    var tmpPathObj = new _(tmpPath);
-    if ( !tmpPathObj.existsSync() ) {
-        tmpPathObj.mkdirSync();
-    }
-    tmpPathObj = null;
-
+    fs.mkdirSync(tmpPath, { recursive: true });
     // cache
     var cachePath = getPath('project') + '/cache';
     console.debug('cache path: ', cachePath);
-    var cachePathObj = new _(cachePath);
-    if ( !cachePathObj.existsSync() ) {
-        cachePathObj.mkdirSync();
-    }
-    cachePathObj = null;
+    fs.mkdirSync(cachePath, { recursive: true });
 
     var sourceObj = new _(source);
     var targetObj = new _(target);
@@ -762,14 +765,20 @@ gna.mount = process.mount = function(bundlesPath, source, target, type, callback
     ;
     console.debug('[ FRAMEWORK ][ MOUNT ] Source: ', source);
     console.debug('[ FRAMEWORK ][ MOUNT ] Checking before mounting ', target, isTargetFound, bundlesPath);
-    if ( isTargetFound ) {
-        try {
-            console.debug('[ FRAMEWORK ][ MOUNT ] removing old build ', target);
-            fs.unlinkSync(target)
-        } catch (err) {
-            callback(err)
-        }
-    }
+    // #B381 — the early unlink is gone: it opened the absent-name window at
+    // the TOP of the mount (spanning the whole createPathSync walk below), and
+    // its catch called callback(err) WITHOUT returning, so a lost race (a
+    // sibling removing the link first) aborted the boot AND fell through into
+    // a second callback. ensureSymlinkSync() below replaces atomically instead.
+    // was:
+    // if ( isTargetFound ) {
+    //     try {
+    //         console.debug('[ FRAMEWORK ][ MOUNT ] removing old build ', target);
+    //         fs.unlinkSync(target)
+    //     } catch (err) {
+    //         callback(err)
+    //     }
+    // }
 
     // hack to test none-dev env without building: in case you did not build your bundle, but you have the src available
     if (!isSourceFound && !isDev) {
@@ -792,21 +801,24 @@ gna.mount = process.mount = function(bundlesPath, source, target, type, callback
     }
 
     if ( isSourceFound ) {
-        //will override existing each time you restart.
+        // #B381 — was: unlink-then-recreate on every restart ("will override
+        // existing each time you restart"), two non-atomic steps during which
+        // the mount name did not exist. Under two processes booting one shared
+        // project tree that window produced collisions on the contended names
+        // and killed the boot below. ensureSymlinkSync() keeps a correct link
+        // untouched, publishes a new one atomically (temp sibling + rename),
+        // and treats a concurrent identical creator as success.
         gna.lib.generator.createPathSync(bundlesPath, function onPathCreated(err){
             if (!err) {
                 try {
-                    // var targetObj = new _(target);
-                    if ( targetObj.existsSync() ) {
-                        targetObj.rmSync();
-                    }
+                    // was:
+                    // if ( targetObj.existsSync() ) {
+                    //     targetObj.rmSync();
+                    // }
                     console.debug('[ FRAMEWORK ][ MOUNT ] Linking ['+ source +'] to [ '+ target +' ] ');
-                    if ( type != undefined) {
-                        fs.symlinkSync(source, target, type)
-                    } else {
-                        fs.symlinkSync(source, target);
-                    }
-                    // symlink created
+                    new _(source).ensureSymlinkSync(target, type);
+                    // symlink created (or kept / atomically replaced / adopted
+                    // from a concurrent boot of the same tree)
                     callback(false);
 
                 } catch (err) {
@@ -817,17 +829,22 @@ gna.mount = process.mount = function(bundlesPath, source, target, type, callback
                         try { fs.writeSync(2, _mountMsg + '\n'); } catch (_e) { /* best-effort */ }
                         process.exit(1)
                     }
-                    if ( fs.existsSync(target) ) {
-                        var stats = fs.lstatSync(target);
-                        if ( stats.isDirectory() ) {
-                            var d = new _(target).rm( function(err){
-                                callback(err);
-                            })
-                        } else {
-                            fs.unlinkSync(target);
-                            callback(err)
-                        }
-                    }
+                    // #B381 — the recovery below was structurally unreachable
+                    // (the `if (err)` above always fires inside a catch, so the
+                    // exit is unconditional); the tolerance it intended now
+                    // lives in ensureSymlinkSync()'s verify-then-accept path.
+                    // was:
+                    // if ( fs.existsSync(target) ) {
+                    //     var stats = fs.lstatSync(target);
+                    //     if ( stats.isDirectory() ) {
+                    //         var d = new _(target).rm( function(err){
+                    //             callback(err);
+                    //         })
+                    //     } else {
+                    //         fs.unlinkSync(target);
+                    //         callback(err)
+                    //     }
+                    // }
                 }
             } else {
                 console.error(err);
@@ -1762,6 +1779,29 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                                     console.warn('[transient-errors] config validation skipped: ' + (teErr.message || teErr));
                                 }
 
+                                // #MAINT1 — `server.maintenance` boot-time shape check
+                                // (warn-only, NEVER fatal, exactly as #CE1 above: the
+                                // opt-in governs how a request RENDERS, so a bad value
+                                // must not refuse a boot). The engine-side reader
+                                // (lib.maintenance.resolveConf, boot-resolved in
+                                // core/server.js) independently falls back to the same
+                                // defaults per key — this lint exists so that fallback
+                                // is never SILENT. Per-key, not all-or-nothing: a bad
+                                // retryAfter must not disable the whole feature and
+                                // leave an operator believing the site is closed.
+                                try {
+                                    var _mtBlock = null;
+                                    try {
+                                        _mtBlock = config.getInstance()[gna.core.startingApp][env].server.maintenance;
+                                    } catch (mtConfErr) { _mtBlock = null; }
+                                    var _mtWarnings = lib.maintenance.lintConf(_mtBlock);
+                                    for (var _mtW = 0; _mtW < _mtWarnings.length; ++_mtW) {
+                                        console.warn('[maintenance] ' + _mtWarnings[_mtW]);
+                                    }
+                                } catch (mtErr) {
+                                    console.warn('[maintenance] config validation skipped: ' + (mtErr.message || mtErr));
+                                }
+
                                 // setting default global middlewares
                                 if ( typeof(instance.use) == 'function' ) {