@shawnstack/quickforge 1.7.4 → 1.7.6

package/server/cloud/config.mjs

@@ -0,0 +1,54 @@
+import net from 'node:net'
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+function isLoopbackHost(hostname) {
+  const host = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '')
+  if (host === 'localhost' || host.endsWith('.localhost')) return true
+  const ip = net.isIP(host)
+  if (ip === 4) return host.startsWith('127.')
+  if (ip === 6) return host === '::1' || host === '0:0:0:0:0:0:0:1'
+  return false
+}
+
+export function parseCloudBaseUrl(value, _options = {}) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  if (!raw) return undefined
+
+  let url
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new Error('QUICKFORGE_CLOUD_URL must be a valid URL.')
+  }
+
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error('QUICKFORGE_CLOUD_URL must not contain credentials, query parameters, or fragments.')
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error('QUICKFORGE_CLOUD_URL must use http or https.')
+  }
+  if (url.protocol === 'http:' && !isLoopbackHost(url.hostname)) {
+    throw new Error('QUICKFORGE_CLOUD_URL over HTTP is only allowed for loopback hosts.')
+  }
+  if (url.pathname.includes('..')) throw new Error('QUICKFORGE_CLOUD_URL contains an unsafe path.')
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/`
+  return url
+}
+
+export function cloudEndpoint(baseUrl, pathname) {
+  if (!(baseUrl instanceof URL)) throw new Error('QuickForge Cloud is not configured.')
+  const relative = String(pathname || '').replace(/^\/+/, '')
+  if (!relative || relative.split('/').includes('..')) throw new Error('Invalid QuickForge Cloud endpoint.')
+  return new URL(relative, baseUrl)
+}
+
+export function readCloudConfig(env = process.env) {
+  const baseUrl = parseCloudBaseUrl(env.QUICKFORGE_CLOUD_URL)
+  const timeoutValue = Number(env.QUICKFORGE_CLOUD_TIMEOUT_MS || DEFAULT_TIMEOUT_MS)
+  return {
+    enabled: Boolean(baseUrl),
+    baseUrl,
+    timeoutMs: Number.isFinite(timeoutValue) ? Math.min(60_000, Math.max(1_000, timeoutValue)) : DEFAULT_TIMEOUT_MS,
+  }
+}

package/server/cloud/credential-store.mjs

@@ -0,0 +1,200 @@
+import { generateKeyPair, randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { createRandomToken } from '../utils/password-auth.mjs'
+import { ensureStorage, storageDir } from '../storage.mjs'
+
+const generateKeyPairAsync = promisify(generateKeyPair)
+const SCHEMA_VERSION = 1
+const ACCOUNT_FIELDS = ['id', 'email', 'plan']
+
+function publicAccount(value) {
+  if (!value || typeof value !== 'object') return undefined
+  const account = {}
+  for (const field of ACCOUNT_FIELDS) {
+    const candidate = value[field]
+    if (typeof candidate === 'string' && candidate) account[field] = candidate
+  }
+  return Object.keys(account).length ? account : undefined
+}
+
+function publicPendingDeviceFlow(value) {
+  if (!value || typeof value !== 'object') return undefined
+  const expiresAt = Number(value.expiresAt)
+  if (!Number.isFinite(expiresAt)) return undefined
+  return {
+    userCode: String(value.userCode || ''),
+    verificationUri: String(value.verificationUri || ''),
+    verificationUriComplete: String(value.verificationUriComplete || ''),
+    expiresAt,
+    interval: Math.max(1, Number(value.interval) || 5),
+    status: String(value.status || 'pending'),
+  }
+}
+
+function platformName(platform = process.platform) {
+  if (platform === 'win32') return 'windows'
+  if (platform === 'darwin') return 'macos'
+  return 'linux'
+}
+
+function defaultRecord({ installationName, platform, clientVersion } = {}) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    mode: 'local',
+    installationName: installationName || os.hostname() || 'QuickForge',
+    platform: platformName(platform),
+    clientVersion: clientVersion || 'unknown',
+    updatedAt: new Date().toISOString(),
+  }
+}
+
+function normalizeRecord(value, defaults) {
+  const input = value && typeof value === 'object' ? value : {}
+  const base = defaultRecord(defaults)
+  return {
+    ...base,
+    ...input,
+    schemaVersion: SCHEMA_VERSION,
+    mode: ['local', 'guest', 'account'].includes(input.mode) ? input.mode : 'local',
+    installationName: String(input.installationName || base.installationName).slice(0, 120),
+    platform: ['windows', 'macos', 'linux'].includes(input.platform) ? input.platform : base.platform,
+    clientVersion: String(input.clientVersion || base.clientVersion).slice(0, 80),
+  }
+}
+
+function publicRecord(record) {
+  return {
+    configured: true,
+    mode: record.mode,
+    installationId: record.installationId,
+    installationName: record.installationName,
+    platform: record.platform,
+    clientVersion: record.clientVersion,
+    hasInstallationKey: Boolean(record.publicKey && record.privateKeyPkcs8),
+    hasSession: Boolean(record.refreshToken),
+    account: publicAccount(record.account),
+    pendingDeviceFlow: publicPendingDeviceFlow(record.pendingDeviceFlow),
+    updatedAt: record.updatedAt,
+  }
+}
+
+async function generateInstallationKeyPair() {
+  const { publicKey, privateKey } = await generateKeyPairAsync('ed25519')
+  const publicJwk = publicKey.export({ format: 'jwk' })
+  return {
+    publicKey: publicJwk.x,
+    privateKeyPkcs8: privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url'),
+  }
+}
+
+export function createCloudCredentialStore({
+  filePath = path.join(storageDir, 'security', 'cloud-identity.json'),
+  ensureBaseStorage = ensureStorage,
+  installationName,
+  platform,
+  clientVersion,
+} = {}) {
+  let queue = Promise.resolve()
+  const defaults = { installationName, platform, clientVersion }
+
+  async function ensureDirectory() {
+    await ensureBaseStorage()
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 })
+  }
+
+  async function read() {
+    await ensureDirectory()
+    try {
+      const raw = await fs.readFile(filePath, 'utf8')
+      return normalizeRecord(raw.trim() ? JSON.parse(raw) : {}, defaults)
+    } catch (error) {
+      if (error?.code === 'ENOENT') return defaultRecord(defaults)
+      throw error
+    }
+  }
+
+  async function writeNow(record) {
+    await ensureDirectory()
+    const normalized = normalizeRecord({ ...record, updatedAt: new Date().toISOString() }, defaults)
+    const temporary = `${filePath}.${process.pid}.${createRandomToken(8)}.tmp`
+    await fs.writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    try { await fs.chmod(temporary, 0o600) } catch { /* best effort on Windows */ }
+    try {
+      await fs.rename(temporary, filePath)
+    } catch (error) {
+      if (!['EEXIST', 'EPERM'].includes(error?.code)) throw error
+      await fs.rm(filePath, { force: true })
+      await fs.rename(temporary, filePath)
+    }
+    try { await fs.chmod(filePath, 0o600) } catch { /* best effort on Windows */ }
+    return normalized
+  }
+
+  function update(mutator) {
+    const next = queue.catch(() => undefined).then(async () => {
+      const current = await read()
+      const result = await mutator({ ...current })
+      return writeNow(result || current)
+    })
+    queue = next
+    return next
+  }
+
+  async function ensureInstallation() {
+    const current = await read()
+    if (current.publicKey && current.privateKeyPkcs8 && current.installationId) return current
+    return update(async (record) => {
+      const keyPair = (record.publicKey && record.privateKeyPkcs8) ? {} : await generateInstallationKeyPair()
+      return {
+        ...record,
+        ...keyPair,
+        installationId: record.installationId || randomUUID(),
+      }
+    })
+  }
+
+  async function rotateInstallation() {
+    const keyPair = await generateInstallationKeyPair()
+    return update((record) => ({
+      ...record,
+      ...keyPair,
+      mode: 'local',
+      installationId: undefined,
+      refreshToken: undefined,
+      sessionCloudUrl: undefined,
+      pendingRegistrationKey: undefined,
+      pendingRegistrationHash: undefined,
+      pendingDeviceFlow: undefined,
+      account: undefined,
+      rotateInstallationBeforeRegistration: undefined,
+    }))
+  }
+
+  return {
+    filePath,
+    read,
+    update,
+    ensureInstallation,
+    rotateInstallation,
+    async readPublic() { return publicRecord(await read()) },
+    async clearSession({ rotateInstallationBeforeRegistration = false } = {}) {
+      return update((record) => ({
+        ...record,
+        mode: 'local',
+        installationId: undefined,
+        refreshToken: undefined,
+        sessionCloudUrl: undefined,
+        pendingRegistrationKey: undefined,
+        pendingRegistrationHash: undefined,
+        pendingDeviceFlow: undefined,
+        account: undefined,
+        rotateInstallationBeforeRegistration: rotateInstallationBeforeRegistration || undefined,
+      }))
+    },
+  }
+}
+
+export { publicRecord as publicCloudCredentialRecord }

package/server/cloud/identity.mjs

@@ -0,0 +1,312 @@
+import { CloudApiError } from './client.mjs'
+
+const SESSION_INVALID_CODES = new Set(['refresh_token_reused', 'installation_revoked', 'invalid_refresh_token'])
+const DEVICE_PENDING_CODES = new Set(['authorization_pending', 'pending'])
+const DEVICE_SLOW_DOWN_CODES = new Set(['slow_down'])
+const DEVICE_DENIED_CODES = new Set(['access_denied', 'authorization_declined', 'denied'])
+const DEVICE_EXPIRED_CODES = new Set(['expired_token', 'device_code_expired', 'expired'])
+const DEVICE_NETWORK_CODES = new Set(['cloud_unavailable', 'service_unavailable', 'temporarily_unavailable'])
+const DEVICE_NETWORK_CAUSE_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENETDOWN', 'ENETUNREACH', 'EHOSTUNREACH', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_SOCKET'])
+const DEVICE_CLIENT_ID = 'quickforge-desktop'
+const MODEL_CACHE_TTL_MS = 60_000
+const MODEL_CACHE_HARD_TTL_MS = 5 * 60_000
+
+function tokenExpiry(expiresIn) {
+  const seconds = Number(expiresIn)
+  return Date.now() + Math.max(1, Number.isFinite(seconds) ? seconds : 300) * 1000
+}
+
+function publicAccountSummary(value) {
+  if (!value || typeof value !== 'object') return undefined
+  const summary = {}
+  for (const field of ['id', 'email', 'plan']) {
+    const candidate = value[field]
+    if (typeof candidate === 'string' && candidate) summary[field] = candidate
+  }
+  return Object.keys(summary).length ? summary : undefined
+}
+
+function isDeviceFlowNetworkError(error) {
+  if (error instanceof CloudApiError) {
+    return error.retryable === true
+      || error.status >= 500
+      || DEVICE_NETWORK_CODES.has(error.code)
+  }
+  const causeCode = error?.cause?.code || error?.code
+  return error instanceof TypeError || DEVICE_NETWORK_CAUSE_CODES.has(causeCode)
+}
+
+
+export class CloudIdentityManager {
+  constructor({ client, store, serviceUrl } = {}) {
+    if (!client || !store) throw new Error('CloudIdentityManager requires client and store.')
+    this.client = client
+    this.store = store
+    this.serviceUrl = String(serviceUrl || client.baseUrl?.href || '')
+    if (!this.serviceUrl) throw new Error('CloudIdentityManager requires a service URL.')
+    this.accessToken = undefined
+    this.accessExpiresAt = 0
+    this.refreshPromise = undefined
+    this.devicePollPromise = undefined
+    this.modelsCache = undefined
+    this.modelsCachedAt = 0
+    this.modelsPromise = undefined
+  }
+
+  async status() {
+    let record = await this.store.read()
+    if (record.pendingDeviceFlow && Number(record.pendingDeviceFlow.expiresAt) <= Date.now()) {
+      record = await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+    }
+    const publicStatus = await this.store.readPublic()
+    const sessionServiceMismatch = Boolean(record.refreshToken && record.sessionCloudUrl !== this.serviceUrl)
+    const pendingServiceMismatch = Boolean(record.pendingDeviceFlow && record.pendingDeviceFlow.sessionCloudUrl !== this.serviceUrl)
+    return (sessionServiceMismatch || pendingServiceMismatch)
+      ? { ...publicStatus, sessionServiceMismatch: true }
+      : publicStatus
+  }
+
+  assertSessionService(record) {
+    if (record.refreshToken && record.sessionCloudUrl !== this.serviceUrl) {
+      throw new CloudApiError('The saved QuickForge Cloud session belongs to a different or unknown service. Rebuild the local Cloud identity before continuing.', {
+        status: 409,
+        code: 'cloud_session_service_mismatch',
+      })
+    }
+    if (record.pendingDeviceFlow && record.pendingDeviceFlow.sessionCloudUrl !== this.serviceUrl) {
+      throw new CloudApiError('The pending QuickForge Cloud sign-in belongs to a different service. Cancel or rebuild the local Cloud identity before continuing.', {
+        status: 409,
+        code: 'cloud_session_service_mismatch',
+      })
+    }
+  }
+
+
+  async startDeviceFlow({ signal } = {}) {
+    let record = await this.store.read()
+    this.assertSessionService(record)
+    if (record.mode === 'account' && record.refreshToken) {
+      throw new CloudApiError('QuickForge Cloud is already connected to an account.', { status: 409, code: 'cloud_account_already_connected' })
+    }
+    if (record.rotateInstallationBeforeRegistration) {
+      record = await this.store.rotateInstallation()
+    }
+    record = await this.store.ensureInstallation()
+    if (!record.installationId || !record.publicKey) {
+      throw new CloudApiError('QuickForge Cloud installation identity is incomplete.', { status: 409, code: 'cloud_installation_missing' })
+    }
+    this.assertSessionService(record)
+    const authorization = await this.client.authorizeDevice({
+      installationId: record.installationId,
+      clientId: DEVICE_CLIENT_ID,
+      publicKey: record.publicKey,
+      installationName: record.installationName,
+      platform: record.platform,
+      clientVersion: record.clientVersion,
+      signal,
+    })
+    const expiresIn = Math.max(1, Number(authorization?.expiresIn) || 600)
+    const interval = Math.max(1, Number(authorization?.interval) || 5)
+    const pendingDeviceFlow = {
+      deviceCode: String(authorization?.deviceCode || ''),
+      userCode: String(authorization?.userCode || ''),
+      verificationUri: String(authorization?.verificationUri || ''),
+      verificationUriComplete: String(authorization?.verificationUriComplete || ''),
+      expiresAt: Date.now() + expiresIn * 1000,
+      interval,
+      status: 'pending',
+      sessionCloudUrl: this.serviceUrl,
+    }
+    if (!pendingDeviceFlow.deviceCode || !pendingDeviceFlow.userCode || !pendingDeviceFlow.verificationUri) {
+      throw new CloudApiError('QuickForge Cloud returned an invalid device authorization response.', { code: 'invalid_device_authorization_response' })
+    }
+    await this.store.update((current) => ({ ...current, pendingDeviceFlow }))
+    return this.status()
+  }
+
+  async pollDeviceFlow(options = {}) {
+    if (this.devicePollPromise) return this.devicePollPromise
+    this.devicePollPromise = this.pollDeviceFlowOnce(options)
+      .finally(() => { this.devicePollPromise = undefined })
+    return this.devicePollPromise
+  }
+
+  async pollDeviceFlowOnce({ signal } = {}) {
+    const record = await this.store.read()
+    this.assertSessionService(record)
+    const pending = record.pendingDeviceFlow
+    if (!pending?.deviceCode) {
+      throw new CloudApiError('There is no pending QuickForge Cloud sign-in.', { status: 409, code: 'cloud_device_flow_not_pending' })
+    }
+    if (Number(pending.expiresAt) <= Date.now()) {
+      await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+      return { ...(await this.status()), deviceFlowResult: 'expired' }
+    }
+    try {
+      const tokens = await this.client.exchangeDeviceCode(pending.deviceCode, DEVICE_CLIENT_ID, signal)
+      if (!tokens?.refreshToken || !tokens?.accessToken) {
+        throw new CloudApiError('QuickForge Cloud returned an invalid account token response.', { code: 'invalid_token_response' })
+      }
+      this.setAccess(tokens)
+      this.modelsCache = undefined
+      this.modelsCachedAt = 0
+      this.modelsPromise = undefined
+      await this.store.update((current) => ({
+        ...current,
+        mode: 'account',
+        installationId: tokens.installationId || current.installationId,
+        refreshToken: tokens.refreshToken,
+        sessionCloudUrl: this.serviceUrl,
+        pendingDeviceFlow: undefined,
+        account: undefined,
+      }))
+      return { ...(await this.getStatusWithRemoteSummary(signal)), deviceFlowResult: 'success' }
+    } catch (error) {
+      if (DEVICE_PENDING_CODES.has(error?.code)) return { ...(await this.status()), deviceFlowResult: 'pending' }
+      if (DEVICE_SLOW_DOWN_CODES.has(error?.code)) {
+        await this.store.update((current) => ({
+          ...current,
+          pendingDeviceFlow: current.pendingDeviceFlow
+            ? { ...current.pendingDeviceFlow, interval: Math.max(1, Number(current.pendingDeviceFlow.interval) || 5) + 5, status: 'slow_down' }
+            : undefined,
+        }))
+        return { ...(await this.status()), deviceFlowResult: 'slow_down' }
+      }
+      if (DEVICE_DENIED_CODES.has(error?.code) || DEVICE_EXPIRED_CODES.has(error?.code)) {
+        await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+        return { ...(await this.status()), deviceFlowResult: DEVICE_DENIED_CODES.has(error?.code) ? 'denied' : 'expired' }
+      }
+      if (isDeviceFlowNetworkError(error)) {
+        return { ...(await this.status()), deviceFlowResult: 'network' }
+      }
+      throw error
+    }
+  }
+
+  async cancelDeviceFlow() {
+    const record = await this.store.read()
+    this.assertSessionService(record)
+    await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+    return this.status()
+  }
+
+  setAccess(tokens) {
+    this.accessToken = tokens?.accessToken
+    this.accessExpiresAt = tokenExpiry(tokens?.expiresIn)
+  }
+
+  async clearInvalidSession({ rotateInstallationBeforeRegistration = false } = {}) {
+    this.clearMemory()
+    await this.store.clearSession({ rotateInstallationBeforeRegistration })
+  }
+
+  clearMemory() {
+    this.accessToken = undefined
+    this.accessExpiresAt = 0
+    this.refreshPromise = undefined
+    this.devicePollPromise = undefined
+    this.modelsCache = undefined
+    this.modelsCachedAt = 0
+    this.modelsPromise = undefined
+  }
+
+  async resetIdentity() {
+    this.clearMemory()
+    await this.store.rotateInstallation()
+  }
+
+  async refresh({ signal } = {}) {
+    if (this.refreshPromise) return this.refreshPromise
+    this.refreshPromise = (async () => {
+      const record = await this.store.read()
+      if (!record.refreshToken) throw new CloudApiError('QuickForge Cloud is not connected.', { status: 401, code: 'cloud_not_connected' })
+      this.assertSessionService(record)
+      try {
+        const tokens = await this.client.refresh(record.refreshToken, signal)
+        if (!tokens?.refreshToken) throw new CloudApiError('QuickForge Cloud did not rotate the refresh token.', { code: 'invalid_token_response' })
+        this.setAccess(tokens)
+        await this.store.update((current) => ({
+          ...current,
+          mode: tokens.identityMode || current.mode || 'account',
+          installationId: tokens.installationId || current.installationId,
+          refreshToken: tokens.refreshToken,
+          sessionCloudUrl: this.serviceUrl,
+        }))
+        return this.accessToken
+      } catch (error) {
+        if (SESSION_INVALID_CODES.has(error?.code)) {
+          await this.clearInvalidSession({ rotateInstallationBeforeRegistration: true })
+        }
+        throw error
+      }
+    })().finally(() => { this.refreshPromise = undefined })
+    return this.refreshPromise
+  }
+
+  async access({ signal, forceRefresh = false } = {}) {
+    if (!forceRefresh && this.accessToken && this.accessExpiresAt > Date.now() + 30_000) return this.accessToken
+    return this.refresh({ signal })
+  }
+
+  async withAccessToken(operation, { signal } = {}) {
+    let token = await this.access({ signal })
+    try {
+      return await operation(token)
+    } catch (error) {
+      if (!(error instanceof CloudApiError) || error.status !== 401) throw error
+      token = await this.access({ signal, forceRefresh: true })
+      return operation(token)
+    }
+  }
+
+  async getStatusWithRemoteSummary(signal) {
+    const local = await this.status()
+    if (!local.hasSession) return local
+    try {
+      const [remoteAccount, usage] = await Promise.all([this.me(signal), this.usage(signal)])
+      const account = publicAccountSummary(remoteAccount)
+      await this.store.update((record) => ({ ...record, account }))
+      return { ...(await this.status()), account, usage, cloudAvailable: true }
+    } catch (error) {
+      return { ...local, cloudAvailable: false, cloudError: error?.code || 'cloud_unavailable' }
+    }
+  }
+
+  me(signal) { return this.withAccessToken((token) => this.client.me(token, signal), { signal }) }
+  usage(signal) { return this.withAccessToken((token) => this.client.usage(token, signal), { signal }) }
+  installations(signal) { return this.withAccessToken((token) => this.client.installations(token, signal), { signal }) }
+  revokeInstallation(id, signal) {
+    return this.withAccessToken((token) => this.client.revokeInstallation(token, id, signal), { signal })
+  }
+  async logout({ signal } = {}) {
+    const record = await this.store.read()
+    if (!record.refreshToken || !record.installationId) {
+      await this.clearInvalidSession()
+      return
+    }
+    this.assertSessionService(record)
+    await this.revokeInstallation(record.installationId, signal)
+    this.clearMemory()
+    await this.store.clearSession({ rotateInstallationBeforeRegistration: true })
+  }
+  async models(signal, { refresh = false, allowStale = true } = {}) {
+    const age = Date.now() - this.modelsCachedAt
+    if (!refresh && this.modelsCache && age < MODEL_CACHE_TTL_MS) return this.modelsCache
+    if (this.modelsPromise) return this.modelsPromise
+    this.modelsPromise = this.withAccessToken((token) => this.client.models(token, signal), { signal })
+      .then((response) => {
+        this.modelsCache = Array.isArray(response?.data) ? response.data : (Array.isArray(response?.items) ? response.items : [])
+        this.modelsCachedAt = Date.now()
+        return this.modelsCache
+      })
+      .catch((error) => {
+        if (allowStale && this.modelsCache && age < MODEL_CACHE_HARD_TTL_MS) return this.modelsCache
+        throw error
+      })
+      .finally(() => { this.modelsPromise = undefined })
+    return this.modelsPromise
+  }
+  chat(payload, idempotencyKey, signal) {
+    return this.withAccessToken((token) => this.client.chat(token, payload, idempotencyKey, signal), { signal })
+  }
+}

package/server/cloud/index.mjs

@@ -0,0 +1,7 @@
+export { readCloudConfig, parseCloudBaseUrl, cloudEndpoint } from './config.mjs'
+export { readCloudServiceConfig, saveCloudServiceConfig, publicCloudServiceConfig, DEFAULT_CLOUD_URL } from './service-config.mjs'
+export { CloudClient, CloudApiError } from './client.mjs'
+export { createCloudCredentialStore, publicCloudCredentialRecord } from './credential-store.mjs'
+export { CloudIdentityManager } from './identity.mjs'
+export { ManagedCloudModels, isManagedCloudModel, toPublicCloudModel, QUICKFORGE_CLOUD_PROVIDER } from './models.mjs'
+export { createCloudRuntime, getCloudRuntime, invalidateCloudRuntime, resolveManagedCloudProvider } from './runtime.mjs'

package/server/cloud/models.mjs

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto'
+
+const CLOUD_PROVIDER = 'quickforge-cloud'
+const CLOUD_SOURCE = 'cloud'
+
+export function toPublicCloudModel(model) {
+  const id = String(model?.id || '').trim()
+  if (!id) throw new Error('Cloud model is missing an id.')
+  const capabilities = model.capabilities || {}
+  return {
+    id,
+    name: String(model.name || id),
+    provider: CLOUD_PROVIDER,
+    api: 'openai-completions',
+    baseUrl: `quickforge://cloud/${encodeURIComponent(id)}`,
+    reasoning: Boolean(capabilities.reasoning),
+    input: capabilities.vision ? ['text', 'image'] : ['text'],
+    contextWindow: Number(model.contextWindow || 128_000),
+    maxTokens: Number(model.maxTokens || 32_768),
+    quickforgeModelSource: CLOUD_SOURCE,
+    quickforgeCatalogId: id,
+    quickforgeCapabilities: {
+      tools: Boolean(capabilities.tools),
+      vision: Boolean(capabilities.vision),
+      reasoning: Boolean(capabilities.reasoning),
+    },
+  }
+}
+
+export function isManagedCloudModel(model) {
+  return model?.provider === CLOUD_PROVIDER && model?.quickforgeModelSource === CLOUD_SOURCE && typeof model?.quickforgeCatalogId === 'string'
+}
+
+export class ManagedCloudModels {
+  constructor({ identity } = {}) {
+    if (!identity) throw new Error('ManagedCloudModels requires an identity manager.')
+    this.identity = identity
+  }
+
+  async list(signal, options) {
+    return (await this.identity.models(signal, options))
+      .filter((model) => model?.available !== false)
+      .map(toPublicCloudModel)
+  }
+
+  async resolve(model, signal) {
+    if (!isManagedCloudModel(model)) return undefined
+    const catalogId = model.quickforgeCatalogId
+    let available = await this.identity.models(signal)
+    let entry = available.find((item) => item?.id === catalogId && item?.available !== false)
+    if (!entry) {
+      available = await this.identity.models(signal, { refresh: true, allowStale: false })
+      entry = available.find((item) => item?.id === catalogId && item?.available !== false)
+    }
+    if (!entry) {
+      const error = new Error(`QuickForge Cloud model is unavailable: ${catalogId}`)
+      error.code = 'cloud_model_unavailable'
+      throw error
+    }
+    return {
+      publicModel: toPublicCloudModel(entry),
+      catalogId,
+    }
+  }
+
+  async chat(model, payload, signal) {
+    const resolved = await this.resolve(model, signal)
+    if (!resolved) throw new Error('Model is not managed by QuickForge Cloud.')
+    const request = {
+      ...payload,
+      model: resolved.catalogId,
+    }
+    delete request.baseUrl
+    delete request.headers
+    delete request.apiKey
+    return this.identity.chat(request, randomUUID(), signal)
+  }
+}
+
+export const QUICKFORGE_CLOUD_PROVIDER = CLOUD_PROVIDER