gina 0.4.5 → 0.4.6

package/framework/v0.4.6/lib/template-loaders/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "gina-lib-template-loaders",
+  "version": "1.0.0",
+  "description": "Async template-loader extension point for the swig (and, later, nunjucks) render paths. Builds a built-in loader from its flat settings.template.<engine>.loader config (Slice 1: the in-memory loader) and wraps it with a CVE-2023-25345 segment-safety guard applied on every resolve(). Consumed by initSwigEngine (startup build + validation) and controller.render-swig-async.js (the isolated per-bundle swig engine).",
+  "authors": [
+    {
+      "name": "Martin-Luther ETOUMAN",
+      "email": "contact@gina.io"
+    }
+  ],
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engines": {
+    "node": ">=0.10.22"
+  },
+  "main": "src/main",
+  "license": "MIT"
+}

package/framework/v0.4.6/lib/template-loaders/src/loaders/http.js

@@ -0,0 +1,272 @@
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @module lib/template-loaders/http
+ * @description Built-in HTTP(S)-fetch template loader for the async loader
+ * extension point (`settings.template.<engine>.loader.type === "http"`).
+ * Resolves each template identifier to an absolute URL under a configured
+ * `origin` + `basePath`, fetches the source over node `https`/`http` (no SDK),
+ * and caches it via `lib/cache` keyed by the resolved URL — a Tier-1 source
+ * cache with an absolute TTL plus opt-in ETag revalidation. Unblocks
+ * deployments where templates ship separately from app code (S3 / R2 / GCS /
+ * CDN / a CMS endpoint).
+ *
+ * Loader contract: `resolve(to, from) -> absolute URL`, `load(id, cb)` (arity 2
+ * so swig's `getTemplate()` picks the callback load path), `async: true`. The
+ * gina CVE-2023-25345 segment-guard (applied by the wrapper in `main.js`)
+ * already rejected `..` / absolute identifiers BEFORE `resolve()` runs;
+ * `resolve()` adds the origin/basePath CONTAINMENT check — a second,
+ * independent boundary that also catches absolute-URL, protocol-relative and
+ * host-swap escapes the segment guard cannot see.
+ *
+ * Identifiers resolve ROOT-relative under `basePath` (a flat namespace: an
+ * `{% include "partials/x.html" %}` resolves to `<origin><basePath>/partials/x.html`,
+ * not relative to the including template's directory). Parent-relative `../`
+ * includes are rejected upstream by the segment guard.
+ *
+ * @package gina.framework
+ */
+
+var http  = require('http');
+var https = require('https');
+
+/**
+ * Default source-cache TTL in seconds (absolute, from fetch). 60s bounds
+ * staleness even with no revalidation while collapsing per-render fetches to
+ * ~once/template/minute under load. Immutable-CDN operators raise it (e.g.
+ * `ttl: 86400`); live-CMS operators turn on `revalidate` instead.
+ *
+ * @constant
+ * @inner
+ * @type {number}
+ */
+var DEFAULT_TTL_S = 60;
+
+/**
+ * Per-fetch socket timeout (ms). A hung origin must not hang the render.
+ *
+ * @constant
+ * @inner
+ * @type {number}
+ */
+var FETCH_TIMEOUT_MS = 10000;
+
+/**
+ * Build an HTTP(S)-fetch loader from its flat config. Validates shape only — it
+ * never reaches the backend, so a flaky/unreachable origin at boot is a
+ * render-time concern, not a bundle-startup failure (the no-network-probe rule).
+ *
+ * @param {object}  cfg                    - Loader config (`settings.template.<engine>.loader`)
+ * @param {string}  cfg.origin             - `scheme://host[:port]` of the template origin (no path). http or https.
+ * @param {string}  [cfg.basePath=""]      - Path prefix under origin every identifier resolves against.
+ * @param {number}  [cfg.ttl=60]           - Source-cache TTL in seconds (absolute from fetch). `0` = cache until evicted.
+ * @param {boolean} [cfg.revalidate=false] - When true, a cache hit issues a conditional GET (`If-None-Match`).
+ * @param {object}  [ctx]                  - Build context (`{ bundle }`) threaded from `initSwigEngine` for cache-key namespacing.
+ * @returns {{async: boolean, resolve: function, load: function}} Loader object
+ * @throws {Error} When `origin` is missing or not an http(s) URL
+ *
+ * @example
+ * var http = require('lib/template-loaders/http');
+ * var loader = http({ type: 'http', origin: 'https://cdn.example.com', basePath: '/templates' }, { bundle: 'site' });
+ * loader.load(loader.resolve('pages/home.html'), function (err, source) { ... });
+ */
+module.exports = function httpLoader(cfg, ctx) {
+    if (!cfg || typeof cfg.origin !== 'string' || cfg.origin === '') {
+        throw new Error('[template-loader:http] "origin" (scheme://host[:port]) is required');
+    }
+
+    var parsedOrigin;
+    try {
+        parsedOrigin = new URL(cfg.origin);
+    } catch (e) {
+        throw new Error('[template-loader:http] "origin" must be a valid URL: ' + cfg.origin);
+    }
+    if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:') {
+        throw new Error('[template-loader:http] "origin" must use http or https: ' + cfg.origin);
+    }
+
+    // Normalise basePath: leading slash, no trailing slash, "" when absent.
+    var basePath = (typeof cfg.basePath === 'string') ? cfg.basePath.trim() : '';
+    if (basePath.length > 0) {
+        if (basePath.charAt(0) !== '/') { basePath = '/' + basePath; }
+        basePath = basePath.replace(/\/+$/, '');
+    }
+
+    var originConst    = parsedOrigin.origin;            // e.g. https://cdn.example.com
+    var containPrefix  = originConst + basePath + '/';   // every resolved URL must start with this (note trailing /)
+    var transport      = (parsedOrigin.protocol === 'http:') ? http : https;
+    var ttlSeconds     = (typeof cfg.ttl === 'number' && cfg.ttl >= 0) ? cfg.ttl : DEFAULT_TTL_S;
+    var revalidate     = (cfg.revalidate === true);
+    var bundle         = (ctx && typeof ctx.bundle === 'string' && ctx.bundle) ? ctx.bundle : 'default';
+
+    /**
+     * Resolve a template identifier to an absolute URL under origin+basePath and
+     * containment-check it. The CVE segment-guard (main.js wrapper) already ran
+     * on `to`. Resolution is root-relative against `containPrefix` (`from` is not
+     * used for path construction — the namespace is flat under basePath); the
+     * containment check rejects anything escaping the configured origin/basePath.
+     *
+     * @inner
+     * @param {string}  to     - Template identifier (page, or an extends/include target)
+     * @param {string} [from]  - Resolving template's id (unused — flat-namespace resolution)
+     * @returns {string} Absolute URL string (also the cache key suffix + load() arg)
+     * @throws {Error} When the resolved URL escapes the configured origin/basePath
+     */
+    function resolve(to, from) {
+        var url;
+        try {
+            url = new URL(to, containPrefix);
+        } catch (e) {
+            throw new Error('[template-loader:http] cannot resolve template identifier: ' + to);
+        }
+        if (url.origin !== originConst || url.href.indexOf(containPrefix) !== 0) {
+            throw new Error('[template-loader:http] resolved URL escapes configured origin/basePath: ' + url.href);
+        }
+        return url.href;
+    }
+
+    /**
+     * Fetch `url` over the configured transport. Single-settle (error / timeout /
+     * end race exactly once). A 304 returns no body. Optional `If-None-Match`
+     * makes it a conditional GET.
+     *
+     * @inner
+     * @param {string}   url   - Absolute URL to fetch
+     * @param {?string}  etag  - When set, sent as `If-None-Match` (conditional GET)
+     * @param {function} cb    - `(err, statusCode, body, responseEtag)`
+     * @returns {void}
+     */
+    function fetchUrl(url, etag, cb) {
+        var settled = false;
+        function settle(err, status, body, respEtag) {
+            if (settled) { return; }
+            settled = true;
+            cb(err, status, body, respEtag);
+        }
+
+        var opts = {};
+        if (etag) { opts.headers = { 'If-None-Match': etag }; }
+
+        var req = transport.get(url, opts, function (res) {
+            var respEtag = (res.headers && res.headers.etag) ? res.headers.etag : null;
+            if (res.statusCode === 304) {
+                res.resume(); // drain so the socket frees
+                return settle(null, 304, null, etag);
+            }
+            var chunks = [];
+            res.on('data', function (chunk) { chunks.push(chunk); });
+            res.on('end', function () {
+                settle(null, res.statusCode, Buffer.concat(chunks).toString('utf8'), respEtag);
+            });
+            res.on('error', function (streamErr) { settle(streamErr); });
+        });
+        req.on('error', function (reqErr) { settle(reqErr); });
+        req.setTimeout(FETCH_TIMEOUT_MS, function () {
+            req.destroy(new Error('[template-loader:http] timeout (' + FETCH_TIMEOUT_MS + 'ms) fetching ' + url));
+        });
+    }
+
+    /**
+     * The shared gina cache, resolved LAZILY at load time. It is NOT available
+     * at loader-build time — `initSwigEngine` builds the loader before the
+     * server's shared Map is created in `start()`, so a build-time capture would
+     * grab nothing. The request pipeline points `process.gina._cache` at the
+     * server Map before any render-driven `load()`. Returns null when absent
+     * (e.g. a unit test with no server) so caching is skipped, not crashed.
+     *
+     * @inner
+     * @returns {?object} A `lib.Cache` instance, or null
+     */
+    function getCache() {
+        return (typeof process.gina === 'object' && process.gina && process.gina._cache) ? process.gina._cache : null;
+    }
+
+    /**
+     * Cache key for a resolved URL: `tpl:src:<bundle>:<URL>` (mirrors the
+     * `static:<bundle>:<url>` convention of the static-HTML response cache, with
+     * a distinct `tpl:src:` prefix so the two never collide).
+     *
+     * @inner
+     * @param {string} url - Resolved absolute URL
+     * @returns {string} Cache key
+     */
+    function cacheKey(url) {
+        return 'tpl:src:' + bundle + ':' + url;
+    }
+
+    return {
+        // Dispatch flag — routes the bundle to the async swig delegate and tells
+        // swig's renderFile to take the async getTemplate path.
+        async: true,
+
+        resolve: resolve,
+
+        // Arity 2 (id, cb) so swig.getTemplate() uses the callback load path. A
+        // network fetch is callback-only — there is no synchronous return path.
+        load: function (id, cb) {
+            var cache = getCache();
+            var key   = cacheKey(id);
+            var hit   = (cache && typeof cache.get === 'function') ? cache.get(key) : undefined;
+
+            if (hit && typeof hit.source === 'string') {
+                if (!revalidate || !hit.etag) {
+                    // Fresh hit, no revalidation to do → serve cached source.
+                    return void cb(null, hit.source);
+                }
+                // Revalidate via a conditional GET.
+                return void fetchUrl(id, hit.etag, function (err, status, body, respEtag) {
+                    if (err) {
+                        // Flaky origin during revalidation — serve stale rather
+                        // than 500 a page that is only slightly out of date.
+                        return void cb(null, hit.source);
+                    }
+                    if (status === 304) {
+                        // Unchanged — refresh the TTL, serve cached source.
+                        if (cache) { cache.set(key, makeEntry(hit.source, hit.etag)); }
+                        return void cb(null, hit.source);
+                    }
+                    if (status === 200) {
+                        if (cache) { cache.set(key, makeEntry(body, respEtag)); }
+                        return void cb(null, body);
+                    }
+                    return void cb(new Error('[template-loader:http] ' + status + ' revalidating ' + id));
+                });
+            }
+
+            // Miss (or expired, or no cache) → unconditional GET.
+            return void fetchUrl(id, null, function (err, status, body, respEtag) {
+                if (err) { return void cb(err); }
+                if (status === 200) {
+                    if (cache) { cache.set(key, makeEntry(body, respEtag)); }
+                    return void cb(null, body);
+                }
+                return void cb(new Error('[template-loader:http] ' + status + ' fetching ' + id));
+            });
+        }
+    };
+
+    /**
+     * Build a cache-entry value. `ttl` (seconds) drives `lib/cache` expiry;
+     * `fromMemory` classifies it under "memory" in `/_gina/cache/stats`.
+     *
+     * @inner
+     * @param {string}  source - Template source
+     * @param {?string} etag   - Origin ETag (for revalidation), or null
+     * @returns {object} Cache value
+     */
+    function makeEntry(source, etag) {
+        return {
+            source:     source,
+            etag:       etag || null,
+            fetchedAt:  Date.now(),
+            ttl:        ttlSeconds,
+            fromMemory: true
+        };
+    }
+};

package/framework/v0.4.6/lib/template-loaders/src/loaders/memory.js

@@ -0,0 +1,75 @@
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @module lib/template-loaders/memory
+ * @description Built-in in-memory template loader for the async loader
+ * extension point (`settings.template.<engine>.loader.type === "memory"`).
+ * Templates are supplied inline as a flat `identifier -> source` map in the
+ * loader config — no filesystem, no network. Useful for tests and small,
+ * self-contained template sets.
+ *
+ * Implements the two-method swig/nunjucks loader contract (`resolve` + `load`)
+ * plus the `async: true` dispatch flag. `load` is dual-mode (callback form and
+ * synchronous return) with arity 2 so swig's async `getTemplate()` picks the
+ * callback load path (it gates on `load.length >= 2`).
+ *
+ * @package gina.framework
+ */
+
+/**
+ * Build an in-memory loader from a templates map.
+ *
+ * @param {object} cfg            - Loader config (`settings.template.<engine>.loader`)
+ * @param {Object.<string,string>} cfg.templates - Flat map of identifier -> source string
+ * @returns {{async: boolean, resolve: function, load: function}} Loader object
+ * @throws {Error} When `cfg.templates` is not a plain object map
+ *
+ * @example
+ * var memory = require('lib/template-loaders/memory');
+ * var loader = memory({ templates: { 'index.html': '<h1>{{ title }}</h1>' } });
+ * loader.load('index.html', function (err, source) { ... });
+ */
+module.exports = function memory(cfg) {
+    if (
+        !cfg
+        || typeof cfg.templates !== 'object'
+        || cfg.templates === null
+        || Array.isArray(cfg.templates)
+    ) {
+        throw new Error('[template-loader:memory] "templates" must be an object map of identifier -> source string');
+    }
+    var map = cfg.templates;
+
+    return {
+        // Dispatch flag — read by swig's renderFile and by gina's delegate
+        // selection (controller.js routes async-loader bundles to the async
+        // delegate). Always true for this loader.
+        async: true,
+
+        // Identity resolve — the supplied identifier IS the map key. extends /
+        // include targets pass through here too, so the gina CVE segment-guard
+        // (applied by the wrapper in main.js) covers the whole transitive chain.
+        resolve: function (to, from) {
+            return to;
+        },
+
+        // Dual-mode load. Arity 2 (identifier, cb) so swig.getTemplate() uses
+        // the callback path; the synchronous return keeps the loader usable by
+        // any sync consumer.
+        load: function (identifier, cb) {
+            if (cb) {
+                if (!Object.prototype.hasOwnProperty.call(map, identifier)) {
+                    return void cb(new Error('[template-loader:memory] template not found: ' + identifier));
+                }
+                return void cb(null, map[identifier]);
+            }
+            return map[identifier];
+        }
+    };
+};

package/framework/v0.4.6/lib/template-loaders/src/main.js

@@ -0,0 +1,134 @@
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @module lib/template-loaders
+ * @description Registry + factory for gina's async template-loader extension
+ * point (`settings.template.<engine>.loader`). Builds a built-in loader from
+ * its flat config — a named `type` plus type-specific keys, mirroring the
+ * `connectors.json` convention — and wraps it with a CVE-2023-25345
+ * segment-safety guard applied on EVERY `resolve()`, covering the whole
+ * transitive extends/include chain (stronger than a first-hop-only guard).
+ *
+ * Ships two built-ins: `memory` (inline templates, no network) and `http`
+ * (HTTP(S)-fetch from a configured origin + basePath, with a TTL'd source cache
+ * and opt-in ETag revalidation). A custom project-supplied loader hook lands in
+ * a later slice.
+ *
+ * @package gina.framework
+ */
+
+/**
+ * Built-in loader factories keyed by `type`. Grows one entry per slice.
+ *
+ * @constant
+ * @inner
+ * @type {Object.<string, function>}
+ */
+var BUILTINS = {
+    memory: require('./loaders/memory'),
+    http:   require('./loaders/http')
+};
+
+/**
+ * Assert a template identifier is segment-safe: not absolute and free of any
+ * parent-traversal (`..`) segment. Runs on every `resolve()` so it guards the
+ * full transitive extends/include chain, not just the first hop
+ * (CVE-2023-25345).
+ *
+ * @inner
+ * @param {string} id - Template identifier requested by the engine
+ * @returns {void}
+ * @throws {Error} When `id` is empty/non-string, absolute, or contains a `..` segment
+ */
+function assertSafeIdentifier(id) {
+    if (typeof id !== 'string' || id === '') {
+        throw new Error('[template-loader] invalid template identifier: ' + JSON.stringify(id));
+    }
+    if (id.charAt(0) === '/' || id.charAt(0) === '\\') {
+        throw new Error('[template-loader] absolute template path rejected: ' + id);
+    }
+    var segs = id.split(/[\\/]/);
+    for (var i = 0; i < segs.length; i++) {
+        if (segs[i] === '..') {
+            throw new Error('[CVE-2023-25345] template path traversal blocked: ' + id);
+        }
+    }
+}
+
+/**
+ * Wrap a built-in (or, later, user-supplied) loader with the gina CVE
+ * segment-guard. The guard runs inside `resolve()`; `load` is re-exposed via
+ * `.bind()` so its `.length` (arity) is preserved — swig's `getTemplate()`
+ * uses `load.length >= 2` to choose the callback load path, so a wrapper that
+ * dropped the arity would silently break async loading.
+ *
+ * @inner
+ * @param {object} inner - Loader exposing `resolve(to, from)` + `load(id, cb)` [+ `async`]
+ * @returns {{async: boolean, resolve: function, load: function}} Guarded loader
+ * @throws {Error} When `inner` does not expose both `resolve()` and `load()`
+ */
+function wrapWithGuard(inner) {
+    if (!inner || typeof inner.resolve !== 'function' || typeof inner.load !== 'function') {
+        throw new Error('[template-loader] loader must expose resolve(to, from) and load(identifier, cb)');
+    }
+    return {
+        async: inner.async === true,
+        resolve: function (to, from) {
+            assertSafeIdentifier(to);
+            return inner.resolve(to, from);
+        },
+        // .bind() preserves load.length (arity) — load-bearing for swig's
+        // callback-vs-sync load dispatch.
+        load: inner.load.bind(inner)
+    };
+}
+
+/**
+ * Build a guarded async loader from its bundle config, or return `null` when
+ * no loader is configured. Throws on a bad config so the caller
+ * (`initSwigEngine`) can let it propagate and fail bundle startup fast — the
+ * same fail-fast contract as `initNunjucksEngine`/`NUNJUCKS_NOT_INSTALLED`.
+ *
+ * @param {?object} [cfg]    - `settings.template.<engine>.loader` (absent -> null)
+ * @param {string}  cfg.type - Built-in loader name (`"memory"` | `"http"`)
+ * @param {object}  [ctx]    - Build context (`{ bundle }`) forwarded to the built-in factory for cache-key namespacing
+ * @returns {?{async: boolean, resolve: function, load: function}} Guarded loader, or null when `cfg` is absent
+ * @throws {Error} On unknown `type`, a loader missing `resolve`/`load`, or a built-in's own config error
+ *
+ * @example
+ * var loader = lib.templateLoaders.build({ type: 'memory', templates: { 'a.html': 'hi' } });
+ * // loader.async === true
+ * var remote = lib.templateLoaders.build({ type: 'http', origin: 'https://cdn.example.com' }, { bundle: 'site' });
+ */
+function build(cfg, ctx) {
+    if (cfg === null || typeof cfg !== 'object') {
+        return null;
+    }
+    var type = cfg.type;
+    if (typeof type !== 'string' || !Object.prototype.hasOwnProperty.call(BUILTINS, type)) {
+        throw new Error(
+            '[template-loader] unknown loader type ' + JSON.stringify(type) +
+            ' - expected one of: ' + Object.keys(BUILTINS).join(', ')
+        );
+    }
+    // The built-in factory validates its own flat config and throws on a bad
+    // shape; we let that propagate (fail-fast at bundle startup). `ctx` (e.g.
+    // `{ bundle }`) is forwarded for built-ins that namespace by bundle (the
+    // http source cache); built-ins that don't need it (memory) ignore it.
+    var inner = BUILTINS[type](cfg, ctx);
+    return wrapWithGuard(inner);
+}
+
+module.exports = {
+    build: build,
+    // Exposed for unit tests and future-slice built-in registration.
+    BUILTINS: BUILTINS,
+    assertSafeIdentifier: assertSafeIdentifier,
+    wrapWithGuard: wrapWithGuard
+};

package/framework/{v0.4.5 → v0.4.6}/package.json

@@ -1,8 +1,8 @@
 {
   "name": "gina-framework",
-  "version": "0.4.5-alpha.2",
+  "version": "0.4.6-alpha.2",
   "dependencies": {
-    "@rhinostone/swig": "^2.6.0",
+    "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",
     "psl": "^1.15.0",
     "ws": "^8.20.1"

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.4.5/core/gna');
+var _gna = require('./framework/v0.4.6/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.4.5/core/controller');
-var EntitySuper     = require('./framework/v0.4.5/core/model/entity');
+var SuperController = require('./framework/v0.4.6/core/controller');
+var EntitySuper     = require('./framework/v0.4.6/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.4.5/lib/uuid');
+var uuid = require('./framework/v0.4.6/lib/uuid');
 
 module.exports = {