@skaile/forge-settings 0.0.0-stage → 1.0.0

package/dist/runtime/server/credential-policy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Credential policy — which references a host lets the credential layer touch.
+ *
+ * A reference names where a secret lives (`env:NAME`, `keyring:s/a`, `cmd:…`,
+ * `platform:…`). A host that stores provider entries an administrator typed,
+ * and runs next to its own secrets (a Directus token, an encryption key), must
+ * decide up front which references may be resolved at all. The decision is
+ * made *before* a reference is read: a refused reference is never resolved,
+ * never looked up in an environment and never passed on to a child process.
+ *
+ * The policy covers every place an entry names an environment variable:
+ *
+ * - `credential.ref` — by form, and for `env:` by variable name;
+ * - `${NAME}` interpolation tokens in `base_url`, `headers` and `query_params`,
+ *   which a spawned runtime expands from its environment. Only bare variable
+ *   names the `envNames` allow-list accepts pass; any other token is refused.
+ *
+ * No policy means no restriction: existing hosts keep their current reference
+ * handling. A policy is opt-in per host and states the host's rule explicitly.
+ */
+import type { AIProviderEntry, AIProviderRegistryView } from "../shared/provider-registry.js";
+/** The four credential reference forms. */
+export type CredentialRefForm = "env" | "cmd" | "platform" | "keyring";
+/** A host's rule for which credential references may be resolved. */
+export interface CredentialPolicy {
+    /** Reference forms that may be resolved. Absent: every form. */
+    forms?: readonly CredentialRefForm[];
+    /**
+     * Environment variable names a reference or interpolation token may name:
+     * exact strings, or expressions that must match the whole name. Absent:
+     * any name.
+     */
+    envNames?: ReadonlyArray<string | RegExp>;
+}
+/** An entry the policy refused, and why. The reason is secret-free. */
+export interface PolicyRefusal {
+    providerId: string;
+    error: string;
+}
+/** Whether `name` passes the policy's `envNames` allow-list. */
+export declare function isEnvNameAllowed(name: string, policy: CredentialPolicy): boolean;
+/**
+ * The reason a credential reference is refused, or `undefined` when the policy
+ * lets it through. A string that is not a reference is not this function's
+ * concern: it resolves to nothing anyway.
+ */
+export declare function credentialRefRefusal(ref: string, policy: CredentialPolicy): string | undefined;
+/**
+ * The reason an entry is refused, or `undefined`: its credential reference and
+ * every environment name it interpolates are checked, nothing is resolved.
+ */
+export declare function entryPolicyRefusal(entry: AIProviderEntry, policy: CredentialPolicy): string | undefined;
+/**
+ * The registry without the entries the policy refuses, as a plain entry map in
+ * registry order, plus what was refused. Nothing is resolved.
+ */
+export declare function applyCredentialPolicy(registry: AIProviderRegistryView, policy: CredentialPolicy): {
+    registry: Record<string, AIProviderEntry>;
+    refused: PolicyRefusal[];
+};

package/dist/runtime/server/credential-policy.js

@@ -0,0 +1,64 @@
+import { parseCredentialRef, registryEntries } from "../shared/provider-registry.js";
+const BARE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
+export function isEnvNameAllowed(name, policy) {
+  if (!policy.envNames) return true;
+  return policy.envNames.some((rule) => {
+    if (typeof rule === "string") return rule === name;
+    const match = new RegExp(rule.source, rule.flags.replace(/[gy]/g, "")).exec(name);
+    return match !== null && match.index === 0 && match[0] === name;
+  });
+}
+export function credentialRefRefusal(ref, policy) {
+  const parsed = parseCredentialRef(ref);
+  if (!parsed) return void 0;
+  if (policy.forms && !policy.forms.includes(parsed.form)) {
+    return `credential references of the form '${parsed.form}:' are not allowed here`;
+  }
+  if (parsed.form === "env" && !isEnvNameAllowed(parsed.name, policy)) {
+    return `environment variable ${parsed.name} is not allowed here`;
+  }
+  return void 0;
+}
+function interpolationRefusal(field, value, policy) {
+  for (const match of value.matchAll(INTERPOLATION_TOKEN)) {
+    const name = match[1].trim();
+    if (!BARE_ENV_NAME.test(name) || !isEnvNameAllowed(name, policy)) {
+      return `${field} interpolates '\${${name}}', which is not allowed here`;
+    }
+  }
+  return void 0;
+}
+export function entryPolicyRefusal(entry, policy) {
+  const ref = entry.credential?.ref;
+  if (ref !== void 0) {
+    const refusal = credentialRefRefusal(ref, policy);
+    if (refusal) return refusal;
+  }
+  const fields = [
+    ["base_url", entry.base_url],
+    ...Object.entries(entry.headers ?? {}).map(([name, value]) => [
+      `headers.${name}`,
+      value
+    ]),
+    ...Object.entries(entry.query_params ?? {}).map(
+      ([name, value]) => [`query_params.${name}`, value]
+    )
+  ];
+  for (const [field, value] of fields) {
+    if (typeof value !== "string") continue;
+    const refusal = interpolationRefusal(field, value, policy);
+    if (refusal) return refusal;
+  }
+  return void 0;
+}
+export function applyCredentialPolicy(registry, policy) {
+  const allowed = {};
+  const refused = [];
+  for (const [providerId, entry] of registryEntries(registry)) {
+    const error = entryPolicyRefusal(entry, policy);
+    if (error) refused.push({ providerId, error });
+    else allowed[providerId] = entry;
+  }
+  return { registry: allowed, refused };
+}

package/dist/runtime/server/credential-store.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The forge credential store — secrets at rest, keyed by credential-reference
+ * identity, plus resolution of the reference forms forge itself can serve.
+ *
+ * A registry entry never holds a secret: it holds a `credential.ref`
+ * (`env:NAME`, `cmd:<shell>`, `platform:<configId>`, `keyring:<service>/<account>`).
+ * This module is the backend for the two forms a forge server owns:
+ *
+ *   - `env:NAME`     — read from the process environment.
+ *   - `keyring:s/a`  — read from this store: an AES-256-GCM encrypted JSON file
+ *                      whose keys are the reference strings themselves. A forge
+ *                      app runs headless on a server with no OS keychain, so the
+ *                      encrypted file *is* the keyring the grammar names.
+ *
+ * `cmd:` is resolved by the runtime that owns the shell (the spawned
+ * `skaile serve` reads its own `providers.yml`), and `platform:` by the control
+ * plane that injects the session secret; both are reported, never guessed.
+ *
+ * Encryption is bound to reference identity: the reference string is the GCM
+ * additional-authenticated-data, so a blob stored for one reference cannot be
+ * replayed under another — moving `keyring:forge/anthropic` onto
+ * `keyring:forge/openai` fails authentication instead of silently handing the
+ * wrong endpoint a working key.
+ *
+ * Blob format: `enc:<base64(iv[16] + tag[16] + ciphertext)>`.
+ *
+ * Key format: `FORGE_CREDENTIAL_KEY` must be a 64-char hex string (32 bytes).
+ */
+import type { AIProviderEntry, AIProviderRegistryView } from "../shared/provider-registry.js";
+import { type CredentialPolicy } from "./credential-policy.js";
+export declare const CREDENTIAL_PREFIX: "enc:";
+/**
+ * The credential key is missing or unusable. Only operations that need the
+ * encrypted store raise it; `env:` and `cmd:` references never touch the key.
+ * `statusCode` is 503 so a host can map it straight to an HTTP answer.
+ */
+export declare class CredentialKeyError extends Error {
+    readonly code: "missing" | "invalid";
+    readonly statusCode: 503;
+    constructor(code: "missing" | "invalid", message: string);
+}
+/**
+ * A stored blob did not authenticate: the key is wrong, the data was altered,
+ * or the blob was encrypted for a different reference (the reference is the
+ * GCM additional data). The message names no secret and no plaintext.
+ */
+export declare class CredentialDecryptError extends Error {
+    constructor();
+}
+/**
+ * Encrypt a credential for storage under one reference.
+ *
+ * @param plaintext - The secret. Must not be empty.
+ * @param hexKey    - 64-char hex key (32 bytes) from `FORGE_CREDENTIAL_KEY`.
+ * @param ref       - The credential reference this blob belongs to; bound into
+ *                    the ciphertext as GCM additional data.
+ * @returns         `enc:<base64(iv + tag + ciphertext)>`
+ */
+export declare function encryptCredential(plaintext: string, hexKey: string, ref: string): string;
+/**
+ * Decrypt a credential stored under `ref`.
+ *
+ * @param ciphertext - `enc:<base64(iv + tag + ciphertext)>` string.
+ * @param hexKey     - 64-char hex key (32 bytes) from `FORGE_CREDENTIAL_KEY`.
+ * @param ref        - The reference the blob was encrypted for.
+ * @returns          The original plaintext.
+ * @throws           If the blob is tampered with, the key is wrong, the value is
+ *                   not encrypted, or the blob belongs to a different reference.
+ */
+export declare function decryptCredential(ciphertext: string, hexKey: string, ref: string): string;
+/** Where and with what a credential-store call reads or writes. */
+export interface CredentialStoreOptions {
+    /** 64-char hex key; defaults to `FORGE_CREDENTIAL_KEY` of the environment. */
+    key?: string;
+    /** Store file; defaults to `FORGE_CREDENTIAL_STORE` or `<skaile home>/forge-credentials.json`. */
+    path?: string;
+    /**
+     * Environment `env:` references (and the key and store path variables) read
+     * from. Without a {@link policy} it defaults to `process.env`; with one it
+     * defaults to an empty environment, so a policy-bound host never reads the
+     * ambient process by accident.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * Which references may be resolved. A refused reference is reported as an
+     * error and never read. Absent: no restriction.
+     */
+    policy?: CredentialPolicy;
+}
+/**
+ * Path of the local keyring file.
+ *
+ * Lives beside the user's `settings.json` so it follows `$SKAILE_HOME`, and is
+ * overridable per app with `FORGE_CREDENTIAL_STORE`.
+ */
+export declare function credentialStorePath(options?: CredentialStoreOptions): string;
+/**
+ * Store `value` under `ref` in the local keyring, encrypted against `ref`.
+ *
+ * @param ref   - A `keyring:<service>/<account>` reference.
+ * @param value - The secret.
+ * @returns     The store path that was written.
+ */
+export declare function storeCredential(ref: string, value: string, options?: CredentialStoreOptions): string;
+/** Read and decrypt the credential stored under `ref`, if any. */
+export declare function readStoredCredential(ref: string, options?: CredentialStoreOptions): string | undefined;
+/** Remove the credential stored under `ref`. Returns whether anything was removed. */
+export declare function deleteStoredCredential(ref: string, options?: CredentialStoreOptions): boolean;
+/** Every reference the local keyring holds a credential for. */
+export declare function listStoredCredentialRefs(options?: CredentialStoreOptions): string[];
+/** Where a resolved credential came from, or why it is missing. */
+export type CredentialSource = "env" | "keyring" | "cmd" | "platform" | "ambient" | "none";
+/** Outcome of a resolution attempt. Never carries the secret in `error`. */
+export interface ResolvedCredential {
+    /** The secret, when this layer could produce one. */
+    value?: string;
+    /** Which reference form answered — `ambient` means the cloud SDK chain signs. */
+    source: CredentialSource;
+    /** Why there is no value. Secret-free, safe to log and to show in the UI. */
+    error?: string;
+}
+/**
+ * Resolve one `credential.ref` to a value.
+ *
+ * `env:` and `keyring:` resolve here. `cmd:` and `platform:` are named as
+ * belonging to another layer rather than being silently treated as missing:
+ * the spawned runtime runs the command against its own `providers.yml`, and the
+ * control plane injects platform secrets into the session.
+ */
+export declare function resolveCredentialRef(ref: string, options?: CredentialStoreOptions): ResolvedCredential;
+/**
+ * Resolve a registry entry's credential.
+ *
+ * `kind: none` needs nothing; `sigv4`, `google_adc` and `azure_entra` without a
+ * reference sign from the ambient AWS/Google/Azure chain, so there is no value
+ * for this layer to hand over and that is not an error.
+ */
+export declare function resolveEntryCredential(entry: AIProviderEntry, options?: CredentialStoreOptions): ResolvedCredential;
+/** Prefix of the per-entry credential variable the harness adapters read. */
+export declare const PROVIDER_CREDENTIAL_ENV_PREFIX: "SKAILE_AIP_";
+/** Suffix of the per-entry credential variable. */
+export declare const PROVIDER_CREDENTIAL_ENV_SUFFIX: "_KEY";
+/**
+ * Canonical environment variable name carrying one entry's credential.
+ *
+ * `SKAILE_AIP_<ID>_KEY`, with every non-alphanumeric character in the id mapped
+ * to `_` (`my-gw.eu` → `SKAILE_AIP_MY_GW_EU_KEY`). The runtime's harness
+ * adapters write this *name* into the config they render (omp's `models.yml`
+ * `apiKey:`, Codex's `env_key`) and read the *value* from the child
+ * environment, which is what this function's callers fill in. The platform's
+ * secret-env allowlist is the `SKAILE_AIP_` prefix rule over the same names, so
+ * the transform must not drift.
+ */
+export declare function providerCredentialEnvName(providerId: string): string;
+/** One entry's credential delivery outcome. */
+export interface CredentialDelivery {
+    providerId: string;
+    /** Variable names this entry contributed to the child environment. */
+    names: string[];
+    source: CredentialSource;
+    /** Why nothing was delivered. Secret-free. */
+    error?: string;
+}
+/** Result of {@link registryCredentialEnv}. */
+export interface RegistryCredentialEnv {
+    /** Variable name → secret. Pass into the child environment, never into a file. */
+    env: Record<string, string>;
+    /** Per-entry outcome, in registry order — for logging and settings UIs. */
+    deliveries: CredentialDelivery[];
+}
+/**
+ * Resolve every enabled entry's credential into a child-process environment.
+ *
+ * Each resolved entry contributes `SKAILE_AIP_<ID>_KEY`; an entry whose
+ * reference is `env:NAME` also re-exports `NAME`, so a harness that still reads
+ * its vendor's conventional variable keeps working without forge owning a
+ * vendor table. The first entry in registry order wins a name collision.
+ *
+ * Entries that resolve elsewhere (`cmd:` in the runtime, `platform:` in the
+ * control plane) or sign from an ambient chain contribute nothing and say so in
+ * {@link RegistryCredentialEnv.deliveries} — the spawned session resolves those
+ * itself from the same registry.
+ */
+export declare function registryCredentialEnv(registry: AIProviderRegistryView, options?: CredentialStoreOptions): RegistryCredentialEnv;

package/dist/runtime/server/credential-store.js

@@ -0,0 +1,234 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { globalSettingsPath } from "@skaile/workspaces/sdk/core";
+import { isEntryEnabled, parseCredentialRef, registryEntries } from "../shared/provider-registry.js";
+import {
+  credentialRefRefusal,
+  entryPolicyRefusal
+} from "./credential-policy.js";
+export const CREDENTIAL_PREFIX = "enc:";
+const STORE_FILENAME = "forge-credentials.json";
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 16;
+const TAG_LENGTH = 16;
+export class CredentialKeyError extends Error {
+  code;
+  statusCode = 503;
+  constructor(code, message) {
+    super(message);
+    this.name = "CredentialKeyError";
+    this.code = code;
+  }
+}
+export class CredentialDecryptError extends Error {
+  constructor() {
+    super(
+      "Encrypted credential could not be authenticated: wrong key, altered data, or it belongs to a different reference."
+    );
+    this.name = "CredentialDecryptError";
+  }
+}
+function parseKey(key) {
+  if (key.length !== 64) {
+    throw new CredentialKeyError(
+      "invalid",
+      `FORGE_CREDENTIAL_KEY must be a 64-character hex string (32 bytes). Got ${key.length} chars.`
+    );
+  }
+  if (!/^[0-9a-fA-F]{64}$/.test(key)) {
+    throw new CredentialKeyError(
+      "invalid",
+      "FORGE_CREDENTIAL_KEY contains non-hex characters. Provide a 64-char hex string."
+    );
+  }
+  return Buffer.from(key, "hex");
+}
+export function encryptCredential(plaintext, hexKey, ref) {
+  if (!plaintext) throw new Error("plaintext must not be empty");
+  if (!ref) throw new Error("ref must not be empty \u2014 credentials are encrypted per reference");
+  const key = parseKey(hexKey);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  cipher.setAAD(Buffer.from(ref, "utf8"));
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${CREDENTIAL_PREFIX}${Buffer.concat([iv, tag, encrypted]).toString("base64")}`;
+}
+function splitBlob(ciphertext) {
+  if (!ciphertext.startsWith(CREDENTIAL_PREFIX)) {
+    throw new Error(
+      `Value is not encrypted (missing '${CREDENTIAL_PREFIX}' prefix). Pass plaintext through encryptCredential() first.`
+    );
+  }
+  const blob = Buffer.from(ciphertext.slice(CREDENTIAL_PREFIX.length), "base64");
+  if (blob.length < IV_LENGTH + TAG_LENGTH + 1) {
+    throw new Error("Encrypted blob is too short \u2014 data is corrupted.");
+  }
+  return {
+    iv: blob.subarray(0, IV_LENGTH),
+    tag: blob.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH),
+    body: blob.subarray(IV_LENGTH + TAG_LENGTH)
+  };
+}
+export function decryptCredential(ciphertext, hexKey, ref) {
+  const { iv, tag, body } = splitBlob(ciphertext);
+  const decipher = createDecipheriv(ALGORITHM, parseKey(hexKey), iv);
+  decipher.setAAD(Buffer.from(ref, "utf8"));
+  decipher.setAuthTag(tag);
+  try {
+    return decipher.update(body) + decipher.final("utf8");
+  } catch {
+    throw new CredentialDecryptError();
+  }
+}
+function envOf(options) {
+  return options.env ?? (options.policy ? {} : process.env);
+}
+export function credentialStorePath(options = {}) {
+  if (options.path) return options.path;
+  const fromEnv = envOf(options).FORGE_CREDENTIAL_STORE;
+  if (fromEnv) return fromEnv;
+  return join(dirname(globalSettingsPath()), STORE_FILENAME);
+}
+function requireKey(options) {
+  const key = options.key ?? envOf(options).FORGE_CREDENTIAL_KEY;
+  if (!key) {
+    throw new CredentialKeyError(
+      "missing",
+      "FORGE_CREDENTIAL_KEY is not set \u2014 the forge credential store cannot encrypt or decrypt stored credentials. Set it to a 64-char hex string (32 bytes)."
+    );
+  }
+  return key;
+}
+function readStore(path) {
+  if (!existsSync(path)) return { version: 1, credentials: {} };
+  const parsed = JSON.parse(readFileSync(path, "utf8"));
+  const credentials = typeof parsed === "object" && parsed !== null ? parsed.credentials : void 0;
+  if (typeof credentials !== "object" || credentials === null || Array.isArray(credentials)) {
+    return { version: 1, credentials: {} };
+  }
+  return { version: 1, credentials };
+}
+function writeStore(path, store) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(store, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+}
+export function storeCredential(ref, value, options = {}) {
+  const parsed = parseCredentialRef(ref);
+  if (parsed?.form !== "keyring") {
+    throw new Error(
+      `'${ref}' is not a keyring reference \u2014 the local store only backs keyring:<service>/<account>. env:/cmd:/platform: references live outside forge.`
+    );
+  }
+  const path = credentialStorePath(options);
+  const store = readStore(path);
+  store.credentials[ref] = encryptCredential(value, requireKey(options), ref);
+  writeStore(path, store);
+  return path;
+}
+export function readStoredCredential(ref, options = {}) {
+  const blob = readStore(credentialStorePath(options)).credentials[ref];
+  if (!blob) return void 0;
+  return decryptCredential(blob, requireKey(options), ref);
+}
+export function deleteStoredCredential(ref, options = {}) {
+  const path = credentialStorePath(options);
+  const store = readStore(path);
+  if (store.credentials[ref] === void 0) return false;
+  delete store.credentials[ref];
+  writeStore(path, store);
+  return true;
+}
+export function listStoredCredentialRefs(options = {}) {
+  return Object.keys(readStore(credentialStorePath(options)).credentials);
+}
+export function resolveCredentialRef(ref, options = {}) {
+  const parsed = parseCredentialRef(ref);
+  if (!parsed) {
+    return {
+      source: "none",
+      error: "credential.ref is not a reference (expected env:NAME, cmd:<shell>, platform:<configId> or keyring:<service>/<account>)"
+    };
+  }
+  const refusal = options.policy ? credentialRefRefusal(ref, options.policy) : void 0;
+  if (refusal) return { source: parsed.form, error: refusal };
+  switch (parsed.form) {
+    case "env": {
+      const value = envOf(options)[parsed.name];
+      if (!value) {
+        return { source: "env", error: `environment variable ${parsed.name} is not set` };
+      }
+      return { source: "env", value };
+    }
+    case "keyring": {
+      try {
+        const value = readStoredCredential(ref, options);
+        if (!value) {
+          return { source: "keyring", error: `no credential is stored for '${ref}'` };
+        }
+        return { source: "keyring", value };
+      } catch (err) {
+        return { source: "keyring", error: err.message };
+      }
+    }
+    case "cmd":
+      return {
+        source: "cmd",
+        error: "cmd: references are run by the runtime that owns the shell \u2014 the spawned session resolves this reference itself"
+      };
+    case "platform":
+      return {
+        source: "platform",
+        error: "platform: references are injected by the control plane into the session"
+      };
+  }
+}
+export function resolveEntryCredential(entry, options = {}) {
+  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : void 0;
+  if (refusal) return { source: "none", error: refusal };
+  const credential = entry.credential;
+  if (!credential || credential.kind === "none") return { source: "none" };
+  if (!credential.ref) {
+    if (credential.kind === "sigv4" || credential.kind === "google_adc" || credential.kind === "azure_entra") {
+      return { source: "ambient" };
+    }
+    return { source: "none", error: `credential.ref is missing for kind '${credential.kind}'` };
+  }
+  return resolveCredentialRef(credential.ref, options);
+}
+export const PROVIDER_CREDENTIAL_ENV_PREFIX = "SKAILE_AIP_";
+export const PROVIDER_CREDENTIAL_ENV_SUFFIX = "_KEY";
+export function providerCredentialEnvName(providerId) {
+  const slug = providerId.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+  return `${PROVIDER_CREDENTIAL_ENV_PREFIX}${slug}${PROVIDER_CREDENTIAL_ENV_SUFFIX}`;
+}
+export function registryCredentialEnv(registry, options = {}) {
+  const env = {};
+  const deliveries = [];
+  for (const [providerId, entry] of registryEntries(registry)) {
+    if (!isEntryEnabled(entry)) continue;
+    const resolved = resolveEntryCredential(entry, options);
+    const names = [];
+    if (resolved.value) {
+      const canonical = providerCredentialEnvName(providerId);
+      if (env[canonical] === void 0) {
+        env[canonical] = resolved.value;
+        names.push(canonical);
+      }
+      const parsed = entry.credential?.ref ? parseCredentialRef(entry.credential.ref) : void 0;
+      if (parsed?.form === "env" && env[parsed.name] === void 0) {
+        env[parsed.name] = resolved.value;
+        names.push(parsed.name);
+      }
+    }
+    deliveries.push({
+      providerId,
+      names,
+      source: resolved.source,
+      ...resolved.error ? { error: resolved.error } : {}
+    });
+  }
+  return { env, deliveries };
+}

package/dist/runtime/server/env-layers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Layered `.env` files — the server half of the settings modal's Providers
+ * tab (credential picker, Enter a key, environment disclosure).
+ *
+ * A registry entry references its secret as `env:NAME`; the host resolves that
+ * name against a layered environment where the nearest layer wins:
+ * `process` (boot env) < `instance` (`$FORGE_HOME/.env`) < `workspace`
+ * (`<workspace root>/.env`). This module reads and edits those files and builds
+ * the document the browser sees — names, masked hints and lengths, never
+ * values.
+ *
+ * The vocabulary (layer ids, name rules, document shapes) lives in the
+ * browser-safe `utils/env-vars.ts` and is re-exported here, so client and
+ * server refuse the same names from one source.
+ */
+import type { AIProviderRegistryView } from "../shared/provider-registry.js";
+import { type EnvLayerId, type EnvSettingsDocument, type EnvSettingsUpdate } from "../shared/env-vars.js";
+export * from "../shared/env-vars.js";
+/**
+ * Parse `.env` text: blank and `#` lines skipped, optional `export ` prefix,
+ * single-quoted values literal, double-quoted values unescape `\n`, `\"`, `\\`,
+ * unquoted values lose an inline ` #` comment. A later duplicate wins.
+ */
+export declare function parseDotenv(text: string): Record<string, string>;
+/** Parsed `.env` file; `{}` when it is missing or unreadable. */
+export declare function readDotenvFile(path: string): Record<string, string>;
+/**
+ * Apply `patch` to the `.env` file at `path`, preserving every line it does not
+ * touch. A patched key's first `KEY=` / `export KEY=` line is rewritten in
+ * place and its later duplicates dropped; `null` deletes the key; keys the file
+ * lacks are appended. The file is created (parents included) when missing and
+ * always left at mode 0600.
+ */
+export declare function updateDotenvFile(path: string, patch: Record<string, string | null>): void;
+/**
+ * Make sure `<dir>/.gitignore` ignores `.env`: appends the line unless an
+ * equivalent pattern is already present, creating the file when missing.
+ */
+export declare function ensureDotenvIgnored(dir: string): void;
+/** Input of {@link buildEnvSettingsDocument}. */
+export interface EnvSettingsDocumentInput {
+    scope: "instance" | "workspace";
+    editable: boolean;
+    /** The layers visible from this scope; absent layers are ignored. */
+    layers: Partial<Record<EnvLayerId, Record<string, string | undefined>>>;
+    /** Registry whose `env:` references are reported (`referencedBy`, `missing`). */
+    registry: AIProviderRegistryView;
+}
+/**
+ * The browser's view of a scope's environment. Lists every name an editable
+ * layer (instance, workspace) holds, every name a registry `env:` reference
+ * uses, and every catalog preset's conventional key name that some layer sets
+ * — so the credential picker can tell a set `OPENROUTER_API_KEY` from an unset
+ * one. Other process variables stay unlisted. Values never leave: each row
+ * carries only a hint and a length.
+ */
+export declare function buildEnvSettingsDocument(input: EnvSettingsDocumentInput): EnvSettingsDocument;
+/**
+ * Validate a `PUT <environmentUrl>` body. Returns the normalized update, or a
+ * refusal string suitable as an HTTP 400 status message.
+ */
+export declare function validateEnvSettingsUpdate(body: unknown): EnvSettingsUpdate | string;