@skaile/forge-settings 1.3.3 → 2.0.0

package/src/runtime/shared/provider-accounts.ts

@@ -0,0 +1,526 @@
+/**
+ * Provider accounts: how one signs in to a catalog preset, what a provider
+ * row says about its account, and the Microsoft Azure account that writes up
+ * to two registry entries (Azure OpenAI and Claude on Foundry) sharing one
+ * resource and one credential.
+ *
+ * Pure and browser-safe: the settings panel and the server's write gate read
+ * the same rules. The facts come from the catalog preset
+ * (`@skaile/provider-registry/catalog`'s `AIProviderPreset`): its `credential.kind`, its
+ * `transport`, its default `params` and its `required_params`. The catalog
+ * names no list of accepted sign-in kinds, so they are derived here from those
+ * facts.
+ */
+
+import {
+  type AIProviderCredential,
+  type AIProviderCredentialKind,
+  type AIProviderTransport,
+  validateCredentialRef,
+} from "./provider-registry";
+
+// ── Presets ──────────────────────────────────────────────────────────────────
+
+/** The preset facts the account helpers read; a catalog preset and its summary both fit. */
+export interface ProviderAccountPreset {
+  id: string;
+  label: string;
+  transport?: AIProviderTransport;
+  credential: { kind: AIProviderCredentialKind; env?: string };
+  /** Default routing parameters. */
+  params?: Record<string, string>;
+  /** `params` keys the operator must supply. */
+  required_params?: string[];
+}
+
+/**
+ * The `params` keys a preset requires that `params` leaves empty: the
+ * preset's `required_params` minus the ones its own `params` default.
+ * A value that is not a non-blank string, number or boolean counts as missing.
+ */
+export function missingRequiredParams(
+  preset: Pick<ProviderAccountPreset, "required_params" | "params">,
+  params: Record<string, unknown> | undefined,
+): string[] {
+  return (preset.required_params ?? []).filter((key) => {
+    if (preset.params?.[key] !== undefined) return false;
+    const value = params?.[key];
+    if (typeof value === "number" || typeof value === "boolean") return false;
+    return typeof value !== "string" || value.trim() === "";
+  });
+}
+
+/** What the add/edit dialog calls each routing parameter. */
+export const PROVIDER_PARAM_LABELS: Record<string, string> = {
+  resource: "Resource",
+  deployment: "Deployment",
+  api_version: "API version",
+  region: "Region",
+  project: "Project",
+  location: "Location",
+  publisher: "Publisher",
+};
+
+/**
+ * Parameters the operator sets only in expert mode: the dialog prefills them
+ * and shows them read-only otherwise.
+ */
+export const EXPERT_PARAMS: readonly string[] = ["api_version"];
+
+/**
+ * The parameter fields an entry of `preset` needs: its required params the
+ * preset gives no default for, then any further key `current` already holds.
+ */
+export function presetParamKeys(
+  preset: Pick<ProviderAccountPreset, "required_params" | "params"> | null | undefined,
+  current: Record<string, unknown> | undefined = undefined,
+): string[] {
+  const keys = (preset?.required_params ?? []).filter((key) => preset?.params?.[key] === undefined);
+  for (const key of Object.keys(current ?? {})) if (!keys.includes(key)) keys.push(key);
+  return keys;
+}
+
+/** The value the dialog prefills for parameter `key` of `presetId`, else `""`. */
+export function defaultParamValue(presetId: string | undefined, key: string): string {
+  return presetId === AZURE_OPENAI_PRESET && key === "api_version"
+    ? AZURE_OPENAI_DEFAULT_API_VERSION
+    : "";
+}
+
+// ── Sign-in kinds ────────────────────────────────────────────────────────────
+
+/** One way to sign in to a provider, as the add flow's "How do you sign in?" step lists it. */
+export type ProviderSignInId =
+  | "api_key"
+  | "entra"
+  | "aws"
+  | "google"
+  | "oauth"
+  | "none"
+  | "reference";
+
+/** What the sign-in step offers for one {@link ProviderSignInId}. */
+export interface ProviderSignInOption {
+  id: ProviderSignInId;
+  label: string;
+  description: string;
+  /** The `credential.kind` the entry gets. */
+  credentialKind: AIProviderCredentialKind;
+  /**
+   * The fields the next step shows: `key` = environment variable name plus
+   * an optional value for the scope's `.env`; `reference` = a typed
+   * `env:` / `keyring:` / `cmd:` / `platform:` reference; `none` = nothing
+   * (no credential, or the server's ambient cloud chain signs).
+   */
+  fields: "key" | "reference" | "none";
+}
+
+/** Transports that run on a Microsoft Azure resource. */
+export const AZURE_TRANSPORTS: readonly AIProviderTransport[] = ["azure-openai", "foundry"];
+
+/** Whether a transport runs on a Microsoft Azure resource (and so accepts Entra ID). */
+export function isAzureTransport(transport: AIProviderTransport | undefined): boolean {
+  return transport !== undefined && AZURE_TRANSPORTS.includes(transport);
+}
+
+function apiKeyOption(kind: AIProviderCredentialKind): ProviderSignInOption {
+  return {
+    id: "api_key",
+    label: "API key",
+    description:
+      "A key from the provider. It is stored in this scope's environment; the entry only names the variable.",
+    credentialKind: kind,
+    fields: "key",
+  };
+}
+
+const ENTRA_OPTION: ProviderSignInOption = {
+  id: "entra",
+  label: "Entra ID",
+  description:
+    "Microsoft Entra ID: the server's Azure identity signs the requests (managed identity, az login or AZURE_CLIENT_ID / AZURE_CLIENT_SECRET / AZURE_TENANT_ID). No key is stored.",
+  credentialKind: "azure_entra",
+  fields: "none",
+};
+
+const AWS_OPTION: ProviderSignInOption = {
+  id: "aws",
+  label: "AWS credentials",
+  description: "The server's AWS default credential chain signs the requests. No key is stored.",
+  credentialKind: "sigv4",
+  fields: "none",
+};
+
+const GOOGLE_OPTION: ProviderSignInOption = {
+  id: "google",
+  label: "Google credentials",
+  description:
+    "Google application default credentials on the server sign the requests. No key is stored.",
+  credentialKind: "google_adc",
+  fields: "none",
+};
+
+const OAUTH_OPTION: ProviderSignInOption = {
+  id: "oauth",
+  label: "OAuth",
+  description: "An OAuth token held behind a reference (keyring, command or control plane).",
+  credentialKind: "oauth",
+  fields: "reference",
+};
+
+const NONE_OPTION: ProviderSignInOption = {
+  id: "none",
+  label: "No sign-in",
+  description: "The endpoint takes no credential, such as a model server on this machine.",
+  credentialKind: "none",
+  fields: "none",
+};
+
+function referenceOption(kind: AIProviderCredentialKind): ProviderSignInOption {
+  return {
+    id: "reference",
+    label: "Reference",
+    description:
+      "Type the credential reference yourself: env:NAME, keyring:service/account, cmd:… or platform:….",
+    credentialKind: kind,
+    fields: "reference",
+  };
+}
+
+/**
+ * The sign-in kinds a preset accepts, in the order the sign-in step lists
+ * them. `null` is a custom entry (no preset).
+ *
+ * - `none` presets (local model servers): No sign-in only.
+ * - `api_key_header` / `bearer` presets: API key; Azure transports
+ *   (`azure-openai`, `foundry`) list Entra ID first, then API key.
+ * - `oauth` / `command` presets: a reference (the token lives behind one).
+ * - `expert`: the raw Reference form is added for every preset that takes a
+ *   credential.
+ */
+export function presetSignInOptions(
+  preset: Pick<ProviderAccountPreset, "credential" | "transport"> | null,
+  options: { expert?: boolean } = {},
+): ProviderSignInOption[] {
+  const out: ProviderSignInOption[] = [];
+  const kind = preset?.credential.kind;
+  if (!preset) {
+    out.push(apiKeyOption("bearer"), NONE_OPTION);
+  } else if (kind === "none") {
+    out.push(NONE_OPTION);
+  } else if (kind === "sigv4") {
+    out.push(AWS_OPTION);
+  } else if (kind === "google_adc") {
+    out.push(GOOGLE_OPTION);
+  } else if (kind === "azure_entra") {
+    out.push(ENTRA_OPTION);
+  } else if (kind === "oauth") {
+    out.push(OAUTH_OPTION);
+  } else if (kind === "command") {
+    out.push(referenceOption("command"));
+  } else if (kind === "api_key_header" || kind === "bearer") {
+    if (isAzureTransport(preset.transport)) out.push(ENTRA_OPTION);
+    out.push(apiKeyOption(kind));
+  }
+  const referenceKind: AIProviderCredentialKind = kind ?? "bearer";
+  if (options.expert && referenceKind !== "none" && !out.some((o) => o.fields === "reference")) {
+    out.push(referenceOption(referenceKind));
+  }
+  return out;
+}
+
+/** What the sign-in fields hold. */
+export interface ProviderSignInInput {
+  /** `key` fields: the environment variable the key lives in. */
+  envName?: string;
+  /** `reference` fields: the typed reference. */
+  ref?: string;
+}
+
+/** The credential a sign-in choice writes, or why it cannot be written. */
+export type ProviderSignInCredential =
+  | { ok: true; credential?: AIProviderCredential }
+  | { ok: false; error: string };
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The `credential` of an entry signed in with `option`.
+ *
+ * `key`: `{ kind, ref: "env:<NAME>" }`; a blank name falls back to
+ * `defaultEnv` (the preset's conventional variable) and, without one, writes
+ * no credential so the preset's own applies — unless `requireCredential`.
+ * `reference`: `{ kind, ref }` after the reference check. `none` fields: a
+ * cloud chain writes `{ kind }` without a reference, No sign-in writes
+ * `{ kind: "none" }`.
+ */
+export function signInCredential(
+  option: ProviderSignInOption,
+  input: ProviderSignInInput,
+  context: { defaultEnv?: string; requireCredential?: boolean } = {},
+): ProviderSignInCredential {
+  if (option.fields === "none") return { ok: true, credential: { kind: option.credentialKind } };
+  if (option.fields === "reference") {
+    const ref = input.ref?.trim() ?? "";
+    if (!ref) return { ok: false, error: "Enter a credential reference." };
+    const refusal = validateCredentialRef(ref);
+    if (refusal) return { ok: false, error: refusal };
+    return { ok: true, credential: { kind: option.credentialKind, ref } };
+  }
+  const name = input.envName?.trim() || context.defaultEnv || "";
+  if (!name) {
+    return context.requireCredential
+      ? { ok: false, error: "Name the environment variable the key is stored in." }
+      : { ok: true };
+  }
+  if (!ENV_NAME.test(name)) {
+    return { ok: false, error: `'${name}' is not a valid environment variable name.` };
+  }
+  return { ok: true, credential: { kind: option.credentialKind, ref: `env:${name}` } };
+}
+
+/** The sign-in option an existing credential corresponds to, among `options`. */
+export function signInOptionOf(
+  credential: { kind?: AIProviderCredentialKind; ref?: string } | undefined,
+  options: readonly ProviderSignInOption[],
+): ProviderSignInOption | undefined {
+  if (!credential?.kind) return options[0];
+  const sameKind = options.filter((o) => o.credentialKind === credential.kind);
+  const ref = credential.ref;
+  const wanted: ProviderSignInOption["fields"] = !ref
+    ? sameKind.some((o) => o.fields === "none")
+      ? "none"
+      : "key"
+    : ref.startsWith("env:")
+      ? "key"
+      : "reference";
+  return sameKind.find((o) => o.fields === wanted) ?? sameKind[0];
+}
+
+// ── Account line ─────────────────────────────────────────────────────────────
+
+/** What a row says for each credential kind. */
+export const CREDENTIAL_KIND_LABELS: Record<AIProviderCredentialKind, string> = {
+  api_key_header: "API key",
+  bearer: "API key",
+  azure_entra: "Entra ID",
+  sigv4: "AWS credentials",
+  google_adc: "Google credentials",
+  oauth: "OAuth",
+  command: "Command",
+  none: "No sign-in",
+};
+
+/** The family an Azure-transport entry belongs to. */
+export const AZURE_FAMILY_LABEL = "Microsoft Azure";
+
+/**
+ * The provider family a row belongs to: "Microsoft Azure" for an
+ * Azure transport, else its preset's label, else "Custom".
+ */
+export function providerFamilyLabel(
+  entry: { preset?: string; transport?: AIProviderTransport },
+  presets: readonly Pick<ProviderAccountPreset, "id" | "label" | "transport">[],
+): string {
+  const preset = entry.preset ? presets.find((p) => p.id === entry.preset) : undefined;
+  if (isAzureTransport(entry.transport ?? preset?.transport)) return AZURE_FAMILY_LABEL;
+  return preset?.label ?? (entry.preset ? entry.preset : "Custom");
+}
+
+/**
+ * The account line of a provider row: family · sign-in kind · resource, each
+ * part only when known — "Microsoft Azure · Entra ID · contoso-ai".
+ */
+export function providerAccountLine(
+  entry: {
+    preset?: string;
+    transport?: AIProviderTransport;
+    credentialKind?: AIProviderCredentialKind;
+    transportParams?: Record<string, string>;
+  },
+  presets: readonly Pick<ProviderAccountPreset, "id" | "label" | "transport" | "credential">[],
+): string {
+  const preset = entry.preset ? presets.find((p) => p.id === entry.preset) : undefined;
+  const kind = entry.credentialKind ?? preset?.credential.kind;
+  const resource = entry.transportParams?.resource?.trim();
+  return [
+    providerFamilyLabel(entry, presets),
+    kind ? CREDENTIAL_KIND_LABELS[kind] : null,
+    resource || null,
+  ]
+    .filter((part): part is string => !!part)
+    .join(" · ");
+}
+
+// ── Credential expiry ────────────────────────────────────────────────────────
+
+/** A credential's expiry as a row shows it. */
+export interface CredentialExpiry {
+  /** Whole days left, rounded down; `0` = expires within a day, negative = expired. */
+  days: number;
+  expired: boolean;
+  /** "Expires in 12 days" · "Expires in 1 day" · "Expires today" · "Expired". */
+  text: string;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The expiry line for an ISO timestamp, or `null` when there is none or it does not parse. */
+export function credentialExpiry(
+  expiresAt: string | null | undefined,
+  now: number = Date.now(),
+): CredentialExpiry | null {
+  if (!expiresAt) return null;
+  const at = Date.parse(expiresAt);
+  if (!Number.isFinite(at)) return null;
+  if (at <= now) return { days: Math.floor((at - now) / DAY_MS), expired: true, text: "Expired" };
+  const days = Math.floor((at - now) / DAY_MS);
+  const text = days === 0 ? "Expires today" : `Expires in ${days} day${days === 1 ? "" : "s"}`;
+  return { days, expired: false, text };
+}
+
+// ── Microsoft Azure account ──────────────────────────────────────────────────
+
+/** Catalog preset of the Azure OpenAI entry. */
+export const AZURE_OPENAI_PRESET = "azure-openai";
+/** Catalog preset of the Claude on Foundry entry. */
+export const FOUNDRY_PRESET = "foundry";
+
+/**
+ * The `api_version` the Azure account prefills when the preset names none
+ * (the catalog's `azure-openai` preset requires it but has no default).
+ */
+export const AZURE_OPENAI_DEFAULT_API_VERSION = "2025-04-01-preview";
+
+/** One deployment row: the Azure deployment name and the logical model id it serves. */
+export interface ProviderDeploymentRow {
+  deployment: string;
+  /** Logical model id (the `model_map` key). Blank: the deployment name. */
+  model: string;
+}
+
+/**
+ * `model_map` (logical id → deployment name) from deployment rows. Rows with
+ * both fields blank are skipped; a model without a deployment, or two rows
+ * naming the same logical id, is refused.
+ */
+export function deploymentModelMap(
+  rows: readonly ProviderDeploymentRow[],
+): { ok: true; modelMap: Record<string, string> } | { ok: false; error: string } {
+  const modelMap: Record<string, string> = {};
+  for (const row of rows) {
+    const deployment = row.deployment.trim();
+    const model = row.model.trim();
+    if (!deployment && !model) continue;
+    if (!deployment) return { ok: false, error: `Name the deployment that serves '${model}'.` };
+    const id = model || deployment;
+    if (Object.hasOwn(modelMap, id)) return { ok: false, error: `Model '${id}' is listed twice.` };
+    modelMap[id] = deployment;
+  }
+  return { ok: true, modelMap };
+}
+
+/** What the Microsoft Azure card collects. */
+export interface AzureAccountInput {
+  /** Azure resource name: the `{resource}` of `<resource>.openai.azure.com` / `<resource>.services.ai.azure.com`. */
+  resource: string;
+  /** The one credential both entries get (from {@link signInCredential}). */
+  credential?: AIProviderCredential;
+  /** Set: write an Azure OpenAI entry. At least one deployment. */
+  openai?: { deployments: readonly ProviderDeploymentRow[]; apiVersion: string };
+  /** Set: write a Claude on Foundry entry; deployments are optional. */
+  foundry?: { deployments: readonly ProviderDeploymentRow[] };
+  /** Entry ids the scope already uses; new ids avoid them. */
+  takenIds?: readonly string[];
+}
+
+/** One entry to `PUT`: its id and body. */
+export interface ProviderEntryDraft {
+  id: string;
+  body: Record<string, unknown>;
+}
+
+/** Azure resource names: letters, digits and inner hyphens. */
+const AZURE_RESOURCE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+
+function freeId(base: string, resource: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base;
+  const slug = resource
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const withResource = slug ? `${base}-${slug}` : base;
+  if (!taken.has(withResource)) return withResource;
+  for (let n = 2; ; n++) {
+    const candidate = `${withResource}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+
+/**
+ * The registry entries one Microsoft Azure account writes: an Azure OpenAI
+ * entry (preset `azure-openai`, `params` `{ resource, deployment, api_version }`
+ * with the first deployment as the routed one, `model_map` from the
+ * deployment rows) and/or a Claude on Foundry entry (preset `foundry`,
+ * `params.resource`, optional `model_map`). Both carry the same resource and
+ * the same credential. Ids are the preset ids, else `<preset>-<resource>`,
+ * else numbered, never one of `takenIds`.
+ */
+export function azureAccountEntries(
+  input: AzureAccountInput,
+): { ok: true; entries: ProviderEntryDraft[] } | { ok: false; error: string } {
+  const resource = input.resource.trim();
+  if (!resource) return { ok: false, error: "Enter the Azure resource name." };
+  if (!AZURE_RESOURCE.test(resource)) {
+    return {
+      ok: false,
+      error:
+        "An Azure resource name has letters, digits and hyphens, and starts and ends with a letter or digit.",
+    };
+  }
+  if (!input.openai && !input.foundry) {
+    return { ok: false, error: "Choose Azure OpenAI, Claude on Foundry or both." };
+  }
+  const taken = new Set(input.takenIds ?? []);
+  const entries: ProviderEntryDraft[] = [];
+  const credential = input.credential ? { credential: { ...input.credential } } : {};
+
+  if (input.openai) {
+    const map = deploymentModelMap(input.openai.deployments);
+    if (!map.ok) return map;
+    const first = Object.values(map.modelMap)[0];
+    if (!first) return { ok: false, error: "Add at least one Azure OpenAI deployment." };
+    const apiVersion = input.openai.apiVersion.trim();
+    if (!apiVersion) return { ok: false, error: "Enter the Azure OpenAI api_version." };
+    const id = freeId(AZURE_OPENAI_PRESET, resource, taken);
+    taken.add(id);
+    entries.push({
+      id,
+      body: {
+        preset: AZURE_OPENAI_PRESET,
+        label: "Azure OpenAI",
+        params: { resource, deployment: first, api_version: apiVersion },
+        model_map: map.modelMap,
+        ...credential,
+      },
+    });
+  }
+
+  if (input.foundry) {
+    const map = deploymentModelMap(input.foundry.deployments);
+    if (!map.ok) return map;
+    const id = freeId(FOUNDRY_PRESET, resource, taken);
+    taken.add(id);
+    entries.push({
+      id,
+      body: {
+        preset: FOUNDRY_PRESET,
+        label: "Claude on Foundry",
+        params: { resource },
+        ...(Object.keys(map.modelMap).length > 0 ? { model_map: map.modelMap } : {}),
+        ...credential,
+      },
+    });
+  }
+  return { ok: true, entries };
+}