@forgeax-extension/character-3d 0.1.2

package/server/credentials-store.ts

@@ -0,0 +1,186 @@
+// Plugin-self-managed provider credentials store.
+//
+// Plugin-local .env holds only the master real/mock switch and optional COS
+// fallback keys. Transfer uploads prefer LiteLLM /v1/assets (Studio key).
+// Meshy personal keys (GEN3D_MESHY_DIRECT / MESHY_API_KEY) are env-only for
+// local recording — never written here.
+//
+// Writes go to the plugin-local .env (gitignored) AND are live-applied to
+// process.env so server/env.ts read() — which reads process.env — picks them up
+// immediately, no server restart (mirrors the host's PUT /api/settings/env
+// live-apply). parseEnv/serializeEnv/maskKey are ported verbatim from
+// packages/server/src/api/settings.ts so the masked-render and comment-preserving
+// contracts match the rest of Studio.
+//
+// SECURITY: nothing here logs, and no thrown error ever carries a plaintext key
+// value — only field names / file paths.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pickLitellmFromEnv } from './env';
+
+// Whitelist of keys this store is allowed to read/write. LiteLLM keys are
+// excluded — they live in Studio global .env only.
+export const CRED_KEYS = [
+  'GEN3D_ENABLE_REAL_PROVIDERS',
+  'COS_SECRET_ID',
+  'COS_SECRET_KEY',
+  'COS_BUCKET',
+  'COS_REGION',
+] as const;
+
+export const SECRET_KEYS = ['COS_SECRET_ID', 'COS_SECRET_KEY'] as const;
+
+export interface CredentialsState {
+  ok: true;
+  realProvidersEnabled: boolean;
+  /** Read-only: derived from Studio global .env, never from plugin .env. */
+  litellmConfigured: boolean;
+  /** Masked gateway key from Studio settings, or null when unset. Read-only. */
+  litellmProxyKey: string | null;
+  credentials: {
+    COS_SECRET_ID: string | null; // masked or null
+    COS_SECRET_KEY: string | null; // masked or null
+    COS_BUCKET: string | null; // PLAINTEXT or null
+    COS_REGION: string | null; // PLAINTEXT or null
+  };
+}
+
+/**
+ * Mask a secret for safe rendering. Ported verbatim from settings.ts: undefined
+ * / empty → null; len ≤ 8 → '***'; otherwise first-4 + ellipsis + last-4 so the
+ * user can recognise which key is set without exposing enough to steal it. The
+ * UI parses these strings literally, so the shape is a contract (unit-tested).
+ */
+export function maskKey(v?: string): string | null {
+  if (!v) return null;
+  if (v.length <= 8) return '***';
+  return `${v.slice(0, 4)}...${v.slice(-4)}`;
+}
+
+// Minimal .env parser — ported from settings.ts. Recognizes UPPER_SNAKE keys,
+// strips matched surrounding quotes; ignores comments / blank / unknown lines.
+function parseEnv(raw: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of raw.split('\n')) {
+    const m = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!m) continue;
+    let value = m[2];
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[m[1]] = value;
+  }
+  return out;
+}
+
+// Serialize — ported from settings.ts. Preserves comments / unknown lines from
+// the original, updates recognized keys in place, appends new keys at the end.
+function serializeEnv(env: Record<string, string>, original?: string): string {
+  const seen = new Set<string>();
+  const lines: string[] = [];
+  if (original) {
+    for (const line of original.split('\n')) {
+      const m = /^\s*([A-Z_][A-Z0-9_]*)\s*=/.exec(line);
+      if (m && env[m[1]] !== undefined) {
+        lines.push(`${m[1]}=${env[m[1]]}`);
+        seen.add(m[1]);
+      } else {
+        lines.push(line);
+      }
+    }
+  }
+  for (const [k, v] of Object.entries(env)) {
+    if (!seen.has(k)) lines.push(`${k}=${v}`);
+  }
+  return lines.join('\n');
+}
+
+// Plugin-local .env path — IDENTICAL resolution to server/env.ts
+// loadPluginEnvOnce so both touch the same file (server/ → '..' → plugin root).
+export function defaultEnvPath(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '.env');
+}
+
+// Resolve one key's effective value the same way env.ts does: process.env wins
+// over the file (the server's env always wins), and an empty / whitespace value
+// reads as "not set". Returns the trimmed value or undefined.
+function effective(name: string, fileEnv: Record<string, string>): string | undefined {
+  const raw = name in process.env ? process.env[name] : fileEnv[name];
+  return raw && raw.trim() ? raw.trim() : undefined;
+}
+
+function readLitellmStatus(): { configured: boolean; maskedKey: string | null } {
+  const litellm = pickLitellmFromEnv(process.env);
+  return {
+    configured: litellm !== null,
+    maskedKey: litellm ? maskKey(litellm.apiKey) : null,
+  };
+}
+
+/**
+ * Read the masked credential state. Plugin .env holds COS + master switch only;
+ * LiteLLM status is read-only from Studio global .env. Never returns a plaintext key.
+ */
+export function readCredentials(envPath: string = defaultEnvPath()): CredentialsState {
+  let fileEnv: Record<string, string> = {};
+  if (existsSync(envPath)) {
+    try {
+      fileEnv = parseEnv(readFileSync(envPath, 'utf8'));
+    } catch {
+      fileEnv = {};
+    }
+  }
+  const litellm = readLitellmStatus();
+  return {
+    ok: true,
+    realProvidersEnabled: effective('GEN3D_ENABLE_REAL_PROVIDERS', fileEnv) === '1',
+    litellmConfigured: litellm.configured,
+    litellmProxyKey: litellm.maskedKey,
+    credentials: {
+      COS_SECRET_ID: maskKey(effective('COS_SECRET_ID', fileEnv)),
+      COS_SECRET_KEY: maskKey(effective('COS_SECRET_KEY', fileEnv)),
+      COS_BUCKET: effective('COS_BUCKET', fileEnv) ?? null,
+      COS_REGION: effective('COS_REGION', fileEnv) ?? null,
+    },
+  };
+}
+
+/**
+ * Write a credential patch to the plugin-local .env and live-apply to
+ * process.env. LiteLLM keys in the patch are silently dropped (managed in
+ * Studio Settings only).
+ */
+export function writeCredentials(
+  patch: Record<string, unknown> = {},
+  envPath: string = defaultEnvPath(),
+): CredentialsState {
+  const clean: Record<string, string> = {};
+  for (const [k, v] of Object.entries(patch ?? {})) {
+    if (!(CRED_KEYS as readonly string[]).includes(k)) continue;
+    if (typeof v !== 'string' && typeof v !== 'number') continue;
+    clean[k] = String(v);
+  }
+
+  if (Object.keys(clean).length > 0) {
+    let originalText = '';
+    let env: Record<string, string> = {};
+    if (existsSync(envPath)) {
+      originalText = readFileSync(envPath, 'utf8');
+      env = parseEnv(originalText);
+    }
+    for (const [k, v] of Object.entries(clean)) env[k] = v;
+
+    const tmp = `${envPath}.tmp`;
+    writeFileSync(tmp, serializeEnv(env, originalText), 'utf8');
+    renameSync(tmp, envPath);
+
+    for (const [k, v] of Object.entries(clean)) {
+      if (v === '') delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+
+  return readCredentials(envPath);
+}

package/server/engine-import.ts

@@ -0,0 +1,238 @@
+// Manual "Import to Game" for gen3d props/mesh assets (PLAN §5.3 / ROLE1).
+// Character assets are explicitly rejected here — they use the (separate,
+// not-yet-built) playable-character export pipeline, never this simple path.
+import { createHash } from 'node:crypto';
+import { access, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import {
+  cookExternalAssetMeta,
+  normalizeGlbForEngine,
+  type ExternalAssetMeta,
+} from '@forgeax-extension/external-asset-meta';
+import type { AssetSidecar } from '../shared/manifest';
+import type { PerGameAssetStore } from './per-game-store';
+
+export interface EngineImportStatus {
+  ok: true;
+  imported: boolean;
+  needsManualImport: boolean;
+  needsDracoNormalize: boolean;
+  engineMetaPath: string | null;
+  sourceHash: string | null;
+  importedAt: string | null;
+  message: string;
+  retryable: boolean;
+}
+
+export type EngineImportResult =
+  | {
+      ok: true;
+      firstImport: boolean;
+      normalizedDraco: boolean;
+      reusedGuidCount: number;
+      engineMetaPath: string;
+      assetPath: string;
+      message: string;
+    }
+  | {
+      ok: false;
+      code: string;
+      message: string;
+      retryable: boolean;
+    };
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function countReused(existing: ExternalAssetMeta | null, next: ExternalAssetMeta): number {
+  if (!existing) return 0;
+  const prev = new Set(existing.subAssets.map((s) => `${s.kind}\0${s.sourceIndex}\0${s.guid}`));
+  let n = 0;
+  for (const s of next.subAssets) {
+    if (prev.has(`${s.kind}\0${s.sourceIndex}\0${s.guid}`)) n += 1;
+  }
+  return n;
+}
+
+export async function engineImportStatus(
+  store: PerGameAssetStore,
+  slug: string,
+  assetPath: string,
+): Promise<EngineImportStatus> {
+  const resolved = store.resolveAssetFiles(slug, assetPath);
+  if (!resolved) {
+    return {
+      ok: true, imported: false, needsManualImport: true, needsDracoNormalize: false,
+      engineMetaPath: null, sourceHash: null, importedAt: null,
+      message: 'Asset not found.', retryable: false,
+    };
+  }
+  if (resolved.slot === 'characters') {
+    return {
+      ok: true, imported: false, needsManualImport: false, needsDracoNormalize: false,
+      engineMetaPath: null, sourceHash: null, importedAt: null,
+      message: 'Character assets use Export Playable Character, not Import to Game.',
+      retryable: false,
+    };
+  }
+  const { glbAbs, metaAbs, sidecarAbs } = resolved;
+  if (!(await exists(glbAbs))) {
+    return {
+      ok: true, imported: false, needsManualImport: true, needsDracoNormalize: false,
+      engineMetaPath: null, sourceHash: null, importedAt: null,
+      message: 'GLB missing on disk.', retryable: false,
+    };
+  }
+  const glbBytes = new Uint8Array(await readFile(glbAbs));
+  const currentHash = `sha256:${sha256Hex(glbBytes)}`;
+  const hasMeta = await exists(metaAbs);
+  let sidecar: AssetSidecar | null = null;
+  if (await exists(sidecarAbs)) {
+    try {
+      sidecar = JSON.parse(await readFile(sidecarAbs, 'utf8')) as AssetSidecar;
+    } catch {
+      sidecar = null;
+    }
+  }
+  const engineImport = (sidecar?.custom as { engineImport?: { importedAt?: string; sourceHash?: string } } | undefined)
+    ?.engineImport;
+  const importedAt = engineImport?.importedAt ?? null;
+  const recordedHash = engineImport?.sourceHash ?? null;
+
+  if (hasMeta && recordedHash === currentHash) {
+    return {
+      ok: true, imported: true, needsManualImport: false, needsDracoNormalize: false,
+      engineMetaPath: metaAbs, sourceHash: currentHash, importedAt,
+      message: 'Already imported to game (engine meta matches current GLB).', retryable: false,
+    };
+  }
+
+  const probe = await cookExternalAssetMeta(glbBytes, currentHash, assetPath.split('/').pop()!);
+  const needsDraco =
+    !probe.ok &&
+    probe.code === 'engine_unsupported_extension' &&
+    (probe.unsupportedExtensions ?? []).includes('KHR_draco_mesh_compression');
+
+  return {
+    ok: true, imported: false, needsManualImport: true, needsDracoNormalize: needsDraco,
+    engineMetaPath: hasMeta ? metaAbs : null, sourceHash: currentHash, importedAt,
+    message: needsDraco
+      ? 'Model generated; Import to Game needs manual confirm (includes format conversion).'
+      : hasMeta
+        ? 'Engine meta is stale or mismatched; re-import required.'
+        : 'Not imported yet. Click Import to Game.',
+    retryable: true,
+  };
+}
+
+export async function importToEngine(
+  store: PerGameAssetStore,
+  slug: string,
+  assetPath: string,
+): Promise<EngineImportResult> {
+  const resolved = store.resolveAssetFiles(slug, assetPath);
+  if (!resolved) {
+    return { ok: false, code: 'asset_not_found', message: 'Asset not found.', retryable: false };
+  }
+  if (resolved.slot === 'characters') {
+    return {
+      ok: false,
+      code: 'character_not_supported',
+      message: 'Character assets use Export Playable Character, not Import to Game.',
+      retryable: false,
+    };
+  }
+  const { glbAbs, metaAbs, sidecarAbs, glbFileName } = resolved;
+  if (!(await exists(glbAbs))) {
+    return { ok: false, code: 'asset_not_found', message: 'GLB missing on disk.', retryable: false };
+  }
+
+  const originalGlb = new Uint8Array(await readFile(glbAbs));
+  let glbBytes: Uint8Array = originalGlb;
+  let contentHash = `sha256:${sha256Hex(glbBytes)}`;
+  let normalizedDraco = false;
+
+  let existingMeta: ExternalAssetMeta | null = null;
+  if (await exists(metaAbs)) {
+    try {
+      existingMeta = JSON.parse(await readFile(metaAbs, 'utf8')) as ExternalAssetMeta;
+      if (existingMeta.kind !== 'external-asset-package') existingMeta = null;
+    } catch {
+      existingMeta = null;
+    }
+  }
+  const firstImport = existingMeta === null;
+
+  let cooked = await cookExternalAssetMeta(glbBytes, contentHash, glbFileName, { existingMeta });
+
+  if (
+    !cooked.ok &&
+    cooked.code === 'engine_unsupported_extension' &&
+    (cooked.unsupportedExtensions ?? []).includes('KHR_draco_mesh_compression')
+  ) {
+    const normalized = await normalizeGlbForEngine(glbBytes);
+    if (!normalized.ok) {
+      return { ok: false, code: normalized.code, message: `Draco normalize failed: ${normalized.message}`, retryable: true };
+    }
+    glbBytes = normalized.bytes;
+    contentHash = `sha256:${sha256Hex(glbBytes)}`;
+    cooked = await cookExternalAssetMeta(glbBytes, contentHash, glbFileName, { existingMeta });
+    if (!cooked.ok) {
+      return { ok: false, code: cooked.code, message: cooked.message, retryable: true };
+    }
+    normalizedDraco = true;
+  } else if (!cooked.ok) {
+    return { ok: false, code: cooked.code, message: cooked.message, retryable: true };
+  }
+
+  const tmpGlb = `${glbAbs}.__import_tmp`;
+  const tmpMeta = `${metaAbs}.__import_tmp`;
+  try {
+    if (normalizedDraco) await writeFile(tmpGlb, glbBytes);
+    await writeFile(tmpMeta, `${JSON.stringify(cooked.meta, null, 2)}\n`, 'utf8');
+    if (normalizedDraco) await rename(tmpGlb, glbAbs);
+    await rename(tmpMeta, metaAbs);
+  } catch (err) {
+    await rm(tmpGlb, { force: true }).catch(() => undefined);
+    await rm(tmpMeta, { force: true }).catch(() => undefined);
+    return {
+      ok: false, code: 'write_failed',
+      message: err instanceof Error ? err.message : 'Failed to write import artifacts',
+      retryable: true,
+    };
+  }
+
+  if (await exists(sidecarAbs)) {
+    try {
+      const sidecar = JSON.parse(await readFile(sidecarAbs, 'utf8')) as AssetSidecar;
+      sidecar.contentHash = contentHash;
+      sidecar.size = glbBytes.byteLength;
+      (sidecar.custom as Record<string, unknown>).engineImport = {
+        sourceHash: contentHash,
+        importedAt: new Date().toISOString(),
+      };
+      await writeFile(sidecarAbs, `${JSON.stringify(sidecar, null, 2)}\n`, 'utf8');
+    } catch {
+      // Non-fatal: engine meta already written.
+    }
+  }
+
+  return {
+    ok: true,
+    firstImport,
+    normalizedDraco,
+    reusedGuidCount: countReused(existingMeta, cooked.meta),
+    engineMetaPath: metaAbs,
+    assetPath,
+    message: 'Imported to game Edit asset catalog. This does not auto-replace the game protagonist or modify gameplay code.',
+  };
+}