boxdown 1.2.0 → 1.2.1

package/src/doctor.ts

@@ -1,7 +1,10 @@
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 import { resolveDevcontainerCli } from './devcontainer-cli.ts'
+import { buildGeneratedDevcontainerConfig, type DevcontainerConfig } from './config.ts'
+import { BOXDOWN_SECRET_ENV_NAMES } from './constants.ts'
+import { resolveConfiguredSshSigningKey, selectGitSigningKey, type GitSigningReason } from './git-signing.ts'
 import type { WorkspaceContext } from './paths.ts'
 import { runBuffered } from './process.ts'
 
@@ -40,6 +43,36 @@ function check (name: string, pass: boolean, okMessage: string, failMessage: str
   }
 }
 
+function secretEnvironmentConfigCheck (context: WorkspaceContext): DoctorCheck {
+  let config: DevcontainerConfig
+
+  try {
+    config = existsSync(context.generatedConfigPath)
+      ? JSON.parse(readFileSync(context.generatedConfigPath, 'utf8')) as DevcontainerConfig
+      : buildGeneratedDevcontainerConfig(context)
+  } catch {
+    return {
+      name: 'secret-environment-config',
+      level: 'warn',
+      message: 'Generated config could not be checked for secret-safe environment handling'
+    }
+  }
+
+  const runArgs = Array.isArray(config.runArgs) ? config.runArgs : []
+  const containerEnv = config.containerEnv ?? {}
+  const unsafe = runArgs.includes('--env-file') ||
+    runArgs.some((arg) => arg.includes('.env.development')) ||
+    BOXDOWN_SECRET_ENV_NAMES.some((name) => Object.hasOwn(containerEnv, name))
+
+  return {
+    name: 'secret-environment-config',
+    level: unsafe ? 'warn' : 'ok',
+    message: unsafe
+      ? 'Generated config still exposes Boxdown secrets through Docker environment settings; recreate after upgrading Boxdown'
+      : 'Generated config uses runtime-mounted secrets without Docker environment values'
+  }
+}
+
 async function runDoctorCommand (command: string, args: string[]): Promise<DoctorCommandResult> {
   return runBuffered(command, args, {
     mirrorStdout: false,
@@ -70,19 +103,77 @@ export async function runDoctorChecks (context: WorkspaceContext, options: RunDo
   ))
 
   const sshAgent = await runCommand('ssh-add', ['-L'])
-  const identities = sshAgent.code === 0
-    ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith('ssh-')).length
-    : 0
+  const identityLines = sshAgent.code === 0
+    ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith('ssh-'))
+    : []
+  const identities = identityLines.length
+  let configuredKey: string | undefined
+  let configuredFailure: { reason: GitSigningReason, detail?: string } | undefined
+  const format = await runCommand('git', ['config', '--global', '--get', 'gpg.format'])
+  if (format.code === 0 && format.stdout.trim() === 'ssh') {
+    const signingKey = await runCommand('git', ['config', '--global', '--get', 'user.signingkey'])
+    if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+      const resolved = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+        homeDir: dirname(context.hostGitconfigPath),
+        workspaceFolder: context.workspaceFolder
+      })
+      if (resolved.key === undefined) {
+        configuredFailure = {
+          reason: resolved.reason ?? 'configured-key-invalid',
+          detail: resolved.detail
+        }
+      } else {
+        configuredKey = resolved.key
+      }
+    }
+  }
+
+  const includeOptional = options.includeOptional ?? true
+  let ghAvailable = false
+  let ghAuth = false
+  let githubLogin: string | undefined
+  let githubAuthKeys: string[] | undefined
+  if (includeOptional) {
+    ghAvailable = await commandWorks(runCommand, 'gh', ['--version'])
+    if (ghAvailable) {
+      ghAuth = await commandWorks(runCommand, 'gh', ['auth', 'status', '--hostname', 'github.com'])
+      if (ghAuth && configuredKey === undefined && configuredFailure === undefined && identities > 1) {
+        const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+        githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined
+        if (githubLogin !== undefined) {
+          const authentication = await runCommand('gh', ['api', `users/${githubLogin}/keys`, '--paginate', '--jq', '.[].key'])
+          if (authentication.code === 0) githubAuthKeys = authentication.stdout.split(/\r?\n/)
+        }
+      }
+    }
+  }
+
+  const selected: { key?: string, reason?: GitSigningReason } = configuredFailure ?? selectGitSigningKey(identityLines, configuredKey, githubAuthKeys)
+  const selectedByConfiguration = selected.key !== undefined && configuredKey !== undefined
+  const selectedByGithub = selected.key !== undefined && configuredKey === undefined && identities > 1
+  const signingMessages: Record<GitSigningReason, string> = {
+    'agent-unavailable': 'SSH agent is unavailable; Boxdown commits will remain unsigned',
+    'no-identities': 'SSH agent has no identities; Boxdown commits will remain unsigned',
+    'ambiguous-identities': 'SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned',
+    'configured-key-unreadable': 'Configured SSH signing-key file could not be read; Boxdown commits will remain unsigned',
+    'configured-key-invalid': 'Configured SSH signing key is not a valid public key; Boxdown commits will remain unsigned',
+    'configured-key-not-loaded': 'Configured SSH signing key is not loaded in the agent; Boxdown commits will remain unsigned',
+    'agent-socket-unavailable': 'Host SSH-agent socket is unavailable; Boxdown commits will remain unsigned',
+    'docker-probe-image-unavailable': 'No local Docker image is available to probe commit-signing agent forwarding',
+    'agent-mount-unavailable': 'Docker could not mount the host SSH-agent socket; Boxdown commits will remain unsigned'
+  }
   checks.push({
     name: 'git-signing-agent',
-    level: sshAgent.code === 0 && identities === 1 ? 'ok' : 'warn',
+    level: sshAgent.code === 0 && selected.key !== undefined ? 'ok' : 'warn',
     message: sshAgent.code !== 0
-      ? 'SSH agent is unavailable; Boxdown commits will remain unsigned'
-      : identities === 0
-        ? 'SSH agent has no identities; Boxdown commits will remain unsigned'
-        : identities > 1
-          ? 'SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned'
-          : 'One SSH agent identity is available for Boxdown commit signing'
+      ? signingMessages['agent-unavailable']
+      : selected.key === undefined
+        ? signingMessages[selected.reason ?? 'ambiguous-identities']
+        : selectedByConfiguration
+          ? 'Configured SSH signing key is loaded in the agent'
+          : selectedByGithub
+            ? 'GitHub authentication keys identify one SSH agent identity for Boxdown commit signing'
+            : 'One SSH agent identity is available for Boxdown commit signing'
   })
 
   checks.push(check(
@@ -133,26 +224,29 @@ export async function runDoctorChecks (context: WorkspaceContext, options: RunDo
     `Missing Boxdown devcontainer assets: ${context.assetsDevcontainerDir}`
   ))
 
-  if (options.includeOptional ?? true) {
-    if (await commandWorks(runCommand, 'gh', ['--version'])) {
-      const ghAuth = await commandWorks(runCommand, 'gh', ['auth', 'status', '--hostname', 'github.com'])
+  checks.push(secretEnvironmentConfigCheck(context))
+
+  if (includeOptional) {
+    if (ghAvailable) {
       checks.push({
         name: 'gh-auth',
         level: ghAuth ? 'ok' : 'warn',
         message: ghAuth ? 'GitHub CLI auth is available' : 'GitHub CLI is available but not authenticated'
       })
-      if (ghAuth && identities === 1) {
-        const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
-        const signing = user.code === 0 && user.stdout.trim().length > 0
-          ? await runCommand('gh', ['api', `users/${user.stdout.trim()}/ssh_signing_keys`, '--paginate', '--jq', '.[].key'])
+      if (ghAuth && selected.key !== undefined) {
+        if (githubLogin === undefined) {
+          const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+          githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined
+        }
+        const signing = githubLogin !== undefined
+          ? await runCommand('gh', ['api', `users/${githubLogin}/ssh_signing_keys`, '--paginate', '--jq', '.[].key'])
           : { code: 1, stdout: '', stderr: '' }
-        const identity = sshAgent.stdout.split(/\r?\n/).find((line) => line.trim().startsWith('ssh-'))?.trim()
         checks.push({
           name: 'git-signing-github',
-          level: signing.code === 0 && identity !== undefined && signing.stdout.includes(identity.split(/\s+/, 3).slice(0, 2).join(' ')) ? 'ok' : 'warn',
+          level: signing.code === 0 && signing.stdout.includes(selected.key) ? 'ok' : 'warn',
           message: signing.code !== 0
             ? 'GitHub SSH signing-key registration could not be checked'
-            : signing.stdout.includes(identity?.split(/\s+/, 3).slice(0, 2).join(' ') ?? '')
+            : signing.stdout.includes(selected.key)
               ? 'Selected SSH key is registered with GitHub for commit signing'
               : 'Register the selected public key with GitHub as a signing key to receive Verified badges'
         })
@@ -215,10 +309,13 @@ async function checkDockerBindMounts (
 
   mkdirSync(context.workspaceDataDir, { recursive: true })
   const runtimeProbeDir = mkdtempSync(join(context.workspaceDataDir, 'doctor-mount-probe-'))
+  mkdirSync(context.workspaceSecretEnvDir, { recursive: true, mode: 0o700 })
+  chmodSync(context.workspaceSecretEnvDir, 0o700)
   const sources: DockerMountSource[] = [
     { label: 'workspace', path: context.workspaceFolder },
     { label: 'Boxdown devcontainer assets', path: context.assetsDevcontainerDir },
-    { label: 'Boxdown runtime state', path: runtimeProbeDir }
+    { label: 'Boxdown runtime state', path: runtimeProbeDir },
+    { label: 'Boxdown runtime secret state', path: context.workspaceSecretEnvDir }
   ]
 
   try {

package/src/git-signing.ts

@@ -1,18 +1,64 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
 
+import type { WorkspaceCommandLogger } from './logging.ts'
 import type { WorkspaceContext } from './paths.ts'
-import { runBuffered } from './process.ts'
+import { runBuffered, type CommandResult } from './process.ts'
 
-export type GitSigningReason = 'agent-unavailable' | 'no-identities' | 'ambiguous-identities' | 'configured-key-not-loaded' | 'agent-mount-unavailable'
+export type GitSigningReason = 'agent-unavailable' | 'no-identities' | 'ambiguous-identities' | 'configured-key-unreadable' | 'configured-key-invalid' | 'configured-key-not-loaded' | 'agent-socket-unavailable' | 'docker-probe-image-unavailable' | 'agent-mount-unavailable'
 
 export interface GitSigningPlan {
   enabled: boolean
   reason?: GitSigningReason
+  detail?: string
   publicKey?: string
   agentSocketSource?: string
 }
 
+const GIT_SIGNING_REASON_MESSAGES: Record<GitSigningReason, string> = {
+  'agent-unavailable': 'the host SSH agent is unavailable',
+  'no-identities': 'the host SSH agent has no loaded identities',
+  'ambiguous-identities': 'multiple SSH identities are loaded and no signing key could be selected safely',
+  'configured-key-unreadable': 'the configured SSH signing-key file could not be read',
+  'configured-key-invalid': 'the configured SSH signing key is not a valid public key',
+  'configured-key-not-loaded': 'the configured SSH signing key is not loaded in the agent',
+  'agent-socket-unavailable': 'the host SSH-agent socket is unavailable',
+  'docker-probe-image-unavailable': 'no local Docker image is available to probe the SSH-agent mount',
+  'agent-mount-unavailable': 'Docker could not mount the host SSH-agent socket'
+}
+
+function compactDiagnosticDetail (detail: string): string {
+  return detail
+    .trim()
+    .replace(/\s+/gu, ' ')
+    .slice(0, 2000)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----.*?(?:-----END [^-]*PRIVATE KEY-----|$)/giu, '[redacted-private-key]')
+    .replace(/\b(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+|sk-(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+))\s+[A-Za-z0-9+/=]{16,}/gu, '[redacted-ssh-key]')
+    .replace(/\b(?:github_pat_|gh[pousr]_|glpat-|xox[baprs]-)[A-Za-z0-9_-]{8,}/gu, '[redacted-token]')
+    .replace(/\b(?:Bearer\s+|token[=:]\s*)[A-Za-z0-9._~+/-]{8,}/giu, '[redacted-token]')
+    .slice(0, 300)
+}
+
+export function reportGitSigningPlan (
+  plan: GitSigningPlan,
+  options: {
+    logger?: Pick<WorkspaceCommandLogger, 'boxdown'>
+    quiet?: boolean
+    writeWarning?: (message: string) => void
+  } = {}
+): void {
+  if (plan.enabled) return
+
+  const reason = plan.reason ?? 'agent-unavailable'
+  const detail = plan.detail === undefined ? '' : ` detail=${compactDiagnosticDetail(plan.detail)}`
+  options.logger?.boxdown(`git-signing: enabled=false reason=${reason}${detail}\n`)
+
+  if (options.quiet !== true) {
+    const writeWarning = options.writeWarning ?? ((message: string) => process.stderr.write(message))
+    writeWarning(`boxdown: commit signing disabled: ${GIT_SIGNING_REASON_MESSAGES[reason]}; commits will remain unsigned.\n`)
+  }
+}
+
 export function parseSshPublicKey (value: string): string | undefined {
   const [algorithm, key] = value.trim().split(/\s+/, 3)
   if (algorithm === undefined || key === undefined || !/^ssh-[A-Za-z0-9-]+$/.test(algorithm) || key.length === 0) {
@@ -22,11 +68,68 @@ export function parseSshPublicKey (value: string): string | undefined {
   return `${algorithm} ${key}`
 }
 
+export interface ConfiguredSshSigningKeyResult {
+  key?: string
+  reason?: Extract<GitSigningReason, 'configured-key-unreadable' | 'configured-key-invalid'>
+  detail?: string
+}
+
+export function resolveConfiguredSshSigningKey (
+  value: string,
+  options: { homeDir?: string, workspaceFolder: string }
+): ConfiguredSshSigningKeyResult {
+  const inlineValue = value.startsWith('key::') ? value.slice('key::'.length) : value
+  const inlineKey = parseSshPublicKey(inlineValue)
+  if (inlineKey !== undefined) {
+    return { key: inlineKey }
+  }
+  if (value.startsWith('key::')) {
+    return {
+      reason: 'configured-key-invalid',
+      detail: 'configured inline value is not a valid SSH public key'
+    }
+  }
+
+  let keyPath: string
+  if (value.startsWith('~/')) {
+    if (options.homeDir === undefined) {
+      return {
+        reason: 'configured-key-unreadable',
+        detail: 'configured public-key file could not be read'
+      }
+    }
+    keyPath = join(options.homeDir, value.slice(2))
+  } else {
+    keyPath = isAbsolute(value) ? value : resolve(options.workspaceFolder, value)
+  }
+
+  let publicKeyText: string
+  try {
+    publicKeyText = readFileSync(keyPath, 'utf8')
+  } catch {
+    return {
+      reason: 'configured-key-unreadable',
+      detail: 'configured public-key file could not be read'
+    }
+  }
+
+  const publicKey = parseSshPublicKey(publicKeyText.split(/\r?\n/u).find((line) => line.trim().length > 0) ?? '')
+  return publicKey === undefined
+    ? {
+        reason: 'configured-key-invalid',
+        detail: 'configured public-key file does not contain a valid SSH public key'
+      }
+    : { key: publicKey }
+}
+
 export function selectGitSigningKey (identities: string[], configuredKey?: string, githubKeys?: string[]): { key?: string, reason?: GitSigningReason } {
   const keys = identities.map(parseSshPublicKey).filter((key): key is string => key !== undefined)
   if (keys.length === 0) return { reason: 'no-identities' }
 
   const configured = configuredKey === undefined ? undefined : parseSshPublicKey(configuredKey)
+  if (configuredKey !== undefined && configured === undefined) {
+    return { reason: 'configured-key-invalid' }
+  }
   if (configured !== undefined) {
     return keys.includes(configured) ? { key: configured } : { reason: 'configured-key-not-loaded' }
   }
@@ -43,44 +146,121 @@ export function writeGitSigningPublicKey (context: WorkspaceContext, key: string
   writeFileSync(join(context.gitSigningStateDir, 'signing-key.pub'), `${parseSshPublicKey(key) ?? key}\n`, { mode: 0o644 })
 }
 
-async function dockerCanMountAgent (source: string): Promise<boolean> {
-  const images = await runBuffered('docker', ['image', 'ls', '--format', '{{.Repository}}:{{.Tag}}'], { mirrorStdout: false, mirrorStderr: false })
+type GitSigningCommandRunner = (command: string, args: string[]) => Promise<CommandResult>
+
+interface ResolveGitSigningPlanOptions {
+  env?: NodeJS.ProcessEnv
+  platform?: NodeJS.Platform
+  runCommand?: GitSigningCommandRunner
+}
+
+type AgentMountProbeResult =
+  | { ok: true }
+  | { ok: false, reason: Extract<GitSigningReason, 'docker-probe-image-unavailable' | 'agent-mount-unavailable'>, detail: string }
+
+async function runGitSigningCommand (command: string, args: string[]): Promise<CommandResult> {
+  return runBuffered(command, args, { mirrorStdout: false, mirrorStderr: false })
+}
+
+function failedCommandDetail (label: string, result: CommandResult): string {
+  const stderr = compactDiagnosticDetail(result.stderr)
+  return stderr.length === 0
+    ? `${label} failed with exit code ${result.code}`
+    : `${label} failed with exit code ${result.code}: ${stderr}`
+}
+
+async function probeDockerAgentMount (source: string, runCommand: GitSigningCommandRunner): Promise<AgentMountProbeResult> {
+  const images = await runCommand('docker', ['image', 'ls', '--format', '{{.Repository}}:{{.Tag}}'])
   const image = images.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => value.length > 0 && value !== '<none>:<none>')
-  if (images.code !== 0 || image === undefined) return false
+  if (images.code !== 0) {
+    return {
+      ok: false,
+      reason: 'agent-mount-unavailable',
+      detail: failedCommandDetail('Docker image listing', images)
+    }
+  }
+  if (image === undefined) {
+    return {
+      ok: false,
+      reason: 'docker-probe-image-unavailable',
+      detail: 'no tagged local Docker image was found'
+    }
+  }
 
-  const created = await runBuffered('docker', ['create', '--pull=never', '--entrypoint', '/bin/true', '--mount', `type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`, image], { mirrorStdout: false, mirrorStderr: false })
+  const created = await runCommand('docker', ['create', '--pull=never', '--entrypoint', '/bin/true', '--mount', `type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`, image])
   const containerId = created.stdout.trim().split(/\r?\n/)[0]
-  if (created.code !== 0 || containerId === undefined || containerId.length === 0) return false
-  await runBuffered('docker', ['rm', '-f', containerId], { mirrorStdout: false, mirrorStderr: false })
-  return true
+  if (created.code !== 0 || containerId === undefined || containerId.length === 0) {
+    return {
+      ok: false,
+      reason: 'agent-mount-unavailable',
+      detail: failedCommandDetail('Docker SSH-agent mount probe', created)
+    }
+  }
+  await runCommand('docker', ['rm', '-f', containerId])
+  return { ok: true }
 }
 
-export async function resolveGitSigningPlan (context: WorkspaceContext): Promise<GitSigningPlan> {
-  const result = await runBuffered('ssh-add', ['-L'], { mirrorStdout: false, mirrorStderr: false })
-  if (result.code !== 0) return { enabled: false, reason: 'agent-unavailable' }
+export async function resolveGitSigningPlan (context: WorkspaceContext, options: ResolveGitSigningPlanOptions = {}): Promise<GitSigningPlan> {
+  const runCommand = options.runCommand ?? runGitSigningCommand
+  const result = await runCommand('ssh-add', ['-L'])
+  if (result.code !== 0) {
+    return {
+      enabled: false,
+      reason: 'agent-unavailable',
+      detail: failedCommandDetail('ssh-add -L', result)
+    }
+  }
 
   const identities = result.stdout.split(/\r?\n/)
-  const format = await runBuffered('git', ['config', '--global', '--get', 'gpg.format'], { mirrorStdout: false, mirrorStderr: false })
-  const configuredKey = format.code === 0 && format.stdout.trim() === 'ssh'
-    ? (await runBuffered('git', ['config', '--global', '--get', 'user.signingkey'], { mirrorStdout: false, mirrorStderr: false })).stdout.trim()
-    : undefined
+  const format = await runCommand('git', ['config', '--global', '--get', 'gpg.format'])
+  let configuredKey: string | undefined
+  if (format.code === 0 && format.stdout.trim() === 'ssh') {
+    const signingKey = await runCommand('git', ['config', '--global', '--get', 'user.signingkey'])
+    if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+      const resolvedKey = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+        homeDir: options.env?.HOME ?? process.env.HOME,
+        workspaceFolder: context.workspaceFolder
+      })
+      if (resolvedKey.key === undefined) {
+        return {
+          enabled: false,
+          reason: resolvedKey.reason ?? 'configured-key-invalid',
+          detail: resolvedKey.detail
+        }
+      }
+      configuredKey = resolvedKey.key
+    }
+  }
   let githubKeys: string[] | undefined
-  if (identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
-    const user = await runBuffered('gh', ['api', 'user', '--jq', '.login'], { mirrorStdout: false, mirrorStderr: false })
+  if (configuredKey === undefined && identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
+    const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
     const login = user.stdout.trim()
     if (user.code === 0 && login.length > 0) {
-      const github = await runBuffered('gh', ['api', `users/${login}/keys`, '--paginate', '--jq', '.[].key'], { mirrorStdout: false, mirrorStderr: false })
+      const github = await runCommand('gh', ['api', `users/${login}/keys`, '--paginate', '--jq', '.[].key'])
       if (github.code === 0) githubKeys = github.stdout.split(/\r?\n/)
     }
   }
   const selected = selectGitSigningKey(identities, configuredKey, githubKeys)
   if (selected.key === undefined) return { enabled: false, reason: selected.reason }
 
-  const agentSocketSource = process.platform === 'darwin'
+  const agentSocketSource = (options.platform ?? process.platform) === 'darwin'
     ? '/run/host-services/ssh-auth.sock'
-    : process.env.SSH_AUTH_SOCK
-  if (agentSocketSource === undefined || agentSocketSource.length === 0) return { enabled: false, reason: 'agent-mount-unavailable' }
-  if (!await dockerCanMountAgent(agentSocketSource)) return { enabled: false, reason: 'agent-mount-unavailable' }
+    : options.env?.SSH_AUTH_SOCK ?? process.env.SSH_AUTH_SOCK
+  if (agentSocketSource === undefined || agentSocketSource.length === 0) {
+    return {
+      enabled: false,
+      reason: 'agent-socket-unavailable',
+      detail: 'SSH_AUTH_SOCK is not set'
+    }
+  }
+  const mountProbe = await probeDockerAgentMount(agentSocketSource, runCommand)
+  if (!mountProbe.ok) {
+    return {
+      enabled: false,
+      reason: mountProbe.reason,
+      detail: mountProbe.detail
+    }
+  }
 
   writeGitSigningPublicKey(context, selected.key)
   return { enabled: true, publicKey: selected.key, agentSocketSource }

package/src/logging.ts

@@ -24,6 +24,13 @@ function argvText (command: string, args: string[]): string {
   return JSON.stringify([command, ...args])
 }
 
+export function redactKnownSecretEnvironmentAssignments (value: string): string {
+  return value
+    .replace(/ANTHROPIC_API_KEY=[^\s,"\]}]+/gu, 'ANTHROPIC_API_KEY=[redacted]')
+    .replace(/SNYK_TOKEN=[^\s,"\]}]+/gu, 'SNYK_TOKEN=[redacted]')
+    .replace(/OP_SERVICE_ACCOUNT_TOKEN=[^\s,"\]}]+/gu, 'OP_SERVICE_ACCOUNT_TOKEN=[redacted]')
+}
+
 export class WorkspaceCommandLogger {
   readonly logPath: string
   readonly workspaceFolder: string
@@ -89,7 +96,10 @@ export class WorkspaceCommandLogger {
   }
 
   #redact (value: string): string {
-    return this.#redactions.reduce((current, redaction) => current.replaceAll(redaction, '[redacted]'), value)
+    return this.#redactions.reduce(
+      (current, redaction) => current.replaceAll(redaction, '[redacted]'),
+      redactKnownSecretEnvironmentAssignments(value)
+    )
   }
 
   #stream (stream: LogStreamName, chunk: Buffer | string): void {

package/src/main.ts

@@ -13,7 +13,7 @@ import { listWorkspaceMetadata, readWorkspaceMetadata, writeWorkspaceMetadata, t
 import { readPackageVersion } from './package-info.ts'
 import { createWorkspaceContext, createWorkspaceContextFromIdentity, defaultDataRoot, type WorkspaceContext } from './paths.ts'
 import { createProgress, resolveProgressMode, type ProgressReporter, type ProgressOutputTarget, type ProgressStepDefinition } from './progress.ts'
-import { purgeWorkspace } from './purge.ts'
+import { purgeWorkspace, removeWorkspaceRuntimeState } from './purge.ts'
 import { defaultSshAlias, installSshConfig, uninstallSshConfig } from './ssh-config.ts'
 import { dedupeSshInstallTargets, installSshInstallTarget, isSshConfigInstallTarget, SSH_INSTALL_TARGETS, sshInstallTargetFlagHintsText, supportedSshInstallTargetsText, type SshConfigInstallTarget } from './ssh-install-targets.ts'
 import { createStatusInfo, formatStatusText, statusIsHealthy } from './status.ts'
@@ -831,6 +831,7 @@ async function runDownCommand (workspaces: string[] | undefined, options: RunCli
       const context = createWorkspaceContext({ workspace })
       await runLoggedLifecycle(context, 'down', ['down', ...(workspace === undefined ? [] : ['--workspace', workspace])], async (logger) => {
         await removeWorkspaceContainer(context, { logger })
+        removeWorkspaceRuntimeState(context)
       })
     } catch (error) {
       failed = true

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, realpathSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
+import { homedir, tmpdir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -22,8 +22,11 @@ export interface WorkspaceContext {
   assetsDevcontainerDir: string
   cacheRoot: string
   dataRoot: string
+  runtimeRoot: string
   workspaceCacheDir: string
   workspaceDataDir: string
+  workspaceRuntimeDir: string
+  workspaceSecretEnvDir: string
   generatedConfigPath: string
   hostAgentsDir: string
   hostCodexAuthPath: string
@@ -92,6 +95,18 @@ export function defaultDataRoot (env: NodeJS.ProcessEnv = process.env): string {
   return join(homedir(), '.local', 'share', PACKAGE_NAME)
 }
 
+export function defaultRuntimeRoot (env: NodeJS.ProcessEnv = process.env): string {
+  if (env.BOXDOWN_RUNTIME_HOME) {
+    return env.BOXDOWN_RUNTIME_HOME
+  }
+
+  if (env.XDG_RUNTIME_DIR) {
+    return join(env.XDG_RUNTIME_DIR, PACKAGE_NAME)
+  }
+
+  return join(tmpdir(), `${PACKAGE_NAME}-${process.getuid?.() ?? 'user'}`)
+}
+
 export function defaultHostAgentsDir (env: NodeJS.ProcessEnv = process.env): string {
   return join(env.HOME ?? homedir(), '.agents')
 }
@@ -113,10 +128,12 @@ export function createWorkspaceContextFromIdentity (
   const assetsDevcontainerDir = options.assetsDevcontainerDir ?? env.BOXDOWN_DEVCONTAINER_ASSETS_DIR ?? join(packageRoot, 'assets', 'devcontainer')
   const cacheRoot = defaultCacheRoot(env)
   const dataRoot = defaultDataRoot(env)
+  const runtimeRoot = defaultRuntimeRoot(env)
   const hostAgentsDir = defaultHostAgentsDir(env)
   const hostCodexAuthPath = defaultHostCodexAuthPath(env)
   const workspaceCacheDir = join(cacheRoot, 'workspaces', identity.workspaceId)
   const workspaceDataDir = join(dataRoot, 'workspaces', identity.workspaceId)
+  const workspaceRuntimeDir = join(runtimeRoot, 'workspaces', identity.workspaceId)
   const hostGitconfigSnapshotDir = join(workspaceDataDir, 'gitconfig')
 
   return {
@@ -127,8 +144,11 @@ export function createWorkspaceContextFromIdentity (
     assetsDevcontainerDir,
     cacheRoot,
     dataRoot,
+    runtimeRoot,
     workspaceCacheDir,
     workspaceDataDir,
+    workspaceRuntimeDir,
+    workspaceSecretEnvDir: join(workspaceRuntimeDir, 'secrets'),
     generatedConfigPath: join(workspaceCacheDir, 'devcontainer.json'),
     hostAgentsDir,
     hostCodexAuthPath,

package/src/purge.ts

@@ -85,6 +85,10 @@ function removeWorkspaceStateDir (
   process.stdout.write(`Removed ${label}: ${path}\n`)
 }
 
+export function removeWorkspaceRuntimeState (context: WorkspaceContext): void {
+  removeWorkspaceStateDir(context, 'workspace runtime directory', context.workspaceRuntimeDir, context.runtimeRoot)
+}
+
 async function purgeAliasIntegrations (context: WorkspaceContext, alias: string): Promise<boolean> {
   let failed = false
 
@@ -194,6 +198,10 @@ export async function purgeWorkspace (context: WorkspaceContext, options: PurgeO
     }) || failed
   }
 
+  failed = await runPurgeStep('workspace runtime directory', () => {
+    removeWorkspaceRuntimeState(context)
+  }) || failed
+
   failed = await runPurgeStep('workspace cache directory', () => {
     removeWorkspaceStateDir(context, 'workspace cache', context.workspaceCacheDir, context.cacheRoot)
   }) || failed

package/src/shell.ts

@@ -61,10 +61,15 @@ function interactiveAgentPathScript (): string {
   ].join('\n')
 }
 
+function runtimeSecretEnvironmentScript (): string {
+  return 'source "${BASH_ENV:-/opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh}"'
+}
+
 export function interactiveShellScript (): string {
   return [
     interactiveTermSetupScript(),
     interactiveTtySetupScript(),
+    runtimeSecretEnvironmentScript(),
     'exec bash -i'
   ].join('\n')
 }
@@ -74,6 +79,7 @@ export function interactiveCommandScript (): string {
     interactiveTermSetupScript(),
     interactiveTtySetupScript(),
     interactiveAgentPathScript(),
+    runtimeSecretEnvironmentScript(),
     'exec "$@"'
   ].join('\n')
 }