dsh-connect-agnes-token-plan 0.5.0

package/lib/host-config-BNGgm_j7.js

@@ -0,0 +1,456 @@
+//#region src/host/util.ts
+/**
+* The error `pluginError` actually produces at runtime: an `Error` with a
+* stable `code` the panel branches on, plus optional structured fields the
+* panel and trace read. The fields are attached, not inherited, so this is a
+* structural annotation, not a subclass.
+* @typedef {Error & {
+*   code: import("./codes.ts").CodeValue,
+*   retryAfterMs?: number,
+*   detail?: string,
+*   trace?: object[]
+* }} PluginError
+*/
+/** Read a finite positive number, else the fallback. */
+function num(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/** Read a non-empty string, else the fallback. */
+function str(value, fallback) {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : fallback;
+}
+/**
+* Redact credential-shaped strings from any text that may reach a log, an
+* error message, or a panel-facing response.
+*
+* AGENTS.md's red line: "凭据不入库" — a credential never reaches a log or a
+* response. The login trace already sanitizes in `Agnes-auth.ts`; this is
+* the counterpart for the LLM route, where an HTTP error object's `message`
+* often embeds the request headers it was built from (axios/fetch errors do),
+* and a Agnes 4xx body may echo the `sk-` key back. Without this gate a
+* registration failure would leak the key through `providerState.error` and
+* `ctx.logger.warn`.
+* @param {string} text - any string that might carry a credential.
+* @returns {string} the text with credential patterns replaced by `[REDACTED]`.
+*/
+function redactSecrets(text) {
+	return (typeof text === "string" ? text : "").replace(/(["']?[Aa]uthorization["']?\s*[:=]\s*["']?)(?!Bearer\s)[^"',;\s]+/g, "$1[REDACTED]").replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [REDACTED]").replace(/\bsk-[A-Za-z0-9._-]{8,}/g, "sk-[REDACTED]").replace(/(["']?(?:password|access_token|refresh_token|api[_-]?key|token)["']?\s*:\s*["'])[^"']+(?=["'])/gi, "$1[REDACTED]").replace(/\b(password|access_token|refresh_token|api[_-]?key|token)\s*=\s*[^&;\s]+/gi, "$1=[REDACTED]");
+}
+/** Read a plain object, else `{}`. */
+function obj(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/**
+* Read a string exactly as it was given, else the fallback.
+*
+* The companion to `str()` for secrets: a password is stored, read back and
+* sent as typed, because trimming it is a change the user cannot see. A
+* password of only whitespace is still "not filled in", which the caller
+* judges with `.trim()`.
+*/
+function verbatim(value, fallback) {
+	return typeof value === "string" ? value : fallback;
+}
+/** Read a finite number, else `null`. */
+function numOrNull(value) {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+* An error carrying a stable code the panel can branch on.
+*
+* The single constructor for every failure this plugin produces. `extra`
+* carries optional structured fields (retryAfterMs, detail) that the panel
+* and the trace need; only defined extras are copied, so an absent field
+* stays absent rather than reading as a zero.
+*
+* The runtime value is a plain `Error` with these fields attached; the
+* {@link PluginError} type records that shape so a `catch (e)` downstream can
+* read `e.code` as more than a hopeful guess.
+* @param {import("./codes.ts").CodeValue} code - a {@link import("./codes.ts").CODE} wire value.
+* @param {string} message - human-readable description.
+* @param {{ retryAfterMs?: number, detail?: string }} [extra] - optional structured fields.
+* @returns {PluginError}
+*/
+function pluginError(code, message, extra = {}) {
+	const error = new Error(message);
+	error.code = code;
+	if (extra.retryAfterMs !== void 0) error.retryAfterMs = extra.retryAfterMs;
+	if (extra.detail !== void 0) error.detail = extra.detail;
+	return error;
+}
+
+//#endregion
+//#region src/host/host-config.ts
+/**
+* The plugin's configuration contract and the Host trust fence.
+*
+* Everything the Host half reads from the row's patch config lives here, plus
+* the `isAdmitted` check that keeps a foreign page from planting an account.
+* `test/config.test.mjs` pins `CONFIG_DEFAULTS` and the resolvers against this
+* file and `cordis.patch.yml`, so the code and the documented contract cannot
+* silently drift.
+* @module dsh-connect-agnes-token-plan/host-config
+*/
+/**
+* The one slug every addressable surface of this plugin derives from.
+*
+* Besides the name the Loader reports for the row, it is also the `/api` route
+* prefix (`index.ts`), the credential record's scope (`token-store.ts`) and the
+* state directory (`throttle-store.ts`) — so a rename has to carry the user's
+* stored grant and parked throttle with it, not just the text. The two files
+* that cannot import from here repeat it literally: `package.json#name` and the
+* `id`/`name` pair in `cordis.patch.yml`. Neither is pinned against this
+* constant by `test/config.test.mjs` (it pins `CONFIG_DEFAULTS` only), so a
+* rename must check all three by hand.
+*/
+const name = "dsh-connect-agnes-token-plan";
+/** Cordis services this plugin needs; without `webServer` it stays inactive. */
+const inject = ["webServer"];
+/**
+* The plugin's configuration contract in one place.
+*
+* Every default the Host half reads lives here, so the code and the
+* `cordis.patch.yml` that documents it cannot silently drift: `test/config.test.mjs`
+* pins both against this object. The `auth` sub-object lists the operator-facing
+* login-flow overrides (their patch.yml entries are commented by default, which is
+* why they default to empty/zero and mean "use the platform default").
+*/
+const CONFIG_DEFAULTS = Object.freeze({
+	consoleBase: "https://platform-backend.agnes-ai.cn",
+	apiBase: "https://api.agnes-ai.cn/v1",
+	/**
+	* How many days of usage the panel's chart covers, inclusive of today.
+	*
+	* Days, not hours: `/api/usage/series` takes `start_date` / `end_date` as
+	* DATES, so an hour-granular window cannot be asked for. Snapping to whole
+	* days also keeps the request URL stable for the day, which is what lets the
+	* series cache actually hit.
+	*/
+	usageDays: 30,
+	/**
+	* Pseudo multipliers for the model roster, keyed by a case-insensitive
+	* SUBSTRING of a model id (first matching key wins, in insertion order).
+	*
+	* Empty by default, and that is not an oversight: the factor used to scale a
+	* per-model credit figure, and Agnes publishes no per-model usage at all
+	* (its console never reads a `model` field). What is left is the operator's
+	* own annotation — a `×N` badge on a roster row — so there is no defensible
+	* default to ship. Set it to tag models for your own routing notes; rows
+	* without a match get no badge, never a guessed 1.
+	*/
+	trendMultipliers: {},
+	cacheSeconds: 60,
+	pollSeconds: 30,
+	consoleTimeoutMs: 15e3,
+	tokenSkewSeconds: 120,
+	/**
+	* Login-flow overrides, in the shape `agnes-auth.ts` reads them.
+	*
+	* Agnes signs in with ONE request (`POST /api/user/login`), so the SenseNova
+	* OIDC knobs — `iamBase`, `tokenEndpoint`, `jwksEndpoint`, `redirectUri`,
+	* `clientId`, `scope`, `encKeyId`, `maxHops` — have no counterpart here and
+	* are gone. The three below are the ones that still mean something.
+	*/
+	auth: {
+		loginPath: "",
+		loginTimeoutMs: 0,
+		fallbackExpiresInSeconds: 0
+	},
+	/** Host names the Host answers as, by default. The operator's list is added. */
+	admittedHosts: [
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"::1"
+	],
+	/**
+	* Vision step two: whether the Host syncs the identified vision-capable
+	* model ids into THIS row's own settings namespace (`imageModelIds`,
+	* `visionModels`) on every catalog poll, for a later LLM connect plugin to
+	* read. Off by default - the read-only info layer is the safe shape. The
+	* writes go to this plugin's OWN settings row only, never another
+	* provider's, so a miscalculated list cannot reach DSH's model routing.
+	*/
+	writeImageModelIds: false,
+	/** The last published image-model id list (the reader's primary field). */
+	imageModelIds: [],
+	/** The last full vision identification (id + source marker per model). */
+	visionModels: [],
+	/**
+	* Step three ("one-stop service"): register the LLM provider DIRECTLY.
+	*
+	* When true, the plugin calls `ctx.llm.registerAdapter` itself with an
+	* OpenAI-compatible pi-ai adapter aimed at `apiBase`, the catalog poll feeds
+	* its model list, vision models carry image input automatically, and the
+	* panel-saved `AGNES_TOKEN_PLAN_API_KEY` reference authenticates requests. Off by
+	* default for the same reason `writeImageModelIds` is: registering a model
+	* source is a Host-wide change, not a read-only panel view, so it stays an
+	* explicit opt-in and an operator with the hand-written `llm-pi-ai` row is
+	* not suddenly offered two providers.
+	*/
+	registerProvider: false,
+	/**
+	* Draw absorption (ARCHITECTURE §5.4 route B): register the
+	* `agnes_draw_image` agent tool. When true AND the Host exposes a tools
+	* service, image-generation requests go to `{apiBase}/images/generations`
+	* with the panel-saved `AGNES_TOKEN_PLAN_API_KEY`, and the model list comes
+	* from `modality.ts` — the declared `output_modalities` field when the
+	* gateway sends one, the platform's own `agnes-image-*` family segment when
+	* it does not (the Agnes gateway sends no modality metadata at all; see that
+	* module's header). Off by
+	* default like every execution module: a tool the agent can call is a
+	* Host-wide change, and a Host without the tools service must simply never
+	* see it rather than fail.
+	*
+	* 0.4.2: this value is now the DEPLOYMENT DEFAULT only. The panel's draw
+	* tool switch (`POST /api/<name>/draw`, stored in `draw-store.ts`)
+	* overrides it live with no restart. See `docs/PROVIDER-HOT-RELOAD.md` §7.
+	*/
+	drawEnabled: false,
+	/** Preferred draw model id; empty means "first image-gen model of the catalog". */
+	drawModelId: "",
+	/** Deadline for one image request. Image models are slow; chat deadlines do not apply. */
+	drawTimeoutMs: 12e4,
+	/**
+	* Video absorption: register the `agnes_video_generate` agent tool
+	* (`video.ts`). A SEPARATE opt-in from `drawEnabled` on purpose — wanting
+	* image generation without video (or the reverse) is an ordinary
+	* preference, and one switch would force both on together.
+	*
+	* The protocol differs from drawing in the way that matters here: video is
+	* an ASYNCHRONOUS TASK (create, then poll until terminal), so this is the
+	* only module whose deadline is measured in MINUTES. Off by default, and
+	* degraded exactly like the draw tool: no tools service or a failing peer
+	* leaves the panel and the provider untouched.
+	*
+	* The panel's video switch (`POST /api/<name>/video`, stored in
+	* `video-store.ts`) overrides this live with no restart.
+	*/
+	videoEnabled: false,
+	/** Preferred video model id; empty means "first V2.0-family video model of the catalog". */
+	videoModelId: "",
+	/** The whole-generation poll budget (create + poll). Video tasks run for minutes. */
+	videoTimeoutMs: 6e5,
+	/** Default video width in pixels (16:9). */
+	videoWidth: 1152,
+	/** Default video height in pixels (16:9). */
+	videoHeight: 768,
+	/** Default frame count — must satisfy 8n+1 and be ≤441; 121 @ 24fps ≈ 5 seconds. */
+	videoNumFrames: 121,
+	/** Default frame rate (1–60). */
+	videoFrameRate: 24
+});
+/**
+* Sanitize the operator's pseudo-multiplier map: keep only string keys and
+* finite positive numbers, preserving insertion order (matching is
+* first-key-wins). A non-object or empty input falls back to the shipped
+* defaults; the operator sets `{}` explicitly to disable all multipliers.
+* Exported so `test/config.test.mjs` drives the same sanitizer the resolve
+* path uses, instead of a copy that could drift.
+* @param {unknown} raw - the raw `trendMultipliers` config value.
+* @returns {Record<string, number>} the sanitized map.
+*/
+function resolveTrendMultipliers(raw) {
+	const source = raw === void 0 || raw === null ? CONFIG_DEFAULTS.trendMultipliers : raw;
+	if (source === null || typeof source !== "object" || Array.isArray(source)) return { ...CONFIG_DEFAULTS.trendMultipliers };
+	const out = {};
+	for (const [key, value] of Object.entries(source)) if (typeof key === "string" && key !== "" && typeof value === "number" && Number.isFinite(value) && value > 0) out[key] = value;
+	return out;
+}
+/**
+* Clamp a raw numeric setting to its effective integer.
+*
+* Every numeric field in {@link resolveSettings} follows the same shape: floor
+* the raw value, clamp it at a lower bound, then (optionally) at an upper bound;
+* a non-positive or non-finite raw falls back to `def` (because `num` only
+* accepts a positive finite number). The sequence — `Math.min(max, Math.max(min,
+* Math.floor(raw)))` with `max` defaulting to `Infinity` — is exactly what the
+* inline `Math.max`/`Math.min` chains used to spell out one field at a time, so
+* this is a MOVE of that pattern into one tested place, not a behaviour change.
+* @param {unknown} raw - the raw value read from the row.
+* @param {number} def - the fallback when `raw` is not a positive finite number.
+* @param {number} min - the lower clamp (inclusive) applied after flooring.
+* @param {number} [max] - the upper clamp (inclusive); omit for no upper bound.
+* @returns {number} the clamped integer.
+*/
+function clampInt(raw, def, min, max = Infinity) {
+	return Math.min(max, Math.max(min, Math.floor(num(raw, def))));
+}
+/**
+* Resolve the row's raw patch config into effective settings.
+*
+* A malformed row must not throw out of here: `apply` runs at mount, and an
+* exception would take the whole plugin down instead of leaving a panel that
+* explains itself. So problems are returned as `configError` and surfaced
+* through the snapshot route.
+* @param {object} config - the row's raw patch config.
+* @returns {{settings: object, configError: string|null}}
+*/
+function resolveSettings(config) {
+	const source = obj(config);
+	const consoleBase = str(source.consoleBase, CONFIG_DEFAULTS.consoleBase).replace(/\/+$/, "");
+	const apiBase = str(source.apiBase, CONFIG_DEFAULTS.apiBase).replace(/\/+$/, "");
+	try {
+		return {
+			settings: {
+				consoleBase,
+				apiBase,
+				usageDays: clampInt(source.usageDays, CONFIG_DEFAULTS.usageDays, 1, 365),
+				trendMultipliers: resolveTrendMultipliers(source.trendMultipliers),
+				cacheSeconds: clampInt(source.cacheSeconds, CONFIG_DEFAULTS.cacheSeconds, 5),
+				pollSeconds: clampInt(source.pollSeconds, CONFIG_DEFAULTS.pollSeconds, 5),
+				consoleTimeoutMs: clampInt(source.consoleTimeoutMs, CONFIG_DEFAULTS.consoleTimeoutMs, 1e3),
+				allowedHosts: resolveAllowedHosts(source),
+				tokenSkewSeconds: clampInt(source.tokenSkewSeconds, CONFIG_DEFAULTS.tokenSkewSeconds, 0),
+				auth: resolveAuthOverrides(source, consoleBase),
+				writeImageModelIds: source.writeImageModelIds === true,
+				imageModelIds: Array.isArray(source.imageModelIds) ? source.imageModelIds.filter((id) => typeof id === "string") : CONFIG_DEFAULTS.imageModelIds,
+				visionModels: Array.isArray(source.visionModels) ? source.visionModels.filter((entry) => entry && typeof entry === "object" && !Array.isArray(entry)) : CONFIG_DEFAULTS.visionModels,
+				registerProvider: source.registerProvider === true,
+				drawEnabled: source.drawEnabled === true,
+				drawModelId: str(source.drawModelId, ""),
+				drawTimeoutMs: clampInt(source.drawTimeoutMs, CONFIG_DEFAULTS.drawTimeoutMs, 5e3),
+				videoEnabled: source.videoEnabled === true,
+				videoModelId: str(source.videoModelId, ""),
+				videoTimeoutMs: clampInt(source.videoTimeoutMs, CONFIG_DEFAULTS.videoTimeoutMs, 3e4),
+				videoWidth: clampInt(source.videoWidth, CONFIG_DEFAULTS.videoWidth, 1),
+				videoHeight: clampInt(source.videoHeight, CONFIG_DEFAULTS.videoHeight, 1),
+				videoNumFrames: clampInt(source.videoNumFrames, CONFIG_DEFAULTS.videoNumFrames, 1),
+				videoFrameRate: clampInt(source.videoFrameRate, CONFIG_DEFAULTS.videoFrameRate, 1)
+			},
+			configError: null
+		};
+	} catch (error) {
+		return {
+			settings: {
+				consoleBase,
+				apiBase,
+				usageDays: CONFIG_DEFAULTS.usageDays,
+				trendMultipliers: CONFIG_DEFAULTS.trendMultipliers,
+				cacheSeconds: CONFIG_DEFAULTS.cacheSeconds,
+				pollSeconds: CONFIG_DEFAULTS.pollSeconds,
+				consoleTimeoutMs: CONFIG_DEFAULTS.consoleTimeoutMs,
+				allowedHosts: new Set(CONFIG_DEFAULTS.admittedHosts),
+				tokenSkewSeconds: CONFIG_DEFAULTS.tokenSkewSeconds,
+				auth: { consoleOrigin: consoleBase }
+			},
+			configError: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* Collect just the auth keys the operator actually set.
+*
+* The keys are read from the TOP LEVEL of the row. That is not obvious, and
+* getting it wrong is not a harmless typo: a nested `auth:` block is accepted
+* by the loader, silently dropped here, and the panel then runs on its shipped
+* defaults — which point at the REAL platform. An end-to-end run meant to talk
+* to a local stub then posts a real login attempt, which is exactly how this
+* plugin locked an account once already. So a nested `auth` key is reported as
+* a configuration error rather than ignored.
+*
+* The emitted set is exactly what `agnes-auth.ts:resolveAuthConfig` reads. The
+* SenseNova OIDC knobs (`iamBase` / `tokenEndpoint` / `jwksEndpoint` /
+* `redirectUri` / `clientId` / `scope` / `encKeyId` / `maxHops`) are gone with
+* the OIDC walk they configured — passing them through now would hand
+* `createAuth` keys it never reads, which is the silent-drop failure this
+* function exists to prevent.
+* @param {object} source - the row's raw patch config.
+* @param {string} consoleBase - the resolved console origin.
+* @returns {object} the override object for `createAuth`.
+* @throws {Error} when the row looks like it nests overrides it does not read.
+*/
+function resolveAuthOverrides(source, consoleBase) {
+	if (source.auth !== void 0 && source.auth !== null) {
+		const keys = Object.keys(obj(source.auth));
+		throw new Error(`auth overrides are top-level keys on this row, not a nested \`auth:\` block${keys.length === 0 ? "" : ` (found: ${keys.join(", ")})`}. Use \`loginPath\`, \`loginTimeoutMs\` or \`fallbackExpiresInSeconds\` at the top level; a nested block is ignored and the panel would keep using the real platform.`);
+	}
+	const overrides = { consoleOrigin: consoleBase };
+	const loginPath = str(source.loginPath, "");
+	if (loginPath !== "") overrides.loginPath = loginPath;
+	const fallbackExpiresInSeconds = Math.floor(num(source.fallbackExpiresInSeconds, 0));
+	if (fallbackExpiresInSeconds > 0) overrides.fallbackExpiresInSeconds = fallbackExpiresInSeconds;
+	const loginTimeoutMs = Math.floor(num(source.loginTimeoutMs, num(source.requestTimeoutMs, 0)));
+	if (loginTimeoutMs > 0) overrides.requestTimeoutMs = loginTimeoutMs;
+	return overrides;
+}
+/**
+* Collect the host names this Host will answer as.
+*
+* The operator's list is ADDED to the defaults, never substituted: replacing
+* them would let a typo lock the panel out of itself, and there is no console
+* to fix it from.
+* @param {object} source - the row's raw patch config.
+* @returns {Set<string>} the admitted host names, lowercased.
+*/
+function resolveAllowedHosts(source) {
+	const admitted = new Set(CONFIG_DEFAULTS.admittedHosts);
+	const extra = Array.isArray(source.allowedHosts) ? source.allowedHosts : [];
+	for (const entry of extra) {
+		const name = str(entry, "").trim().toLowerCase();
+		if (name !== "") admitted.add(name);
+	}
+	return admitted;
+}
+/**
+* The host name a `Host` header names, without its port.
+* @param {string} host - the raw header value.
+* @returns {string} the name; bracketed for IPv6 literals.
+*/
+function hostName(host) {
+	if (host.startsWith("[") && host.includes("]")) return host.slice(0, host.indexOf("]") + 1);
+	const colons = host.split(":");
+	if (colons.length > 2) {
+		if (/^\d+$/.test(colons[colons.length - 2]) && /^\d+$/.test(colons[colons.length - 1])) return host.slice(0, host.lastIndexOf(":"));
+		return host;
+	}
+	return colons.length > 1 ? host.slice(0, host.lastIndexOf(":")) : host;
+}
+/**
+* Trust fence for a route the browser can reach.
+*
+* Two different attacks have to be turned away here, and they need two
+* different facts:
+*
+* 1. DNS rebinding. The attacker's page rebinds its own name to 127.0.0.1 and
+*    POSTs an account. `Origin` and `Host` now AGREE on the attacker's name
+*    while the request lands on the Host, so comparing them to each other
+*    admits it. The `Host` header is the one thing a browser cannot forge, so
+*    it is checked against a whitelist instead of against the `Origin`.
+* 2. Cross-site forgery. A page on another origin asks the browser to post to
+*    the loopback Host. Here the whitelist alone is worthless — the Host IS
+*    legitimate — and the `Origin` is what gives it away.
+*
+* So: the `Host` must be one this Host answers as, AND any stated `Origin`
+* must agree with it. A request that states no `Origin` is the ordinary
+* same-origin GET and is admitted.
+*
+* The boundary this draws is the BROWSER, not the machine. A process running
+* as the user sets `Host` and `Origin` to whatever it likes, and there is no
+* CSRF token here to tell it apart from the panel — so anything that can open
+* a socket to this port can also plant an account. That is the same trust the
+* Host places in the user's own processes generally, but it is worth saying
+* plainly: an `Origin` check reads like more protection than it is, and a
+* reader who believes otherwise will build something on top of it. Closing
+* that gap needs a token the Host serves in its own page and the POST carries
+* back, not a header a client can choose.
+* @param request - the incoming HTTP request.
+* @param {Set<string>} allowedHosts - the host names this Host answers as.
+* @returns {boolean} whether the request may be served.
+*/
+function isAdmitted(request, allowedHosts) {
+	const host = str(request.headers?.host, "").toLowerCase();
+	if (host === "" || !allowedHosts.has(hostName(host))) return false;
+	const origin = request.headers.origin;
+	if (typeof origin !== "string" || origin === "") return true;
+	if (origin === "null") return false;
+	try {
+		return new URL(origin).host === host;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { name as a, num as c, pluginError as d, redactSecrets as f, isAdmitted as i, numOrNull as l, verbatim as m, hostName as n, resolveAuthOverrides as o, str as p, inject as r, resolveSettings as s, CONFIG_DEFAULTS as t, obj as u };