@zq-silk/yui 2.7.1 → 2.8.0

package/dist/models/modelManagement.js

@@ -0,0 +1,469 @@
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { webLocalMutation, WebRequestRejected } from "../web/webMutation.js";
+import { modelFields, modelObject, modelUrl, validateModelConnection } from "./modelManagementConfig.js";
+import { modelDigest, modelJsonFile, modelKey, newModelFile, replaceModelFile } from "./modelManagementFiles.js";
+import { readModelJson } from "./modelManagementHttp.js";
+const NOTICE = "Configuration is owned by metabridge. Saved does not mean applied: reload through your existing deployment flow if needed, then refresh the catalog. No Session, account or model is switched; inference is not validated.";
+const empty = () => ({
+    status: "not-queried", attemptedAt: null, observedAt: null, stale: false, error: null, items: []
+});
+export function createModelManagement(store, options = {}) {
+    const request = options.request ?? readModelJson;
+    const now = options.now ?? (() => new Date());
+    let catalog = empty();
+    const quotas = { factory: empty(), "command-code": empty() };
+    let cacheRevision = "";
+    const pending = new Map();
+    function snapshot() {
+        const connection = store.getConfig().modelManagement ?? null;
+        let root;
+        let providers = [];
+        let configurationError = null;
+        try {
+            if (connection?.bridgeConfigFile) {
+                root = modelJsonFile(connection.bridgeConfigFile);
+                if (root.value.providerFiles !== undefined && root.value.backends !== undefined)
+                    throw new Error();
+                if (root.value.providerFiles !== undefined) {
+                    if (!Array.isArray(root.value.providerFiles) || !root.value.providerFiles.length || root.value.providerFiles.length > 100)
+                        throw new Error();
+                    const seen = new Set();
+                    let bytes = Buffer.byteLength(root.raw);
+                    providers = root.value.providerFiles.map((path) => {
+                        if (typeof path !== "string")
+                            throw new Error();
+                        const filename = path.startsWith("~/") ? resolve(homedir(), path.slice(2)) : resolve(dirname(root.path), path);
+                        if (seen.has(filename))
+                            throw new Error();
+                        seen.add(filename);
+                        const file = modelJsonFile(filename);
+                        bytes += Buffer.byteLength(file.raw);
+                        if (bytes > 2 * 1024 * 1024)
+                            throw new Error();
+                        return { file, value: file.value, id: modelDigest(filename) };
+                    });
+                    if (new Set(providers.map(p => p.value.name)).size !== providers.length)
+                        throw new Error();
+                }
+                else {
+                    const backends = root.value.backends ?? [];
+                    if (!Array.isArray(backends) || backends.length > 100)
+                        throw new Error();
+                    const names = new Set();
+                    providers = backends.map((value, index) => {
+                        const row = modelObject(value);
+                        const name = typeof row.name === "string" ? row.name : String(index);
+                        if (names.has(name))
+                            throw new Error();
+                        names.add(name);
+                        return { file: root, value: row, id: modelDigest([root.path, name]) };
+                    });
+                }
+            }
+        }
+        catch {
+            configurationError = "Bridge configuration is unavailable, ambiguous or unsupported. No configuration was changed.";
+            providers = [];
+        }
+        const revision = modelDigest([connection, root?.raw ?? null, providers.map(p => [p.id, p.file.raw]), configurationError]);
+        if (revision !== cacheRevision) {
+            catalog = empty();
+            quotas.factory = empty();
+            quotas["command-code"] = empty();
+            cacheRevision = revision;
+        }
+        return { connection, root, providers, configurationError, revision };
+    }
+    function read() {
+        const state = snapshot();
+        return {
+            revision: state.revision, connection: state.connection, providers: state.providers.map(providerView),
+            configurationError: state.configurationError, application: "unverified", notice: NOTICE
+        };
+    }
+    function checkRevision(body) {
+        const state = snapshot();
+        if (typeof body.revision !== "string" || body.revision !== state.revision) {
+            throw new WebRequestRejected("Model configuration changed; read it again before submitting.");
+        }
+        return state;
+    }
+    function saveConnection(input) {
+        const body = modelObject(input);
+        modelFields(body, ["revision", "connection"]);
+        const state = checkRevision(body);
+        const connection = body.connection === null ? null : validateModelConnection(body.connection);
+        if (connection && state.connection) {
+            for (const [address, credential] of [
+                ["bridgeUrl", "catalogKeyFile"], ["cpaUrl", "managementKeyFile"]
+            ]) {
+                const previous = state.connection;
+                const origin = (url) => url ? modelUrl(url).origin : "";
+                if (previous[credential] && previous[credential] === connection[credential]
+                    && origin(previous[address]) !== origin(connection[address])) {
+                    throw new WebRequestRejected(`Changing ${address} origin requires a new ${credential} reference, or clear the old reference and save before explicitly binding it again.`);
+                }
+            }
+        }
+        // No external I/O inside the store transaction.
+        webLocalMutation(store, tx => {
+            if (modelDigest(tx.getConfig().modelManagement ?? null) !== modelDigest(state.connection)) {
+                throw new WebRequestRejected("Connection changed; read it again.");
+            }
+            const config = { ...tx.getConfig() };
+            if (connection)
+                config.modelManagement = connection;
+            else
+                delete config.modelManagement;
+            tx.saveConfig(config);
+        });
+        return read();
+    }
+    function saveProvider(input) {
+        const body = modelObject(input);
+        modelFields(body, ["revision", "operation", "provider", "id"]);
+        const state = checkRevision(body);
+        if (!state.root || state.configurationError)
+            throw new WebRequestRejected("Select a readable local bridge configuration first.");
+        const removing = body.operation === "remove";
+        if (!removing && body.operation !== "save")
+            throw new WebRequestRejected("Unknown provider operation.");
+        const draft = removing ? null : modelObject(body.provider);
+        if (draft)
+            modelFields(draft, ["id", "name", "via", "baseUrl", "prefix", "enabled", "apiKey"]);
+        const id = removing ? body.id : draft.id;
+        const target = id === undefined ? undefined : state.providers.find(p => p.id === id);
+        if (id !== undefined && !target)
+            throw new WebRequestRejected("Provider identity changed; read it again.");
+        if (target && !providerView(target).editable)
+            throw new WebRequestRejected("This provider is read-only.");
+        if (removing && !target)
+            throw new WebRequestRejected("Select the exact provider to remove.");
+        if (!removing && !target && state.providers.length >= 100)
+            throw new WebRequestRejected("Provider limit reached.");
+        let value;
+        if (draft) {
+            if (typeof draft.name !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(draft.name)
+                || typeof draft.prefix !== "string" || !/^[a-zA-Z0-9_-]{1,64}\/$/.test(draft.prefix)
+                || !["direct", "cpa"].includes(String(draft.via)) || typeof draft.baseUrl !== "string"
+                || typeof draft.enabled !== "boolean"
+                || (draft.apiKey !== undefined && (typeof draft.apiKey !== "string" || draft.apiKey.length > 8192 || /[\0\r\n]/.test(draft.apiKey)))) {
+                throw new WebRequestRejected("Expected a name, unique namespace ending in /, direct/cpa route, URL, enabled flag and optional API key.");
+            }
+            modelUrl(draft.baseUrl);
+            if (state.providers.some(p => p !== target && (p.value.name === draft.name || p.value.prefix === draft.prefix))) {
+                throw new WebRequestRejected("Provider name or model namespace already exists.");
+            }
+            const key = typeof draft.apiKey === "string" ? draft.apiKey.trim() : "";
+            if (!target && !key)
+                throw new WebRequestRejected("A new API-key connection requires a key.");
+            const previousBase = target?.value.base_url ?? target?.value.base;
+            const sameDestination = target && safeUrl(draft.baseUrl) === safeUrl(previousBase);
+            if (target && !sameDestination && !key) {
+                throw new WebRequestRejected("Changing the credential destination requires a newly supplied key.");
+            }
+            value = { ...(target?.value ?? {
+                    wire_api: "responses", protocol: "responses", requestMode: "passthrough",
+                    compaction: { mode: "passthrough" }, catalog: { source: "remote" }, priority: 50
+                }), name: draft.name, via: draft.via, prefix: draft.prefix, enabled: draft.enabled };
+            // metabridge's base prepends /v1; base_url is already a complete API root.
+            // Keep the existing spelling even when the address is intentionally edited.
+            value[target?.value.base !== undefined ? "base" : "base_url"] = sameDestination ? previousBase : draft.baseUrl;
+            if (key) {
+                const auth = target?.value.auth;
+                value.auth = auth && ["static", "gateway"].includes(String(auth.type))
+                    ? { ...auth, key } : { type: "static", key };
+            }
+            const auth = value.auth;
+            if (draft.enabled && ["static", "gateway"].includes(String(auth.type))
+                && (typeof auth.key !== "string" || !auth.key.trim())) {
+                throw new WebRequestRejected("Enabling this provider requires an API key; supply one or keep the provider disabled.");
+            }
+        }
+        const backends = state.providers.filter(p => p !== target).map(p => p.value);
+        if (!removing)
+            backends.push(value);
+        if (!backends.some(p => p.enabled !== false)) {
+            throw new WebRequestRejected("Keep at least one enabled backend before saving.");
+        }
+        // Existing cross-provider web search references must still resolve. Do not
+        // rewrite references or silently select another provider on the user's behalf.
+        for (const provider of backends) {
+            const search = provider.webSearch;
+            if (!search || typeof search !== "object" || Array.isArray(search))
+                continue;
+            const destination = backends.find(p => p.name === search.backend);
+            if (!destination || (provider.enabled !== false && destination.enabled === false)) {
+                throw new WebRequestRejected("This change would break a webSearch backend reference; manage the reference with its owner first.");
+            }
+        }
+        // External files never participate in Yui's DB transaction. Synchronous CAS
+        // detects observed edits; metabridge has no cross-writer locking protocol.
+        checkRevision(body);
+        const root = state.root;
+        let retainedFile;
+        if (root.value.providerFiles !== undefined) {
+            if (target && !removing)
+                replaceModelFile(target.file, value);
+            else {
+                const files = [...root.value.providerFiles];
+                if (target)
+                    files.splice(state.providers.indexOf(target), 1);
+                else
+                    files.push(newModelFile(dirname(root.path), draft.name, value));
+                // A failed root replacement can leave a private unreferenced file;
+                // never delete a file whose adoption by another writer is unknown.
+                try {
+                    replaceModelFile(root, { ...root.value, providerFiles: files });
+                }
+                catch (error) {
+                    if (!target)
+                        throw new Error("Provider file created but bridge reference update was not confirmed; inspect retained private files before retrying.", { cause: error });
+                    throw error;
+                }
+            }
+        }
+        else {
+            const backends = state.providers.map(p => p.value);
+            if (target) {
+                if (removing) {
+                    // Inline auth may be the only copy. Preserve the complete provider in
+                    // an owned 0600 file before unlinking, just as providerFiles removal
+                    // leaves its existing file. Never delete this copy on uncertain save.
+                    retainedFile = newModelFile(dirname(root.path), "retained", target.value);
+                    backends.splice(state.providers.indexOf(target), 1);
+                }
+                else
+                    backends[state.providers.indexOf(target)] = value;
+            }
+            else
+                backends.push(value);
+            try {
+                replaceModelFile(root, { ...root.value, backends });
+            }
+            catch (error) {
+                if (retainedFile)
+                    throw new Error(`Provider copy retained in ${retainedFile}; removal was not confirmed. Read current facts before retrying.`, { cause: error });
+                throw error;
+            }
+        }
+        const view = read();
+        if (removing)
+            view.notice = `Provider unlinked. Referenced files and credentials were retained; no service was stopped.${retainedFile ? ` Inline provider retained beside the bridge configuration in ${retainedFile}.` : ""} ${NOTICE}`;
+        return view;
+    }
+    function current(value) {
+        return { ...value, stale: value.observedAt !== null && now().getTime() - Date.parse(value.observedAt) > 60_000 };
+    }
+    function readCatalog(cursor = "0") {
+        snapshot();
+        if (!/^\d{1,5}$/.test(cursor) || Number(cursor) > 2000)
+            throw new WebRequestRejected("Invalid catalog cursor.");
+        const offset = Number(cursor);
+        return { ...current(catalog), items: catalog.items.slice(offset, offset + 100), total: catalog.items.length,
+            nextCursor: offset + 100 < catalog.items.length ? String(offset + 100) : null };
+    }
+    function readQuota(source) {
+        snapshot();
+        if (source !== "factory" && source !== "command-code")
+            throw new WebRequestRejected("Unsupported quota source.");
+        return current(quotas[source]);
+    }
+    async function refresh(input) {
+        const body = modelObject(input);
+        modelFields(body, ["revision", "kind", "source"]);
+        const state = checkRevision(body);
+        if (!state.connection)
+            throw new WebRequestRejected("Configure a metabridge connection first.");
+        const kind = body.kind;
+        const source = body.source;
+        if (kind !== "catalog" && kind !== "quota" || kind === "catalog" && source !== undefined
+            || kind === "quota" && source !== "factory" && source !== "command-code") {
+            throw new WebRequestRejected("Unsupported observation.");
+        }
+        const identity = `${state.revision}/${kind}/${source ?? ""}`;
+        const active = pending.get(identity);
+        if (active)
+            return active;
+        if (pending.size >= 4)
+            throw new WebRequestRejected("Observation capacity reached; wait for the current request.");
+        const operation = (async () => {
+            const attemptedAt = now().toISOString();
+            let observation;
+            try {
+                const c = state.connection;
+                if (kind === "catalog") {
+                    const key = modelKey(c.catalogKeyFile);
+                    const raw = modelObject(await request(c.bridgeUrl, "/v1/models", key, 8_000));
+                    if (!Array.isArray(raw.data) || raw.data.length > 2000)
+                        throw new Error("invalid-or-oversize-catalog");
+                    const items = raw.data.map(item => {
+                        const row = modelObject(item);
+                        if (typeof row.id !== "string" || !row.id || row.id.length > 2048)
+                            throw new Error("invalid-catalog");
+                        return { id: row.id, source: row.id.includes("/") ? row.id.split("/")[0] : "metabridge" };
+                    });
+                    // metabridge serves HTTP 200 even when some/all upstream catalogs fail.
+                    // Its separate health read is bounded too; never expose raw upstream
+                    // diagnostics, which can contain credentials or private addresses.
+                    let healthError;
+                    try {
+                        healthError = catalogHealthError(await request(c.bridgeUrl, "/healthz", key, 8_000), items.length);
+                    }
+                    catch {
+                        healthError = "catalog-health-unavailable";
+                    }
+                    if (healthError && !items.length)
+                        throw new Error(healthError);
+                    observation = { status: healthError ? "partial" : "success", items, attemptedAt,
+                        observedAt: now().toISOString(), stale: false, error: healthError };
+                }
+                else {
+                    if (!c.cpaUrl || !c.managementKeyFile)
+                        throw new Error("quota-not-configured");
+                    const suffix = source === "factory" ? "accounts" : "command-code";
+                    const raw = await request(c.cpaUrl, `/v0/management/plugins/factory-quota/${suffix}`, modelKey(c.managementKeyFile), 30_000);
+                    const items = normalizeQuota(source, raw);
+                    observation = { status: items.some(item => item.status !== "success") ? "partial" : "success",
+                        items, attemptedAt, observedAt: now().toISOString(), stale: false, error: null };
+                }
+            }
+            catch (error) {
+                const code = error instanceof Error && /^[a-z-]{1,64}$/.test(error.message) ? error.message : "observation-unavailable";
+                observation = { status: "failed", items: [], attemptedAt, observedAt: null, stale: false, error: code };
+            }
+            if (snapshot().revision !== state.revision)
+                throw new WebRequestRejected("Connection changed during observation; result discarded.");
+            if (kind === "catalog") {
+                catalog = observation;
+                return readCatalog();
+            }
+            quotas[source] = observation;
+            return readQuota(source);
+        })();
+        pending.set(identity, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            pending.delete(identity);
+        }
+    }
+    return { read, saveConnection, saveProvider, readCatalog, readQuota, refresh };
+}
+function catalogHealthError(value, count) {
+    const health = modelObject(value);
+    const backends = Object.values(modelObject(health.backends));
+    const official = modelObject(health.officialModels);
+    if (health.service !== "metabridge" || health.ok !== true || !backends.length || backends.length > 100
+        || typeof official.ok !== "boolean" || typeof health.models !== "number") {
+        throw new Error("invalid-catalog-health");
+    }
+    const active = backends.map(modelObject).filter(row => row.error !== "disabled");
+    if (!active.length || active.some(row => typeof row.ok !== "boolean"))
+        throw new Error("invalid-catalog-health");
+    if (health.degraded || active.some(row => !row.ok || row.error) || official.error)
+        return "catalog-upstream-failed";
+    // The two routes have no shared snapshot token. A changed count cannot
+    // establish a complete observation, even if both HTTP reads succeeded.
+    return health.models === count ? null : "catalog-health-mismatch";
+}
+function providerView(provider) {
+    const p = provider.value;
+    const auth = p.auth && typeof p.auth === "object" ? p.auth : {};
+    const editable = (p.protocol ?? "responses") === "responses"
+        // Declaring via on an implicit chain changes metabridge's request and
+        // compaction defaults. This editor does not migrate those policies.
+        && (p.via === "direct" || p.via === "cpa")
+        && ["static", "keyfile", "gateway"].includes(String(auth.type))
+        && typeof p.prefix === "string" && /^[a-zA-Z0-9_-]{1,64}\/$/.test(p.prefix)
+        && p.routeModels === undefined && p.http_headers === undefined;
+    return {
+        id: provider.id, name: safeText(p.name, 128) ?? "unnamed",
+        via: p.via === "direct" || p.via === "cpa" ? p.via : "unknown",
+        baseUrl: safeUrl(p.base_url ?? p.base), prefix: safeText(p.prefix, 128) ?? "",
+        enabled: p.enabled !== false, editable, reason: editable ? null : "Official, implicit-policy, shared-route or unsupported provider; manage with its existing owner.",
+        credentialPresent: typeof auth.key === "string" && !!auth.key || typeof auth.file === "string" && !!auth.file,
+        credentialKind: p.protocol === "codex-subscription" ? "subscription" : "key",
+        owner: "metabridge"
+    };
+}
+function safeUrl(value) {
+    try {
+        return modelUrl(typeof value === "string" ? value : "").toString().replace(/\/+$/, "");
+    }
+    catch {
+        return "";
+    }
+}
+function safeText(value, limit = 128) {
+    return typeof value === "string" && value.length <= limit && !/[\0\r\n]/.test(value) ? value : null;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function time(value) {
+    return typeof value === "string" && value.length < 64 && Number.isFinite(Date.parse(value)) ? value : null;
+}
+function windowView(value, label) {
+    const row = modelObject(value);
+    const remaining = finite(row.remainingFraction);
+    return { label, remainingFraction: remaining !== null && remaining <= 1 ? remaining : null,
+        used: finite(row.used), cap: finite(row.cap), resetTime: time(row.resetTime) };
+}
+function normalizeQuota(source, value) {
+    const raw = modelObject(value);
+    if (source === "command-code") {
+        if (!Array.isArray(raw.windows) || raw.windows.length > 32)
+            throw new Error("invalid-quota-response");
+        const credits = raw.credits === undefined ? {} : modelObject(raw.credits);
+        const balanceDetails = [];
+        for (const [field, kind] of [
+            ["monthlyCredits", "monthly-credits"], ["purchasedCredits", "purchased-credits"], ["freeCredits", "free-credits"]
+        ]) {
+            const value = finite(credits[field]);
+            if (value !== null)
+                balanceDetails.push({ kind, value });
+        }
+        // The extension supplies a total only when all three pools are known.
+        // Keep partial pools visible without inventing that total.
+        const balance = balanceDetails.length === 3 ? finite(raw.balance) : null;
+        return [{ id: "command-code", source, status: balance === null ? "partial" : "success",
+                windows: raw.windows.map((w, i) => windowView(w, safeText(modelObject(w).window) ?? `window-${i + 1}`)),
+                balance, balanceDetails, periodEnd: time(raw.periodEnd), error: balance === null ? "quota-total-unknown" : null }];
+    }
+    if (!Array.isArray(raw.accounts) || raw.accounts.length > 16)
+        throw new Error("invalid-quota-response");
+    return raw.accounts.map((account, i) => {
+        const row = modelObject(account);
+        const result = { id: `factory-${modelDigest(typeof row.id === "string" ? row.id : i).slice(0, 12)}`,
+            source, status: "failed", windows: [], balance: null, balanceDetails: [], periodEnd: null, error: "account-query-failed" };
+        if (row.error || !row.quota)
+            return result;
+        const quota = modelObject(row.quota);
+        if (Array.isArray(quota.summary)) {
+            if (quota.summary.length > 32)
+                return result;
+            const extra = quota.summary.find(metric => metric && typeof metric === "object"
+                && metric.key === "extra_usage_balance" && metric.currency === "USD");
+            const value = finite(extra?.value);
+            if (value !== null)
+                result.balanceDetails.push({ kind: "extra-usage-usd", value });
+        }
+        if (!Array.isArray(quota.groups) || quota.groups.length > 16)
+            return result;
+        for (const group of quota.groups) {
+            const g = modelObject(group);
+            if (!Array.isArray(g.buckets) || g.buckets.length > 16)
+                return result;
+            for (const bucket of g.buckets) {
+                const b = modelObject(bucket);
+                result.windows.push(windowView(b, `${safeText(g.displayName) ?? "group"} / ${safeText(b.window) ?? "window"}`));
+            }
+        }
+        result.status = result.windows.length ? "success" : "partial";
+        result.error = result.windows.length ? null : "quota-fields-unknown";
+        return result;
+    });
+}

package/dist/models/modelManagementConfig.js

@@ -0,0 +1,46 @@
+import { isAbsolute } from "node:path";
+import { WebRequestRejected } from "../web/webMutation.js";
+export function modelObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new WebRequestRejected("Expected an object.");
+    return value;
+}
+export function modelFields(value, allowed) {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        throw new WebRequestRejected("Unknown Model management field.");
+}
+/** Configuration validation does not resolve DNS or contact a service. */
+export function modelUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new WebRequestRejected("Expected an HTTP(S) service URL.");
+    }
+    const loopback = ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash
+        || (!loopback && url.protocol !== "https:") || value.length > 2048) {
+        throw new WebRequestRejected("Use loopback HTTP or HTTPS without credentials, query or fragment.");
+    }
+    return url;
+}
+export function validateModelConnection(value) {
+    const row = modelObject(value);
+    const fields = ["bridgeUrl", "bridgeConfigFile", "cpaUrl", "managementKeyFile", "catalogKeyFile"];
+    modelFields(row, fields);
+    for (const field of fields) {
+        if (typeof row[field] !== "string" || row[field].length > 4096
+            || /[\0\r\n]/.test(row[field]))
+            throw new WebRequestRejected("Invalid Model connection field.");
+    }
+    const result = row;
+    modelUrl(result.bridgeUrl);
+    if (result.cpaUrl)
+        modelUrl(result.cpaUrl);
+    for (const field of ["bridgeConfigFile", "managementKeyFile", "catalogKeyFile"]) {
+        if (result[field] && !isAbsolute(result[field]))
+            throw new WebRequestRejected("Server file references must be absolute paths.");
+    }
+    return { ...result };
+}

package/dist/models/modelManagementFiles.js

@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { WebRequestRejected } from "../web/webMutation.js";
+import { modelObject } from "./modelManagementConfig.js";
+export function modelDigest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export function privateModelFile(path, secret = false) {
+    try {
+        if (!isAbsolute(path) || realpathSync(path) !== resolve(path))
+            throw new Error();
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = fstatSync(fd);
+            const limit = secret ? 16384 : 2 * 1024 * 1024;
+            if (!stat.isFile() || stat.size > limit
+                || (process.getuid && stat.uid !== process.getuid())
+                || (secret && (stat.mode & 0o077) !== 0))
+                throw new Error();
+            const buffer = Buffer.alloc(limit + 1);
+            let total = 0;
+            while (total < buffer.length) {
+                const count = readSync(fd, buffer, total, buffer.length - total, total);
+                if (!count)
+                    break;
+                total += count;
+            }
+            if (total > limit)
+                throw new Error();
+            return buffer.subarray(0, total).toString("utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        throw new WebRequestRejected(secret ? "Credential file unavailable; use an owned private regular file." : "Bridge configuration must be an owned, bounded, non-symlink JSON file.");
+    }
+}
+export function modelKey(path) {
+    if (!path)
+        return "";
+    const key = privateModelFile(path, true).trim();
+    if (!key || /[\0\r\n]/.test(key))
+        throw new WebRequestRejected("Credential file is empty or invalid.");
+    return key;
+}
+export function modelJsonFile(path) {
+    const raw = privateModelFile(path);
+    try {
+        return { path, raw, value: modelObject(JSON.parse(raw)) };
+    }
+    catch {
+        throw new WebRequestRejected("Bridge configuration is not a JSON object.");
+    }
+}
+/** Atomic replacement, with optimistic conflict detection against the read bytes. */
+export function replaceModelFile(file, value) {
+    modelDirectory(dirname(file.path));
+    if (privateModelFile(file.path) !== file.raw)
+        throw new WebRequestRejected("Bridge configuration changed; read it again.");
+    const temporary = join(dirname(file.path), `.yui-model-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        created = true;
+        if (privateModelFile(file.path) !== file.raw)
+            throw new WebRequestRejected("Bridge configuration changed; read it again.");
+        renameSync(temporary, file.path);
+        created = false;
+    }
+    finally {
+        if (created)
+            unlinkSync(temporary);
+    }
+}
+export function newModelFile(directory, name, value) {
+    modelDirectory(directory);
+    const filename = `yui-provider-${name}-${randomUUID()}.json`;
+    writeFileSync(join(directory, filename), `${JSON.stringify(value, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    return filename;
+}
+function modelDirectory(directory) {
+    const stat = lstatSync(directory);
+    if (realpathSync(directory) !== resolve(directory) || !stat.isDirectory()
+        || (stat.mode & 0o022) !== 0 || (process.getuid && stat.uid !== process.getuid())) {
+        throw new WebRequestRejected("Bridge configuration directory must be owned, non-symlink and not writable by other users.");
+    }
+}