@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/src/client-http.ts

@@ -1,18 +1,92 @@
 /**
- * Browser-side HTTP helpers for the dsh-hardssh route clients.
- * Plain fetch / same-origin — bundled inline into the client bundle.
+ * Browser-side HTTP transport for the dsh-hardssh route clients — the ONE
+ * fetch / JSON-error layer shared by the workspace client (./client/api.ts)
+ * and the SSH client (./client/ssh/api.ts). Plain fetch / same-origin —
+ * bundled inline into the client bundle.
+ *
+ * Business layers may translate the error (named subclasses/aliases), but they
+ * must not re-parse a response: every route error is decoded here, once, into
+ * {@link HttpApiError} with the HTTP status AND the parsed body.
  */
 
-/** Error carrying the route's JSON error message and stable code/status. */
+/**
+ * Every route's JSON error body (superset of the SSH `ApiErrorBody`): the
+ * stable machine code plus the interactive-gate fields the UI reads.
+ */
+export interface HttpErrorBody {
+  /** Human-readable message (`error` is the wire field name). */
+  error?: string
+  /** Stable machine code (HOST_KEY_UNKNOWN / NEEDS_PASSWORD / VAULT_* / …). */
+  code?: string
+  /** Which secret a connection needs when code === 'NEEDS_PASSWORD'. */
+  secret?: 'password' | 'passphrase'
+  /** The fingerprint when a host key was refused. */
+  hostKeyFingerprint?: string
+  /** Mismatch detail (expected vs actual) when the host key changed. */
+  hostKeyMismatch?: { expected: string; actual: string }
+  /** Workspace titles referencing a host that cannot be deleted (HOST_IN_USE). */
+  workspaces?: Array<{ id: string; title: string }>
+  /** Vault lockout: attempts left before the next lockout window. */
+  remaining?: number
+  /** Vault lockout: milliseconds until the next attempt is allowed. */
+  retryAfterMs?: number
+  /** Forward-compatible: unlisted fields stay reachable through `body`. */
+  [key: string]: unknown
+}
+
+/**
+ * The single transport error: HTTP status plus the PARSED response body, so
+ * no caller re-parses a response and no field is flattened away. The SSH
+ * client re-exports it as `SshApiError`; the workspace client subclasses it as
+ * `WorkspaceApiError`. Both are this class at runtime, so the UI's
+ * `instanceof` / `.code` / `.hostKeyFingerprint` checks keep working.
+ */
 export class HttpApiError extends Error {
   constructor(
     message: string,
-    public readonly code?: string,
-    public readonly status?: number,
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number,
+    /** Parsed JSON error body, when the route sent one. */
+    readonly body?: HttpErrorBody,
   ) {
     super(message)
     this.name = 'HttpApiError'
   }
+
+  /** Stable machine code from the route error body. */
+  get code(): string | undefined {
+    return typeof this.body?.code === 'string' ? this.body.code : undefined
+  }
+
+  /** Which secret a connection needs when {@link code} === 'NEEDS_PASSWORD'. */
+  get secret(): 'password' | 'passphrase' | undefined {
+    const secret = this.body?.secret
+    return secret === 'password' || secret === 'passphrase' ? secret : undefined
+  }
+
+  /** The fingerprint when a host key was refused. */
+  get hostKeyFingerprint(): string | undefined {
+    return typeof this.body?.hostKeyFingerprint === 'string' ? this.body.hostKeyFingerprint : undefined
+  }
+
+  /** Mismatch detail (expected vs actual) when the host key changed. */
+  get hostKeyMismatch(): { expected: string; actual: string } | undefined {
+    const mismatch = this.body?.hostKeyMismatch
+    if (typeof mismatch !== 'object' || mismatch === null) return undefined
+    const { expected, actual } = mismatch as { expected?: unknown; actual?: unknown }
+    if (typeof expected !== 'string' || typeof actual !== 'string') return undefined
+    return { expected, actual }
+  }
+
+  /** Vault lockout: attempts left. */
+  get remaining(): number | undefined {
+    return typeof this.body?.remaining === 'number' ? this.body.remaining : undefined
+  }
+
+  /** Vault lockout: milliseconds until the next attempt is allowed. */
+  get retryAfterMs(): number | undefined {
+    return typeof this.body?.retryAfterMs === 'number' ? this.body.retryAfterMs : undefined
+  }
 }
 
 /** Query-string helper (skips undefined and empty values). */
@@ -25,21 +99,47 @@ export function buildQuery(params: Record<string, string | number | undefined>):
   return text === '' ? '' : '?' + text
 }
 
-/** Parse a JSON response or throw an HttpApiError (code/status preserved). */
+/** Parse a JSON response or throw {@link HttpApiError} (status + body kept). */
 export async function readJson<T>(response: Response): Promise<T> {
-  let body: unknown
+  const body = await parseJson(response)
+  if (body === undefined) {
+    throw new HttpApiError(`HTTP ${response.status}: invalid JSON response`, response.status)
+  }
+  if (!response.ok) throw errorFor(response.status, body)
+  return body as T
+}
+
+/**
+ * Throw {@link HttpApiError} for a response that does NOT carry a JSON
+ * success body (streamed upload/download): a JSON error body is still parsed
+ * and preserved, so the caller sees the route's code instead of raw text.
+ * @param response - the non-ok response (or a stream that could not start).
+ * @param fallback - message prefix used when the route sent no `error` field.
+ */
+export async function throwHttpError(response: Response, fallback: string): Promise<never> {
+  const body = await parseJson(response)
+  const object = bodyObject(body)
+  const message = typeof object?.error === 'string' ? object.error : `${fallback}: HTTP ${response.status}`
+  throw new HttpApiError(message, response.status, object)
+}
+
+/** Parse a response body as JSON; undefined when absent or not JSON. */
+async function parseJson(response: Response): Promise<unknown> {
   try {
-    body = await response.json()
+    return await response.json()
   } catch {
-    throw new HttpApiError(`HTTP ${response.status}: invalid JSON response`, undefined, response.status)
+    return undefined
   }
-  if (!response.ok) {
-    const record = typeof body === 'object' && body !== null
-      ? body as { error?: unknown; code?: unknown }
-      : undefined
-    const message = typeof record?.error === 'string' ? record.error : `HTTP ${response.status}`
-    const code = typeof record?.code === 'string' ? record.code : undefined
-    throw new HttpApiError(message, code, response.status)
-  }
-  return body as T
+}
+
+/** The parsed body as an error-body record, or undefined for non-objects. */
+function bodyObject(body: unknown): HttpErrorBody | undefined {
+  return typeof body === 'object' && body !== null ? body as HttpErrorBody : undefined
+}
+
+/** Build the transport error for a non-ok response. */
+function errorFor(status: number, body: unknown): HttpApiError {
+  const object = bodyObject(body)
+  const message = typeof object?.error === 'string' ? object.error : `HTTP ${status}`
+  return new HttpApiError(message, status, object)
 }

package/src/core.ts

@@ -1,47 +1,37 @@
-/**
- * The shared workspace core: the host store, the SSH engine, and the
- * workspace ledger, provided as `ctx.hardsshCore` by the main plugin row so
- * the two switch rows (fs / subprocess) resolve one instance each.
- */
-
-import type { SshEngine } from './ssh/engine.ts'
-import type { SshHostEntry, SshHostSummary } from './ssh/protocol.ts'
-import type { SshWorkspaceLedger } from './ledger.ts'
-import type { RemoteWorkspaceRunner } from './remote-runner.ts'
-import type { WorkspaceSeamState } from './seam-state.ts'
-
-/** Read-only host-store surface exposed on the core (the write paths live in
- *  the SSH routes, which get the full store). Avoids coupling the core type
- *  to either the plaintext HostStore or the vault-backed SecureHostStore. */
-export interface HostStoreView {
-  readonly path: string
-  list(): SshHostEntry[]
-  find(alias: string): SshHostEntry | undefined
-  summarize(entry: SshHostEntry): SshHostSummary
-}
-
-/** One process-wide core shared by every dsh-hardssh row. */
-export interface HardsshCore {
-  hosts: HostStoreView
-  engine: SshEngine
-  /** The SSH-bound workspace ledger (anchor dir -> remote dir). */
-  ledger: SshWorkspaceLedger
-  /** The shared seam state: ledger-derived routing snapshot + per-record
-   *  fs/subprocess instances, consumed by the fs/subprocess switch rows. */
-  seams: WorkspaceSeamState
-  /** Remote-workspace runner: resolve local anchor paths to remote channels
-   *  (git / files / commands) so other plugins (dsh-workbench-tiphareth) can
-   *  operate SSH-bound workspaces transparently. Optional in older builds. */
-  resolveRemote?: RemoteWorkspaceRunner['resolveRemote']
-}
-
-/**
- * @deprecated Use HardsshCore. Kept as a source-compatible migration alias.
- */
-export type EasysshCore = HardsshCore
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    hardsshCore: HardsshCore
-  }
-}
+/**
+ * The shared SSH operations core provided as `ctx.hardsshCore` by the main
+ * plugin row. Workspace routing is owned exclusively by `ctx.workspaceCore`;
+ * this service retains only the host store and shared SSH engine needed by
+ * SSH-specific integrations.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { SshEngine } from './ssh/engine.ts'
+import type { SshHostEntry, SshHostSummary } from './ssh/protocol.ts'
+
+/** Read-only host-store surface exposed on the core (the write paths live in
+ *  the SSH routes, which get the full store). Avoids coupling the core type
+ *  to either the plaintext HostStore or the vault-backed SecureHostStore. */
+export interface HostStoreView {
+  readonly path: string
+  list(): SshHostEntry[]
+  find(alias: string): SshHostEntry | undefined
+  summarize(entry: SshHostEntry): SshHostSummary
+}
+
+/** One process-wide SSH operations core. Workspace consumers use WorkspaceCore. */
+export interface HardsshCore {
+  hosts: HostStoreView
+  engine: SshEngine
+}
+
+/**
+ * @deprecated Use HardsshCore. Kept as a source-compatible migration alias.
+ */
+export type EasysshCore = HardsshCore
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    hardsshCore: HardsshCore
+  }
+}

package/src/fs.ts

@@ -1,85 +1,171 @@
-/**
- * The `ctx.fs` switch row: provides the workspace-routing filesystem facade in
- * the host scope. The local backend (the deployment's sandboxed filesystem) is
- * mounted in an isolated child scope so its own `ctx.fs` provide never
- * collides. Routing and per-record remote backends are owned by the SHARED
- * seam state (hardsshCore.seams): the row only binds its per-record backend
- * factory and reads the state on every call. Every SSH-bound workspace record
- * gets its OWN remote backend instance bound to that record's alias + remote
- * root; the facade routes each call by the session cwd — an anchor path of an
- * SSH workspace routes remote, everything else stays local. The facade
- * auto-provides `fs` here because the `fs-sandbox` row is disabled by the
- * profile patch.
- *
- * The seam state re-applies the ledger snapshot synchronously on every
- * commit, so creating or removing an SSH workspace takes effect without a
- * plugin restart and the fs/subprocess seams can never disagree. Before the
- * initial ledger load finishes, routing degrades to local with a one-time
- * warning for anchor-root paths.
- *
- * @module dsh-hardssh/fs
- */
-
-import type { Context } from '@deepseek-ai/cordis'
-import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
-import type { HardsshCore } from './core.ts'
-import { isPathUnderAnchor } from './ledger.ts'
-import type { WorkspaceState } from './protocol.ts'
-import { SshFileSystem } from './remote/remote-fs.ts'
-import { WFS_NAMESPACE_MARKER, SwitchFileSystem } from './switch/switch-fs.ts'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    hardsshCore: HardsshCore
-  }
-}
-
-/** Stable cordis plugin name. */
-export const name = 'hardssh-fs'
-
-/** Services required: the shared workspace core (mode store + engine) and the
- *  sandbox policy the local backend (`SandboxedFileSystem`) consumes. */
-export const inject = ['hardsshCore', 'sandboxPolicy']
-
-/** A remote backend fixed to one SSH workspace's alias + remote root. */
-function fixedRemoteState(alias: string, remoteRoot: string): () => WorkspaceState {
-  return () => ({ mode: 'remote' as const, alias, remoteRoot })
-}
-
-/** Mount the switching filesystem facade. */
-export function apply(ctx: Context): void {
-  const core = ctx.hardsshCore
-
-  // The local backend lives in an isolated scope: its `fs` provide shadows
-  // only below this scope, so consumers keep resolving our facade.
-  const localCtx = ctx.isolate('fs')
-  const localFs = new SandboxedFileSystem(localCtx, {
-    cwd: process.env.DSH_CWD ?? process.cwd(),
-    diffBasisMaxBytes: 10 * 1024 * 1024,
-  })
-
-  // Bind the per-record remote backend builder into the shared seam state;
-  // instances are built lazily on first route and reused across refreshes.
-  core.seams.bindFs((record) => ({
-    backend: new SshFileSystem(ctx.isolate('fs'), core.engine, fixedRemoteState(record.alias, record.remoteRoot)),
-    namespace: `${WFS_NAMESPACE_MARKER}${record.id.toLowerCase()}/`,
-    anchorPath: record.anchorPath,
-    remoteRoot: record.remoteRoot,
-  }))
-
-  const anchorRoot = core.ledger.anchorsRoot()
-  let warnedUnready = false
-
-  // The SwitchFileSystem constructor registers the `fs` provide on ctx.
-  new SwitchFileSystem(ctx, {
-    local: localFs,
-    worldFor: (cwd) => {
-      if (!core.seams.isReady() && !warnedUnready && cwd !== undefined && isPathUnderAnchor(anchorRoot, cwd)) {
-        warnedUnready = true
-        console.warn('[dsh-hardssh] fs routing is not ready yet (workspace ledger still loading) — operating on the local anchor until the snapshot is applied')
-      }
-      return core.seams.worldForFs(cwd) ?? { backend: localFs, namespace: '' }
-    },
-    worldForNamespace: (namespace) => core.seams.worldForFsNamespace(namespace),
-  })
-}
+/**
+ * The `ctx.fs` switch row: provides the generic WorkspaceCore-routing
+ * filesystem facade in the host scope. The local backend (the deployment's
+ * sandboxed filesystem) is mounted in an isolated child scope so its own
+ * `ctx.fs` provide never collides.
+ *
+ * Routing worlds always come from `WorkspaceCore`/router:
+ * `connection.get('workspace.fs')` returns the root-bound DSH `FileSystem`
+ * cached by the provider. A cwd inside a workspace anchor resolves through
+ * that connection; everything else stays local. Before the core is ready, or
+ * for an unowned path beneath the managed SSH anchor root, access fails closed
+ * rather than touching the client filesystem.
+ *
+ * @module dsh-hardssh/fs
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
+import { FsError } from '@deepseek-ai/dsh-fs'
+import type { FileSystem } from '@deepseek-ai/dsh-fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { anchorRoot, isPathUnderAnchor } from './ledger.ts'
+import { vaultDirectory, legacyVaultPath } from './ssh/vault.ts'
+import { WFS_NAMESPACE_MARKER, SwitchFileSystem, type WorkspaceWorld } from './switch/switch-fs.ts'
+import type { WorkspaceCore } from './runtime/workspace-core.ts'
+import type { WorkspaceRecord } from './base/model.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'hardssh-fs'
+
+/** The generic workspace core plus the policy used by the local fallback. */
+export const inject = ['sandboxPolicy', 'workspaceCore']
+
+/** The record behind a router connection (sync snapshot lookup). */
+function genericRecordFor(core: WorkspaceCore, id: string): WorkspaceRecord | undefined {
+  return core.ledger.snapshotSync().records.find(record => record.id === id)
+}
+
+/** Resolve the fs world owning a cwd, or undefined when it is definitely local. */
+export function genericFsWorldFor(
+  core: WorkspaceCore,
+  cwd: string | undefined,
+  reservedAnchorRoots: readonly string[],
+): WorkspaceWorld | undefined {
+  if (!core.isReady()) {
+    if (cwd !== undefined && reservedAnchorRoots.some(root => isPathUnderAnchor(root, cwd))) {
+      throw new Error('fs-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)')
+    }
+    return undefined
+  }
+  const connection = core.router.fromAnchor(cwd)
+  if (connection === undefined) return undefined
+  const record = genericRecordFor(core, connection.workspaceId)
+  if (record === undefined) throw new Error(`fs-workspace: routed workspace '${connection.workspaceId}' is missing from the ledger`)
+  if (record.anchor === undefined) throw new Error(`fs-workspace: workspace '${record.id}' has no anchor`)
+  const backend = connection.get('workspace.fs') as FileSystem | undefined
+  if (backend === undefined) throw new Error(`fs-workspace: workspace '${record.id}' provides no workspace.fs capability`)
+  return {
+    backend,
+    namespace: `${WFS_NAMESPACE_MARKER}${record.id.toLowerCase()}/`,
+    anchorPath: record.anchor.path,
+    remoteRoot: record.location.root,
+  }
+}
+
+/** Resolve one namespaced target key, failing closed for stale namespaces. */
+export function genericFsWorldForNamespace(core: WorkspaceCore, namespace: string): WorkspaceWorld | undefined {
+  if (!core.isReady()) return undefined
+  const route = core.router.codec.decode(namespace)
+  if (route === undefined) return undefined
+  const resolution = core.router.resolveRoute(route)
+  if (resolution === undefined) return undefined
+  const record = genericRecordFor(core, resolution.connection.workspaceId)
+  if (record === undefined) throw new Error(`fs-workspace: routed workspace '${resolution.connection.workspaceId}' is missing from the ledger`)
+  if (record.anchor === undefined) throw new Error(`fs-workspace: workspace '${record.id}' has no anchor`)
+  const backend = resolution.connection.get('workspace.fs') as FileSystem | undefined
+  if (backend === undefined) throw new Error(`fs-workspace: workspace '${record.id}' provides no workspace.fs capability`)
+  return {
+    backend,
+    namespace: `${WFS_NAMESPACE_MARKER}${record.id.toLowerCase()}/`,
+    anchorPath: record.anchor.path,
+    remoteRoot: record.location.root,
+  }
+}
+
+/**
+ * Refuse a path that sits inside the managed anchor root but is owned by no
+ * registered workspace — as a NOT-FOUND answer, not as a fatal error.
+ *
+ * The path stays unreachable either way (it is never handed to the local
+ * backend, so a bound session cannot read or write client files through the
+ * anchor window). What changes is how callers SEE the refusal: `FS_NOT_FOUND`
+ * is the DSH contract for "this path does not exist", and the harness relies on
+ * it when walking UP from the session cwd looking for a project root —
+ * `dsh-agent-instructions` probes `<dir>/.git` per ancestor and treats ONLY
+ * `FS_NOT_FOUND` as "keep walking" (any other error aborts the whole run),
+ * `dsh-skill-filesystem` does the same. With a bare Error the very first step
+ * above the anchor (`<anchorRoot>/.git`) killed the run with
+ * "fs-ssh: … is inside the workspace anchor root but no registered workspace
+ * owns it (fail closed)". The message is kept verbatim so the refusal is still
+ * self-explanatory in logs.
+ */
+export function refuseUnownedAnchorPath(path: string): never {
+  throw new FsError(
+    `fs-ssh: '${path}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`,
+    'FS_NOT_FOUND',
+  )
+}
+
+/**
+ * The shipped `worldForAnchorPath` deps hook: the workspace owning an absolute
+ * anchor path (this session's or a SIBLING's), else the anchor-window refusal.
+ * Exported so the seam can be exercised without re-implementing the policy.
+ */
+export function anchorWorldFor(core: WorkspaceCore, anchorRootDir: string, path: string): WorkspaceWorld | undefined {
+  const world = genericFsWorldFor(core, path, [anchorRootDir])
+  if (world !== undefined) return world
+  if (isPathUnderAnchor(anchorRootDir, path)) refuseUnownedAnchorPath(path)
+  return undefined
+}
+
+/** Mount the generic switching filesystem facade. */
+export function apply(ctx: Context): void {
+  const localCtx = ctx.isolate('fs')
+  const localFs = new SandboxedFileSystem(localCtx, {
+    cwd: process.env.DSH_CWD ?? process.cwd(),
+    diffBasisMaxBytes: 10 * 1024 * 1024,
+  })
+  const ws = ctx.workspaceCore
+  const anchorRootDir = anchorRoot()
+  let warnedUnready = false
+
+  new SwitchFileSystem(ctx, {
+    local: localFs,
+    localRoots: [join(homedir(), '.dsh'), join(homedir(), '.agents')],
+    // The anchor root is a window of placeholder dirs that must never be
+    // treated as local infrastructure even though it lives under ~/.dsh.
+    localRootExclusions: [anchorRootDir],
+    // The credential vault is REFUSED outright on every dispatch path (not only
+    // resolve/lstat): a bound session's agent must not be able to read — and
+    // offline-attack — the ciphertext through the routed filesystem. The
+    // pre-relocation path is denied too, because a failed move deliberately
+    // leaves the original file in place.
+    deniedRoots: [vaultDirectory(), legacyVaultPath()],
+    worldForAnchorPath: (path) => anchorWorldFor(ws, anchorRootDir, path),
+    worldFor: (cwd) => {
+      if (!ws.isReady()) {
+        if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
+          if (!warnedUnready) {
+            warnedUnready = true
+            console.warn('[dsh-hardssh] fs routing is not ready yet (workspace core still initializing or failed) — refusing access beneath the workspace anchor root')
+          }
+          throw new Error('fs-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)')
+        }
+        return { backend: localFs, namespace: '' }
+      }
+      const world = genericFsWorldFor(ws, cwd, [anchorRootDir])
+      if (world !== undefined) return world
+      if (cwd !== undefined && isPathUnderAnchor(anchorRootDir, cwd)) {
+        // Deliberately NOT the FS_NOT_FOUND refusal above: `cwd` is the session's
+        // own identity, not a path being probed. An unowned cwd means the
+        // workspace was deleted out from under a live session, which must stay
+        // loud instead of degrading into "not found" on every relative path.
+        throw new Error(`fs-ssh: '${cwd}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`)
+      }
+      return { backend: localFs, namespace: '' }
+    },
+    worldForNamespace: (namespace) => genericFsWorldForNamespace(ws, namespace),
+  })
+}