@quonfig/cli 0.0.51 → 0.0.53

package/dist/serve/server.js

@@ -0,0 +1,355 @@
+/**
+ * HTTP server for `qfg serve`. Boots a single `@quonfig/node` Quonfig client
+ * with `{datadir, dataDirAutoReload}` so file changes flow into a shared
+ * snapshot (mirror of the SDK's `ConfigStore`). All requests evaluate against
+ * that snapshot — see plan project/plans/qfg-serve.md §5 ("Integration with
+ * auto-reload work").
+ *
+ * Bound by default to 127.0.0.1. Auth and CORS are configured per plan §4.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import { ConfigStore, Evaluator, Quonfig } from '@quonfig/node';
+import { handleEvalContext } from './handlers/evalContext.js';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+const isLoopback = (host) => LOOPBACK_HOSTS.has(host);
+export async function startServer(opts) {
+    // Loopback policy — plan §4 auth note. Refuse non-loopback binds without
+    // an explicit opt-in; this prevents the developer from accidentally
+    // exposing an unauthenticated server to their LAN.
+    const policyHost = opts.forceNonLoopbackForTest ?? opts.host;
+    if (!isLoopback(policyHost) && !opts.allowNonLoopback) {
+        throw new Error(`Refusing to bind ${opts.host}: pass --allow-non-loopback to confirm the server should be reachable from the LAN.`);
+    }
+    if (!isLoopback(policyHost) && opts.allowNonLoopback) {
+        opts.logger.warn(`qfg serve is bound to ${opts.host}: any device on your LAN can reach it. ` +
+            `Anyone with the URL gets the datadir contents; do not run this on an untrusted network ` +
+            `without --frontend-sdk-key.`);
+    }
+    // Canonicalize the datadir to its long-name absolute path before handing
+    // it to the SDK. On Windows, os.tmpdir() and short-name paths like
+    // `C:\Users\RUNNER~1\...` trip a libuv assertion in fs-event.c when
+    // fs.watch compares the registered dir against incoming event filenames
+    // (the input is the short name, the events come back as long names).
+    // realpathSync.native delegates to uv_fs_realpath, which returns the same
+    // canonical form libuv uses internally — so the assertion never fires.
+    // No-op on POSIX where short names don't exist.
+    const datadir = (() => {
+        try {
+            return fs.realpathSync.native(opts.datadir);
+        }
+        catch {
+            return opts.datadir;
+        }
+    })();
+    // The Quonfig client owns datadir loading + file watching via the
+    // `dataDirAutoReload` option that landed in sdk-node 0.0.30 (qfg-zx3y).
+    // We hold a parallel ConfigStore + Evaluator that mirror the client's
+    // internal state so the eval handler can call evaluator.evaluateConfig()
+    // directly — Quonfig's public surface (`get`, `rawConfig`, `getRawMatch`)
+    // doesn't return the typed Value object the EvalEnvelope shape needs.
+    let store = new ConfigStore();
+    let evaluator = new Evaluator(store);
+    const environment = opts.environment;
+    let version = '';
+    const refreshSnapshot = (client) => {
+        // Pull every config out of the client and stuff it into our parallel
+        // store. `keys()` and `rawConfig()` are public; they return the
+        // ConfigResponse exactly as the client loaded it from disk.
+        //
+        // NOTE: the SDK fires `onConfigUpdate` from inside its initial
+        // `loadLocalData()` call, BEFORE `init()` has flipped `initialized` to
+        // true. Calling `client.keys()` during that window would throw "Not
+        // initialized." We swallow that one case here — the post-init manual
+        // refresh covers the initial load.
+        let keys;
+        try {
+            keys = client.keys();
+        }
+        catch {
+            return;
+        }
+        const configs = [];
+        for (const key of keys) {
+            const cfg = client.rawConfig(key);
+            if (cfg)
+                configs.push(cfg);
+        }
+        // G8 (qfg-38sf.6): version is a content hash of the canonicalized
+        // configs, not the absolute datadir path. The old shape leaked operator
+        // filesystem layout on every response and changed on every reload even
+        // when the data was unchanged, defeating ETag-style caching.
+        version = computeVersion(configs);
+        const envelope = {
+            configs,
+            meta: { version, environment },
+        };
+        store = new ConfigStore();
+        evaluator = new Evaluator(store);
+        store.loadFromDatafile(envelope);
+    };
+    // qfg-zx3y's auto-reload fires `onConfigUpdate` after the SDK has installed
+    // the new envelope. We re-sync our snapshot from the client at that point.
+    const client = new Quonfig({
+        sdkKey: 'qfg-serve-local',
+        datadir,
+        environment: opts.environment,
+        dataDirAutoReload: opts.watch,
+        dataDirAutoReloadDebounceMs: opts.watchDebounceMs,
+        // Telemetry is intentionally OFF — qfg serve has no Quonfig backend to
+        // post to, and the SDK's default-on collectors would just buffer forever.
+        collectEvaluationSummaries: false,
+        contextUploadMode: 'none',
+        enableSSE: false,
+        fallbackPollEnabled: false,
+        onConfigUpdate() {
+            refreshSnapshot(client);
+            if (opts.verbose)
+                opts.logger.log(`qfg-serve: reloaded datadir (version=${version})`);
+        },
+    });
+    await client.init();
+    // Initial snapshot — the SDK fires onConfigUpdate during init() so this is
+    // mostly insurance against an init path that doesn't, but it's cheap.
+    if (store.keys().length === 0) {
+        refreshSnapshot(client);
+    }
+    // CORS resolution per request. Three shapes:
+    //  - `*` anywhere in the list → wildcard (no Vary)
+    //  - exactly one origin → fixed value (no Vary; caller pinned it)
+    //  - 2+ origins → allow-list: echo the request Origin if it matches and emit
+    //    `Vary: Origin`; omit the header entirely on a miss (qfg-38sf.5). The
+    //    CORS spec does not permit a comma-joined Access-Control-Allow-Origin,
+    //    so the previous `.join(', ')` was silently breaking browser clients.
+    const corsAllowList = new Set(opts.corsOrigins);
+    const corsMode = corsAllowList.has('*')
+        ? 'wildcard'
+        : opts.corsOrigins.length <= 1
+            ? 'fixed'
+            : 'allowlist';
+    const fixedCorsOrigin = corsMode === 'fixed' ? (opts.corsOrigins[0] ?? '*') : null;
+    // qfg-38sf.1 security audit F3: the sendToClientSdk filter is UNCONDITIONAL.
+    // Every qfg serve consumer is by definition a frontend client (browser /
+    // react-native — server SDKs use datadir mode directly). There is no flag
+    // that turns this off. See evalContext.ts for the filter itself.
+    // Bump maxHeaderSize so that oversized base64 context tokens reach our
+    // application-level 414 handler rather than getting bounced by Node's
+    // default 16KB header parser. Our app cap is 64KB (see evalContext.ts G6
+    // check); 256KB leaves room for the path plus normal Authorization /
+    // Cookie / Accept headers.
+    const server = http.createServer({ maxHeaderSize: 256 * 1024 }, async (req, res) => {
+        const startedAt = Date.now();
+        // CORS — emit on every response, including 401 and 404, so browser
+        // clients surface the real status code instead of an opaque CORS error.
+        if (corsMode === 'wildcard') {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+        else if (corsMode === 'fixed' && fixedCorsOrigin !== null) {
+            res.setHeader('Access-Control-Allow-Origin', fixedCorsOrigin);
+        }
+        else if (corsMode === 'allowlist') {
+            const reqOrigin = req.headers.origin;
+            // Vary: Origin regardless of match — caches must not reuse a
+            // matched-Origin response for a request from a different Origin.
+            res.setHeader('Vary', 'Origin');
+            if (typeof reqOrigin === 'string' && corsAllowList.has(reqOrigin)) {
+                res.setHeader('Access-Control-Allow-Origin', reqOrigin);
+            }
+        }
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type');
+        res.setHeader('Access-Control-Expose-Headers', 'ETag');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            logRequest(req, res, startedAt, opts);
+            return;
+        }
+        // Auth — plan §4. If --frontend-sdk-key was set, every non-OPTIONS
+        // request must present `Authorization: Basic base64("1:<key>")`. If it
+        // wasn't set, no check.
+        if (opts.frontendSdkKey) {
+            const ok = checkBasicAuth(req.headers.authorization, opts.frontendSdkKey);
+            if (!ok) {
+                res.writeHead(401, {
+                    'Content-Type': 'text/plain',
+                    'WWW-Authenticate': 'Basic realm="qfg-serve"',
+                });
+                res.end('unauthorized');
+                logRequest(req, res, startedAt, opts);
+                return;
+            }
+        }
+        const url = req.url ?? '/';
+        const [pathOnly] = url.split('?');
+        // GET /api/v2/configs/eval-with-context/{base64url}
+        const evalPrefix = '/api/v2/configs/eval-with-context/';
+        if (req.method === 'GET' && pathOnly.startsWith(evalPrefix)) {
+            const ctxToken = pathOnly.slice(evalPrefix.length);
+            if (!ctxToken) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                res.end('missing context token');
+                logRequest(req, res, startedAt, opts);
+                return;
+            }
+            try {
+                await handleEvalContext(req, res, ctxToken, {
+                    getSnapshot: () => ({ store, evaluator, environment, version }),
+                });
+            }
+            catch (error) {
+                opts.logger.warn(`qfg-serve: eval-with-context handler threw: ${error.message}`);
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'text/plain' });
+                    res.end('internal error');
+                }
+            }
+            logRequest(req, res, startedAt, opts);
+            return;
+        }
+        // POST /api/v1/telemetry/  → 404 with a helpful body. Plan §2: we
+        // intentionally don't accept telemetry — silently 200-OK-and-dropping
+        // would hide a misconfig.
+        if (req.method === 'POST' && pathOnly === '/api/v1/telemetry/') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'qfg serve does not accept telemetry',
+                hint: 'Disable client-side telemetry by passing `collectEvaluationSummaries: false` ' +
+                    '(and `contextUploadMode: "none"`) to your SDK init, or point the SDK\'s ' +
+                    'telemetryUrl at a real Quonfig telemetry endpoint.',
+            }));
+            logRequest(req, res, startedAt, opts);
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('not found');
+        logRequest(req, res, startedAt, opts);
+    });
+    // Bind. EADDRINUSE is the only common failure here; surface it with a
+    // pointed message so the developer doesn't have to read a stack trace.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener('listening', onListening);
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${opts.port} is already in use. Pass --port <n> to pick another.`));
+            }
+            else {
+                reject(err);
+            }
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(opts.port, opts.host);
+    });
+    const boundPort = server.address().port;
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+        });
+        try {
+            await client.close();
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    return { port: boundPort, host: opts.host, close };
+}
+/**
+ * G8 (qfg-38sf.6): compute meta.version as sha256 of the canonicalized
+ * configs array. Canonical form is `JSON.stringify(configs, sortedKeys)` so
+ * two snapshots with identical config content produce the same hash regardless
+ * of object-key order. The hash replaces the prior `datadir:<abs-path>#<ts>`
+ * shape, which leaked operator filesystem layout and changed on every reload
+ * even when the data was unchanged.
+ *
+ * Exported for unit tests that want to assert determinism / stability.
+ */
+export function computeVersion(configs) {
+    const canonical = JSON.stringify(configs, sortedKeyReplacer);
+    return `sha256:${crypto.createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+/**
+ * Replacer for JSON.stringify that emits object keys in sorted order. Arrays
+ * keep their original order (array order is semantically meaningful for rules
+ * and weighted-values).
+ */
+function sortedKeyReplacer(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Validate `Authorization: Basic base64("1:<key>")` against the configured
+ * SDK key. The browser SDKs build this header in
+ * `sdk-javascript/src/apiHelpers.ts:7`.
+ *
+ * G4: use `crypto.timingSafeEqual` instead of `===`. The frontend SDK key is
+ * publicly-available by design (plan §4) so this isn't a hard security
+ * boundary, but `timingSafeEqual` is the right default — cheap, correct, and
+ * removes a class of timing-leak nits from any future audit.
+ *
+ * Length check first because `timingSafeEqual` throws on mismatched buffer
+ * lengths; that throw is itself a timing side-channel (and an exception path).
+ */
+function checkBasicAuth(header, expectedKey) {
+    if (!header || !header.toLowerCase().startsWith('basic '))
+        return false;
+    const b64 = header.slice('basic '.length).trim();
+    let decoded;
+    try {
+        decoded = Buffer.from(b64, 'base64').toString('utf8');
+    }
+    catch {
+        return false;
+    }
+    const expected = `1:${expectedKey}`;
+    const decodedBuf = Buffer.from(decoded, 'utf8');
+    const expectedBuf = Buffer.from(expected, 'utf8');
+    if (decodedBuf.length !== expectedBuf.length)
+        return false;
+    return crypto.timingSafeEqual(decodedBuf, expectedBuf);
+}
+/**
+ * Verbose-mode request log. G1 (qfg-38sf.1 audit): redact the base64-encoded
+ * context token from the URL — it contains caller PII (email, user id,
+ * arbitrary attributes). Format matches api-delivery's LoggingMiddleware
+ * shape: `METHOD PATH STATUS DURATION_MS`. We elide the ctx segment so the
+ * path collapses to e.g.
+ *   `GET /api/v2/configs/eval-with-context/<ctx-redacted> 200 3ms`
+ * which still tells the developer which route fired without leaking the
+ * payload.
+ */
+function logRequest(req, res, startedAt, opts) {
+    if (!opts.verbose)
+        return;
+    const method = req.method ?? '-';
+    const rawUrl = req.url ?? '/';
+    const [pathOnly, query] = rawUrl.split('?', 2);
+    const evalPrefix = '/api/v2/configs/eval-with-context/';
+    let safePath = pathOnly;
+    if (pathOnly.startsWith(evalPrefix)) {
+        safePath = `${evalPrefix}<ctx-redacted>`;
+    }
+    // Drop query string entirely — collectContextMode and friends are fine to
+    // surface but we have no allowlist parser today, so be conservative.
+    if (query && query.length > 0)
+        safePath += '?<redacted>';
+    const status = res.statusCode;
+    const duration = Date.now() - startedAt;
+    opts.logger.log(`qfg-serve: ${method} ${safePath} ${status} ${duration}ms`);
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.51";
+declare const _default: "0.0.53";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.0.51';
+export default '0.0.53';

package/oclif.manifest.json

@@ -2064,6 +2064,121 @@
         "sdk-key.js"
       ]
     },
+    "serve": {
+      "aliases": [],
+      "args": {},
+      "description": "Serve a local datadir over HTTP to browser/RN SDKs.\n\nReads configs from a local datadir and exposes them at\n`GET /api/v2/configs/eval-with-context/{base64url(ctx)}`. Point your\nbrowser SDK at the resulting URL (`http://localhost:6580` by default)\nand the same client code that talks to api-delivery in production will\nwork unmodified.\n\nTelemetry is intentionally not served — qfg serve has no Quonfig backend\nbehind it. Disable client-side telemetry with\n`collectEvaluationSummaries: false` (and `contextUploadMode: \"none\"`),\nor point the SDK's `telemetryUrl` at a real endpoint.\n\nThe server is bound to 127.0.0.1 by default; pass --allow-non-loopback\nto confirm a LAN-reachable bind.",
+      "examples": [
+        "<%= config.bin %> serve",
+        "<%= config.bin %> serve --datadir ./our-config --environment production",
+        "<%= config.bin %> serve --port 6581 --frontend-sdk-key PUBLIC_KEY"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "datadir": {
+          "description": "Datadir to serve (defaults to ./our-config, then ./.quonfig, then errors). Honors QUONFIG_DIR.",
+          "name": "datadir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "environment": {
+          "description": "Which environment slug to evaluate. Honors QUONFIG_ENVIRONMENT.",
+          "name": "environment",
+          "default": "development",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "port": {
+          "description": "TCP port to listen on. Errors on collision; pass --port <n> to retry.",
+          "name": "port",
+          "default": 6580,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "host": {
+          "description": "Bind address. Loopback by default; non-loopback requires --allow-non-loopback.",
+          "name": "host",
+          "default": "127.0.0.1",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "frontend-sdk-key": {
+          "description": "If set, every request must present Authorization: Basic 1:<key>. If unset, the server is open (matches the \"datadir is the source of truth\" mental model).",
+          "name": "frontend-sdk-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cors-origin": {
+          "description": "Allowed CORS origin (repeatable). Default is *; required when binding to a non-loopback host.",
+          "name": "cors-origin",
+          "default": [
+            "*"
+          ],
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "watch": {
+          "description": "Reload the envelope when the datadir changes. --no-watch disables.",
+          "name": "watch",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "allow-non-loopback": {
+          "description": "Confirm a LAN-reachable bind. Required when --host is not loopback.",
+          "name": "allow-non-loopback",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "serve",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "serve.js"
+      ]
+    },
     "set-default": {
       "aliases": [
         "toggle"
@@ -3623,5 +3738,5 @@
       ]
     }
   },
-  "version": "0.0.51"
+  "version": "0.0.53"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
   "name": "@quonfig/cli",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "bugs": {
     "url": "https://github.com/quonfig/cli/issues"
   },
@@ -21,7 +21,7 @@
     "@oclif/core": "^3.18.2",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-plugins": "^4",
-    "@quonfig/node": "^0.0.28",
+    "@quonfig/node": "^0.0.30",
     "acorn": "^8.10.0",
     "acorn-walk": "^8.3.5",
     "chalk": "^5.4.1",