@skaile/forge-settings

Provider and settings operations for Skaile forge apps, without the app's database, authentication or agent runtime.

| Entry | Contents | Peers it needs | |---|---|---| | /server | registry layers and writes, credential store, .env layers, provider inventory and discovery, harness settings rules, credential policy | none | | /vue | useProvidersPanel, SettingsModalScope, browser-safe registry/env/harness vocabulary | vue | | /nuxt | Nuxt module registering <ForgeProvidersPanel> | nuxt, @nuxt/ui | | /ai-sdk | AI SDK LanguageModel of a registry selector | ai + the @ai-sdk/* provider the surface needs | | /editor | the editor's ModelProvider over a registry | @skaile/forge-editor, @ai-sdk/openai-compatible |

Importing /server loads no Vue, editor, AI SDK or agent session code. Every peer is optional and used by one entry only.

What stays with the host

Where settings are stored, who may write which scope, workspace ACLs, lock flags, and what a failure becomes over HTTP. The package supplies the operations (upsertProviderEntry, removeProviderEntry, buildEnvSettingsDocument, …) and the rules they enforce on a document; the host builds a ProviderWriteScope (file paths, effective env, lock state, optional policy) after its own authentication and permission check.

Credential policy

A host that runs next to its own secrets (a database token, an encryption key) states up front which references may be resolved:

import { type CredentialPolicy } from '@skaile/forge-settings/server'

const policy: CredentialPolicy = {
  forms: ['env'],                                   // no cmd:, keyring:, platform:
  envNames: [/ASSISTENT_PROVIDER_[A-Z0-9_]+/, 'NUXT_AI_API_KEY'], // whole-name match
}

The policy is checked against credential.ref and every ${NAME} token in base_url, headers and query_params before anything is read; a refused reference is never resolved, looked up or requested. A policy-bound call reads only the env you pass (an empty one when omitted), never process.env. Without a policy, behaviour is the unrestricted forge-common behaviour.

const scope: ProviderWriteScope = { name: 'instance', file, below: [], env, lock, policy } // refuses writes naming a refused ref
discoverProviderModels('main', registry, { env, policy })
resolveRegistryLanguageModel('main/gpt-x', { projectDir, env, policy })

Credential store

keyring:<service>/<account> references are stored AES-256-GCM encrypted in a JSON file; the reference is the additional authenticated data, so a blob cannot be replayed under another reference. The key is FORGE_CREDENTIAL_KEY (64 hex characters) or options.key. Without it only operations that need the store fail, with CredentialKeyError (statusCode: 503); env: references keep working. A blob that does not authenticate raises CredentialDecryptError.

Model discovery

discoverProviderModels(id, registry, { env, policy?, redact? }) returns live, static (the offline catalog, with the scrubbed reason the live request failed), unsupported (no catalog preset: let the admin type a model id) or error. Error text never contains a remote response body, and every secret the call resolved (plus redact) is removed from it, also in URL-encoded and base64 form.

Models for the editor and the AI SDK

// server/utils/editor-models.ts: ModelProvider for @skaile/forge-editor
import { createEditorModelProvider, ModelResolutionError } from '@skaile/forge-settings/editor'

export const models = createEditorModelProvider({
  registry: () => getProviderRegistry(home()),
  env: () => effectiveEnv(),
  policy,                                            // refused entries are neither listed nor resolved
  onFailure: (e) => createError({ statusCode: e.code === 'policy_refused' ? 403 : 400, statusMessage: e.message }),
})

import { resolveRegistryLanguageModel } from '@skaile/forge-settings/ai-sdk'
const { model } = await resolveRegistryLanguageModel('assistant-default/some-model', { projectDir, env, policy })

Role-to-selector mapping belongs to the host's settings document; there is no global model locator. Failures are ModelResolutionError with a code; messages never carry a secret.

Pass registry (an already merged registry, e.g. one routed through the Workspaces transform proxy) to resolve against it instead of the providers on disk; the policy check runs on it and Workspaces receives it unchanged.

Providers panel

// nuxt.config.ts: '@nuxt/ui' BEFORE this module
modules: ['@nuxt/ui', '@skaile/forge-settings/nuxt']

<ForgeProvidersPanel
  providers-url="/api/providers" providers-write-url="/api/providers"
  environment-url="/api/settings/env" layer="instance" :read-only="!canAdmin"
  @changed="reload" />

The panel (PUT|DELETE <writeUrl>/:id, GET <writeUrl>/detected, GET <providersUrl>, GET|PUT <environmentUrl>) reads and writes only the routes you give it. The host serves them with the /server operations and decides who may call them. SettingsModalScope documents the same URL fields for hosts that compose a larger modal.

Development

bun install
bun run prepare     # generate module types
bun run typecheck
bun run test
bun run build

Releases: push a v* tag equal to the package.json version; publish.yml publishes with npm trusted publishing. gh workflow run publish.yml --ref main is a dry run that publishes nothing but fails unless npmjs accepts the workflow's OIDC token.