@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.4

package/src/paths.ts

@@ -6,9 +6,10 @@
  * @module dsh-vision-toolkit/paths
  */
 
-import { randomUUID } from 'node:crypto'
-import { cp, link, lstat, mkdir, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
-import { extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import type { Stats } from 'node:fs'
+import { cp, link, lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { VisionToolkitError } from './errors.ts'
 
@@ -23,10 +24,22 @@ export interface PathPolicy {
   tempDir: string
   /** Real allowed roots: workspace, platform temp, and configured directories. */
   allowedDirs: string[]
+  /** Real plugin-managed root containing artifacts and transient files. */
+  storageRoot: string
   /** Real plugin-managed output directory inside the fence. */
   outputDir: string
 }
 
+/** Resolved plugin storage for one workspace. */
+export interface WorkspaceStorage {
+  /** Real workspace root. */
+  workspace: string
+  /** Real plugin-managed root for this workspace. */
+  root: string
+  /** Absolute user-visible spelling of the same managed root. */
+  visibleRoot: string
+}
+
 /** Whether `child` equals or lies under `parent` on the same path root. */
 export function isWithin(parent: string, child: string): boolean {
   const rel = relative(parent, child)
@@ -65,26 +78,231 @@ export function normalizePlatformTempPath(
   return win32.join(tempDirectory, raw.slice('/tmp/'.length))
 }
 
+/** Stable opaque per-user workspace id used below a shared storage root. */
+export function workspaceStorageId(
+  workspace: string,
+  userIdentity: string = typeof process.geteuid === 'function'
+    ? `uid:${process.geteuid()}`
+    : `home:${homedir()}`,
+): string {
+  return createHash('sha256')
+    .update(userIdentity)
+    .update('\0')
+    .update(workspace)
+    .digest('hex')
+    .slice(0, 20)
+}
+
+function currentPosixUid(): number {
+  if (typeof process.geteuid !== 'function') {
+    throw new VisionToolkitError(
+      'path',
+      'configured storage directory is not supported on this platform because ownership and permissions cannot be verified',
+    )
+  }
+  return process.geteuid()
+}
+
+export function assertSecureWorkspaceStorage(info: Stats, requested: string): void {
+  const currentUid = currentPosixUid()
+  if (info.uid !== currentUid || (info.mode & 0o777) !== 0o700) {
+    throw new VisionToolkitError('path', `workspace storage directory must be owned by the current user with mode 0700: ${requested}`)
+  }
+}
+
+/** Resolve a shared base and prove every POSIX ancestor is protected from replacement. */
+export async function assertSecureSharedStorageBase(requested: string): Promise<string> {
+  const currentUid = currentPosixUid()
+  const requestedPath = resolve(requested)
+  const requestedChain: string[] = []
+  let requestedCurrent = requestedPath
+  while (true) {
+    requestedChain.push(requestedCurrent)
+    const parent = dirname(requestedCurrent)
+    if (parent === requestedCurrent) break
+    requestedCurrent = parent
+  }
+  for (const component of requestedChain.reverse()) {
+    const info = await lstat(component)
+    if (info.isSymbolicLink()) {
+      if (info.uid !== 0) {
+        throw new VisionToolkitError('path', `configured storage directory contains an untrusted symbolic link: ${component}`)
+      }
+      continue
+    }
+    if (!info.isDirectory()) {
+      throw new VisionToolkitError('path', `configured storage path component is not a directory: ${component}`)
+    }
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${component}`)
+  }
+  const canonical = await realpath(requestedPath)
+  let current = canonical
+  while (true) {
+    const info = await lstat(current)
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      info.isSymbolicLink()
+      || !info.isDirectory()
+      || (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${current}`)
+    const parent = dirname(current)
+    if (parent === current) return canonical
+    current = parent
+  }
+}
+
+function requestedSharedStorageBase(storageDirRaw: string): string {
+  currentPosixUid()
+  const configured = normalizePlatformTempPath(expandUserHome(storageDirRaw.trim()))
+  if (!isAbsolute(configured)) {
+    throw new VisionToolkitError('path', `configured storage directory must be an absolute path: ${storageDirRaw}`)
+  }
+  return resolve(configured)
+}
+
+async function ensureSharedStorageBase(storageDirRaw: string): Promise<{ requestedBase: string; base: string }> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  try {
+    await mkdir(requestedBase, { recursive: true, mode: 0o700 })
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not writable: ${requestedBase}`, { cause: error })
+  }
+  try {
+    return { requestedBase, base: await assertSecureSharedStorageBase(requestedBase) }
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not accessible: ${requestedBase}`, { cause: error })
+  }
+}
+
+/** Validate and write-probe a configured shared root before Settings activation. */
+export async function preflightSharedStorageBase(storageDirRaw: string): Promise<string> {
+  const { base } = await ensureSharedStorageBase(storageDirRaw)
+  let probe: string | undefined
+  let failure: unknown
+  try {
+    probe = await mkdtemp(join(base, '.dsh-vision-toolkit-preflight-'))
+    assertSecureWorkspaceStorage(await lstat(probe), probe)
+  } catch (error) {
+    failure = error
+  }
+  if (probe !== undefined) {
+    try {
+      await rm(probe, { recursive: true, force: true })
+    } catch (error) {
+      failure ??= error
+    }
+  }
+  if (failure !== undefined) {
+    throw new VisionToolkitError('path', `configured storage directory failed its write preflight: ${base}`, { cause: failure })
+  }
+  return base
+}
+
+async function managedDirectory(
+  parent: string,
+  requested: string,
+  label: string,
+  secureWorkspaceStorage = false,
+): Promise<string> {
+  try {
+    await mkdir(requested, { mode: 0o700 })
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) {
+      throw new VisionToolkitError('path', `${label} is not writable: ${requested}`, { cause: error })
+    }
+  }
+  let info
+  try {
+    info = await lstat(requested)
+  } catch (error) {
+    throw new VisionToolkitError('path', `${label} is not accessible: ${requested}`, { cause: error })
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `${label} must be a real directory: ${requested}`)
+  }
+  if (secureWorkspaceStorage) assertSecureWorkspaceStorage(info, requested)
+  const canonical = await realpath(requested)
+  if (!isWithin(parent, canonical)) {
+    throw new VisionToolkitError('path', `${label} escaped its configured root: ${requested}`)
+  }
+  return canonical
+}
+
+/**
+ * Resolve the plugin-managed root for one workspace. Blank configuration keeps
+ * the legacy workspace-local `.dsh-vision-toolkit` directory. A configured
+ * shared root receives one stable, automatically generated workspace child.
+ */
+export async function resolveWorkspaceStorage(
+  workspaceRaw: string,
+  storageDirRaw?: string,
+): Promise<WorkspaceStorage> {
+  const expandedWorkspace = expandUserHome(workspaceRaw)
+  const visibleWorkspace = resolve(expandedWorkspace)
+  let workspace: string
+  try {
+    workspace = await realpath(visibleWorkspace)
+  } catch (error) {
+    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
+  }
+
+  if (storageDirRaw === undefined || storageDirRaw.trim().length === 0) {
+    const visibleRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
+    const root = await managedDirectory(workspace, visibleRoot, 'plugin storage directory')
+    return { workspace, root, visibleRoot }
+  }
+
+  const { requestedBase, base } = await ensureSharedStorageBase(storageDirRaw)
+  const id = workspaceStorageId(workspace)
+  const visibleRoot = join(requestedBase, id)
+  const root = await managedDirectory(base, join(base, id), 'workspace storage directory', true)
+  return { workspace, root, visibleRoot }
+}
+
+async function resolveReadableWorkspaceStorageRoot(
+  workspace: string,
+  storageDirRaw: string,
+): Promise<string> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  const base = await assertSecureSharedStorageBase(requestedBase)
+  const requestedRoot = join(base, workspaceStorageId(workspace))
+  const info = await lstat(requestedRoot)
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `historical workspace storage must be a real directory: ${requestedRoot}`)
+  }
+  assertSecureWorkspaceStorage(info, requestedRoot)
+  const root = await realpath(requestedRoot)
+  if (!isWithin(base, root)) {
+    throw new VisionToolkitError('path', `historical workspace storage escaped its configured root: ${requestedRoot}`)
+  }
+  return root
+}
+
 /**
- * Build the per-invocation path policy: realpath the workspace, resolve and
- * realpath the platform temp directory and allowed directories, and create
- * the output directory inside the fence.
+ * Build the per-invocation path policy: resolve workspace storage, realpath the
+ * platform temp directory and allowed directories, and create the artifact
+ * directory inside the managed root.
  * @param workspaceRaw - session workspace (or process cwd fallback).
  * @param allowedDirs - configured extra allowed roots.
- * @param outputDirRaw - configured output directory (default `.dsh-vision-toolkit/artifacts`).
+ * @param storageDirRaw - optional shared storage root.
+ * @param readableStorageDirs - previously validated shared roots retained for persisted input paths.
  * @returns the resolved policy.
  */
 export async function createPathPolicy(
   workspaceRaw: string,
   allowedDirs: readonly string[],
-  outputDirRaw?: string,
+  storageDirRaw?: string,
+  readableStorageDirs: readonly string[] = [],
 ): Promise<PathPolicy> {
-  let workspace: string
-  try {
-    workspace = await realpath(expandUserHome(workspaceRaw))
-  } catch (error) {
-    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
-  }
+  const storage = await resolveWorkspaceStorage(workspaceRaw, storageDirRaw)
+  const { workspace } = storage
   let tempDir: string
   const tempDirectoryRaw = platformTempDirectory()
   try {
@@ -92,7 +310,16 @@ export async function createPathPolicy(
   } catch (error) {
     throw new VisionToolkitError('path', `platform temporary directory is not accessible: ${tempDirectoryRaw}`, { cause: error })
   }
-  const roots = [workspace, tempDir]
+  const roots = [workspace, tempDir, storage.root]
+  for (const raw of readableStorageDirs) {
+    if (raw === storageDirRaw) continue
+    try {
+      roots.push(await resolveReadableWorkspaceStorageRoot(workspace, raw))
+    } catch {
+      // Historical roots are read-only compatibility fences. Missing or newly
+      // unsafe roots stay unauthorized without breaking the active runtime.
+    }
+  }
   for (const raw of allowedDirs) {
     const candidate = expandUserHome(raw)
     const target = isAbsolute(candidate) ? candidate : resolve(workspace, candidate)
@@ -102,20 +329,14 @@ export async function createPathPolicy(
       throw new VisionToolkitError('path', `allowedDirs entry is not accessible: ${raw}`, { cause: error })
     }
   }
-  const outputRaw = outputDirRaw === undefined || outputDirRaw.trim().length === 0
-    ? join(workspace, '.dsh-vision-toolkit', 'artifacts')
-    : resolve(workspace, expandUserHome(outputDirRaw))
-  if (!roots.some(root => isWithin(root, outputRaw))) {
-    throw new VisionToolkitError('path', 'output directory must stay inside the workspace or an allowedDirs entry')
-  }
-  let outputDir: string
-  try {
-    await mkdir(outputRaw, { recursive: true })
-    outputDir = await realpath(outputRaw)
-  } catch (error) {
-    throw new VisionToolkitError('path', `output directory is not writable: ${outputRaw}`, { cause: error })
+  const outputDir = await managedDirectory(storage.root, join(storage.root, 'artifacts'), 'artifact directory')
+  return {
+    workspace,
+    tempDir,
+    allowedDirs: [...new Set(roots)],
+    storageRoot: storage.root,
+    outputDir,
   }
-  return { workspace, tempDir, allowedDirs: [...new Set(roots)], outputDir }
 }
 
 /**

package/src/runtime-manager.ts

@@ -7,6 +7,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { resolveConfig, type ResolvedVisionToolkitConfig, type VisionToolkitConfig } from './config.ts'
+import { preflightSharedStorageBase } from './paths.ts'
 import { VisionToolkitRuntime } from './runtime.ts'
 import { UpstreamAdapter, type UpstreamVersionInfo } from './upstream.ts'
 
@@ -26,16 +27,30 @@ export interface RuntimeManagerStatus {
   lastError?: string
 }
 
+/** Storage selection paired to the active or validated startup generation. */
+export interface RuntimeStorageGeneration {
+  generation: number
+  storageDir?: string
+}
+
 /** Test seam for preparing one generation. */
 export type RuntimeGenerationFactory = (
   ctx: Context,
   config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
 ) => Promise<VisionToolkitRuntime>
 
-async function defaultFactory(ctx: Context, config: ResolvedVisionToolkitConfig): Promise<VisionToolkitRuntime> {
+/** Async commit prerequisite run after preparation and before a generation becomes active. */
+export type RuntimeGenerationBeforePublish = (candidate: PreparedRuntimeGeneration) => Promise<void>
+
+async function defaultFactory(
+  ctx: Context,
+  config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
+): Promise<VisionToolkitRuntime> {
   const adapter = new UpstreamAdapter(ctx, config)
   await adapter.prepare()
-  return new VisionToolkitRuntime(ctx, config, adapter)
+  return new VisionToolkitRuntime(ctx, config, adapter, readableStorageDirs)
 }
 
 function fingerprint(config: ResolvedVisionToolkitConfig): string {
@@ -57,6 +72,8 @@ export class VisionToolkitRuntimeManager {
   private generation = 0
   private reconfigureTicket = 0
   private lastError: string | undefined
+  private validatedStartupStorageDir: string | null | undefined
+  private readonly readableStorageDirs = new Set<string>()
 
   constructor(
     private readonly ctx: Context,
@@ -69,22 +86,69 @@ export class VisionToolkitRuntimeManager {
     return this.active.runtime
   }
 
+  /** Configuration belonging to the currently serving runtime generation. */
+  currentConfig(): ResolvedVisionToolkitConfig {
+    if (this.active === undefined) throw new Error('dsh-vision-toolkit runtime is not ready')
+    return this.active.config
+  }
+
   /** Whether at least one generation is available. */
   get ready(): boolean {
     return this.active !== undefined
   }
 
-  /** Resolve and fully prepare a candidate without changing the active runtime. */
-  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
-    const config = resolveConfig(raw)
+  /** Storage config safe for paste writes even when initial runtime preparation failed. */
+  storageGeneration(): RuntimeStorageGeneration {
+    if (this.active !== undefined) {
+      return {
+        generation: this.generation,
+        ...(this.active.config.storageDir === undefined ? {} : { storageDir: this.active.config.storageDir }),
+      }
+    }
+    if (this.validatedStartupStorageDir === undefined) {
+      throw new Error('dsh-vision-toolkit storage configuration is not ready')
+    }
+    return {
+      generation: this.generation,
+      ...(this.validatedStartupStorageDir === null ? {} : { storageDir: this.validatedStartupStorageDir }),
+    }
+  }
+
+  /** Validated storage for best-effort consumers; undefined when startup preflight failed. */
+  validatedStorageDirectory(): string | undefined {
+    if (this.active !== undefined) return this.active.config.storageDir
+    return this.validatedStartupStorageDir ?? undefined
+  }
+
+  private async prepareResolvedCandidate(config: ResolvedVisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
     const resolvedFingerprint = fingerprint(config)
     if (this.active?.fingerprint === resolvedFingerprint) {
       return { ...this.active, config }
     }
-    const runtime = await this.factory(this.ctx, config)
+    const runtime = await this.factory(
+      this.ctx,
+      config,
+      [...new Set([...this.readableStorageDirs, ...config.storageHistory])]
+        .filter(storageDir => storageDir !== config.storageDir),
+    )
     return { config, fingerprint: resolvedFingerprint, runtime }
   }
 
+  private rememberStorageDirectory(storageDir: string | undefined): void {
+    if (storageDir !== undefined) this.readableStorageDirs.add(storageDir)
+  }
+
+  private rememberStorageDirectories(storageDirs: readonly string[]): void {
+    for (const storageDir of storageDirs) this.rememberStorageDirectory(storageDir)
+  }
+
+  /** Resolve and fully prepare a candidate without changing the active runtime. */
+  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
+    const config = resolveConfig(raw)
+    if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+    return this.prepareResolvedCandidate(config)
+  }
+
   /**
    * Publish one already-prepared generation atomically.
    * @param candidate - generation returned by {@link prepareCandidate}.
@@ -97,6 +161,8 @@ export class VisionToolkitRuntimeManager {
     }
     this.reconfigureTicket += 1
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     this.generation += 1
     this.lastError = undefined
     this.ctx.logger.info(
@@ -108,10 +174,21 @@ export class VisionToolkitRuntimeManager {
     )
   }
 
-  /** Prepare and publish the initial or explicitly validated generation. */
-  async initialize(raw: VisionToolkitConfig): Promise<void> {
+  /**
+   * Prepare and publish the initial or explicitly validated generation.
+   * @param raw - untrusted Settings generation to resolve and prepare.
+   * @param beforePublish - optional durable prerequisite run after preparation.
+   */
+  async initialize(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<void> {
     try {
-      this.activateCandidate(await this.prepareCandidate(raw))
+      const config = resolveConfig(raw)
+      if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+      this.validatedStartupStorageDir = config.storageDir ?? null
+      this.rememberStorageDirectories(config.storageHistory)
+      this.rememberStorageDirectory(config.storageDir)
+      const candidate = await this.prepareResolvedCandidate(config)
+      await beforePublish?.(candidate)
+      this.activateCandidate(candidate)
     } catch (error) {
       this.lastError = messageOf(error)
       throw error
@@ -121,13 +198,17 @@ export class VisionToolkitRuntimeManager {
   /**
    * Apply an externally committed Settings generation. Concurrent edits are
    * last-write-wins; a slower obsolete prepare can never overwrite a newer one.
+   * @param raw - externally committed Settings generation.
+   * @param beforePublish - optional durable prerequisite run after preparation.
    * @returns whether this call published a new active generation.
    */
-  async reconfigure(raw: VisionToolkitConfig): Promise<boolean> {
+  async reconfigure(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<boolean> {
     const ticket = ++this.reconfigureTicket
     let candidate: PreparedRuntimeGeneration
     try {
       candidate = await this.prepareCandidate(raw)
+      if (ticket !== this.reconfigureTicket) return false
+      await beforePublish?.(candidate)
     } catch (error) {
       if (ticket === this.reconfigureTicket) this.lastError = messageOf(error)
       throw error
@@ -135,6 +216,8 @@ export class VisionToolkitRuntimeManager {
     if (ticket !== this.reconfigureTicket) return false
     const changed = this.active?.fingerprint !== candidate.fingerprint
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     if (changed) {
       this.generation += 1
       this.ctx.logger.info(