@gotcos/glasses-server 6.12.1 → 6.12.2

package/.env.example

@@ -38,7 +38,7 @@ BIND_HOST=0.0.0.0
 
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
-#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
+#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://docs.anthropic.com/en/docs/claude-code/getting-started, then `claude auth login`)
 #   GPT Frontier/Balanced  ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
 # Install at least one. Pick the default model the glasses use:
 # COS_G2_DEFAULT_MODEL=sonnet     # opus | fable | sonnet | codex-frontier | codex-balanced

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 6.12.2
+
+First-install hardening for public `npx` users.
+
+- **No nested install inside npm's cache.** The launcher resolves the declared
+  `tsx` dependency from npm's existing `npx` dependency tree and never runs a
+  second `npm install` from the ephemeral package directory.
+- **Permission failures do not spread.** A broken or incomplete package fails
+  closed with a user-owned isolated-cache recovery command. COS never suggests
+  `sudo npm`, broad ownership changes, or writing through a root-owned cache.
+- **Claude Desktop is no longer mistaken for Claude Code.** First-run guidance
+  explicitly requires the terminal CLI, keeps the scoped npm command on one
+  copyable line, forbids `sudo`, and explains the interactive sign-in step.
+- **Known signed-out agents fail before startup.** Installed Claude/Codex
+  binaries are checked before first-query readiness. Older CLI versions whose
+  authentication state cannot be proven show a warning instead of a false
+  signed-in claim.
+- **Local credentials are private.** `~/.cos-glasses` is repaired to `0700`;
+  the token and profile files are repaired to `0600`; symlinked credential
+  paths fail closed; auto-generated tokens are persisted with an atomic write.
+- **Runtime behavior is unchanged.** Query, prompt recovery, meetings, media,
+  diagnostics, transcription, display, and server data contracts are untouched.
+
 ## 6.12.1
 
 Public-safe CLI diagnostics for the COS Glasses Recovery Center.

package/README.md

@@ -8,7 +8,7 @@ API key is pasted into the phone for chat.
 ## Quick start
 
 ```bash
-npx @gotcos/glasses-server
+npx --yes @gotcos/glasses-server@latest
 ```
 
 The launcher checks Node, finds your CLI, checks voice and image processing,
@@ -24,7 +24,10 @@ without silently losing completed replies.
 ## Requirements
 
 - **Node.js 20.11+** — https://nodejs.org
-- **Claude Code CLI** (Opus/Fable/Sonnet) — https://claude.ai/download, then `claude login`
+- **Claude Code CLI** (Opus/Fable/Sonnet). Claude Desktop alone does not install
+  the terminal command. Install it on one line with
+  `npm install -g @anthropic-ai/claude-code` (**never with `sudo`**), then run
+  `claude` and finish the browser sign-in
   _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
 - `brew install whisper-cpp` for free local voice (the launcher can download the model)
@@ -106,9 +109,20 @@ BIND_HOST=0.0.0.0 npm run start:server
 
 ## Troubleshooting
 
+- *Claude Desktop is installed but COS says Claude Code is missing* — Desktop
+  and the terminal CLI are separate. Run
+  `npm install -g @anthropic-ai/claude-code` on one line without `sudo`, then
+  run `claude` and complete sign-in. Verify with `claude --version` before
+  starting COS again.
+- *npm reports EACCES or a root-owned cache* — never run COS or npm with
+  `sudo`, and do not recursively change system ownership. Use a private COS
+  cache instead:
+  `npm_config_cache="$HOME/.cos-glasses/npm-cache" npx --yes @gotcos/glasses-server@latest`.
+  Version 6.12.2+ never runs a second install from inside npm's temporary cache.
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
-- *Safari connects but the app does not* — confirm `npx @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
-- *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
+- *Safari connects but the app does not* — confirm `npx --yes @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
+- *AI queries fail* — run `claude auth status` / `codex login status`, then
+  `claude auth login` / `codex login` when the provider reports signed out.
 - *Voice getting billed?* — voice is local-only by default in 6.12.0+. Confirm
   `/api/health` reports `capabilities.transcription.mode: "local-only"`. Remove
   `COS_OPENAI_WHISPER_FALLBACK` (or set it to `0`) to disable an earlier opt-in.
@@ -117,7 +131,7 @@ BIND_HOST=0.0.0.0 npm run start:server
   keeps compatible prompt/meeting audio available for retry instead of silently
   sending it to OpenAI.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
-- *Prompt recovery unavailable?* — update with `npx @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
+- *Prompt recovery unavailable?* — update with `npx --yes @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
 - *Durable query recovery unavailable?* — build 204+ requires server 6.10.0+ and
   `COS_DURABLE_QUERY_JOBS=1`. Restart once, then confirm `/api/health` reports
   `features.durableQueryJobs: true`, protocol `1`, and state `ready`. To roll

package/bin/cli.cjs

@@ -5,7 +5,17 @@
 // package — there is no clone. Config persists at ~/.cos-glasses/.
 
 const { execSync, spawn } = require('child_process')
-const { existsSync, mkdirSync, statSync, readFileSync, copyFileSync, unlinkSync, renameSync } = require('fs')
+const {
+  existsSync,
+  mkdirSync,
+  statSync,
+  lstatSync,
+  readFileSync,
+  copyFileSync,
+  unlinkSync,
+  renameSync,
+  chmodSync,
+} = require('fs')
 const { join, resolve } = require('path')
 const { homedir } = require('os')
 
@@ -30,11 +40,11 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(bold('  COS Glasses Server'))
   console.log('')
   console.log('  Usage:')
-  console.log('    npx @gotcos/glasses-server')
+  console.log('    npx --yes @gotcos/glasses-server@latest')
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')
-  console.log('    - Claude Code CLI (Opus / Fable / Sonnet) or Codex CLI (GPT Frontier / Balanced)')
+  console.log('    - Claude Code CLI (not Claude Desktop) or Codex CLI')
   console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
   console.log('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
@@ -72,52 +82,142 @@ function normalizeCodexVersion(raw) {
   const line = raw.split('\n').map((s) => s.trim()).find((s) => /^codex(?:-cli)?\s+/i.test(s)) || raw.split('\n')[0].trim()
   return line.replace(/^codex(?:-cli)?\s*/i, '') || line
 }
+function commandResult(command) {
+  try {
+    return {
+      ok: true,
+      output: execSync(`${command} 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim(),
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      output: (err.stdout?.toString() || err.stderr?.toString() || '').trim(),
+    }
+  }
+}
+function claudeAuthState() {
+  const result = commandResult('claude auth status --json')
+  try {
+    const parsed = JSON.parse(result.output)
+    if (parsed.loggedIn === true) return 'ready'
+    if (parsed.loggedIn === false) return 'signed-out'
+  } catch { /* older CLIs may not support JSON status */ }
+  if (/not logged in|logged out|sign[ -]?in required/i.test(result.output)) return 'signed-out'
+  return 'unknown'
+}
+function codexAuthState() {
+  const result = commandResult('codex login status')
+  if (/logged in/i.test(result.output) && !/not logged in/i.test(result.output)) return 'ready'
+  if (/not logged in|logged out|sign[ -]?in required/i.test(result.output)) return 'signed-out'
+  return 'unknown'
+}
 const claudeVersion = getCliVersion('claude')
 const codexVersion = getCliVersion('codex')
+const claudeAuth = claudeVersion ? claudeAuthState() : null
+const codexAuth = codexVersion ? codexAuthState() : null
 if (claudeVersion) {
-  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
+  if (claudeAuth === 'signed-out') {
+    console.log(yellow('  ⚠') + ` Claude Code ${claudeVersion} installed — sign-in required`)
+    console.log('    Run: ' + bold('claude auth login'))
+  } else if (claudeAuth === 'unknown') {
+    console.log(yellow('  ⚠') + ` Claude Code ${claudeVersion} installed — sign-in status unavailable`)
+    console.log('    Verify: ' + bold('claude auth status'))
+  } else {
+    console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
+  }
 } else {
   console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Fable/Sonnet unavailable'))
-  console.log('    Install: ' + bold('https://claude.ai/download'))
+  console.log('    Claude Desktop does not install the terminal CLI.')
+  console.log('    Install (no sudo): ' + bold('npm install -g @anthropic-ai/claude-code'))
+  console.log('    Then run:          ' + bold('claude') + ' and finish sign-in')
 }
 if (codexVersion) {
-  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
+  if (codexAuth === 'signed-out') {
+    console.log(yellow('  ⚠') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} installed — sign-in required`)
+    console.log('    Run: ' + bold('codex login'))
+  } else if (codexAuth === 'unknown') {
+    console.log(yellow('  ⚠') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} installed — sign-in status unavailable`)
+    console.log('    Verify: ' + bold('codex login status'))
+  } else {
+    console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
+  }
 } else {
   console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— GPT Frontier/Balanced unavailable'))
 }
-if (!claudeVersion && !codexVersion) {
+const hasUsableAgent = (claudeVersion && claudeAuth !== 'signed-out') || (codexVersion && codexAuth !== 'signed-out')
+if (!hasUsableAgent) {
   console.log('')
-  console.log(red('  ✗ No supported agent CLI found'))
-  console.log('    Install Claude Code: ' + bold('https://claude.ai/download'))
+  console.log(red('  ✗ No signed-in agent CLI is ready'))
+  console.log('    Claude Desktop alone is not enough; COS needs a terminal CLI.')
+  console.log('    Install Claude Code (no sudo): ' + bold('npm install -g @anthropic-ai/claude-code'))
+  console.log('    Then run:                       ' + bold('claude auth login'))
   console.log('    or Codex CLI:        ' + bold('https://developers.openai.com/codex/') + ' then ' + bold('codex login'))
+  console.log('    Setup help:          ' + bold('https://www.gotcos.com/wizard/'))
   console.log('')
   process.exit(1)
 }
 
-// Step 3: dependencies — only when run from a git clone without node_modules.
-// `npx` already installed the package's deps alongside it.
-if (!existsSync(join(PKG_ROOT, 'node_modules'))) {
+// Step 3: resolve the dependency npm already installed. With `npx`, dependency
+// packages are siblings in npm's temporary node_modules tree rather than under
+// PKG_ROOT/node_modules. Running a second `npm install` from inside that cache
+// is both unnecessary and unsafe: a prior sudo-based npm install can make the
+// shared cache root-owned and turn an otherwise valid first launch into EACCES.
+let tsxImport
+try {
+  tsxImport = require.resolve('tsx/esm', { paths: [PKG_ROOT] })
+} catch {
   console.log('')
-  console.log(`  ${yellow('⟳')} Installing dependencies...`)
-  try {
-    execSync('npm install', { cwd: PKG_ROOT, stdio: 'pipe', timeout: 300000 })
-    console.log(green('  ✓') + ' Dependencies installed')
-  } catch (err) {
-    console.log(red('  ✗ npm install failed'))
-    console.log(`    ${err.stderr?.toString().slice(0, 200) || err.message}`)
-    process.exit(1)
-  }
+  console.log(red('  ✗ COS package dependencies are incomplete'))
+  console.log('    Do not use sudo. Retry with an isolated user-owned npm cache:')
+  console.log('    ' + bold('npm_config_cache="$HOME/.cos-glasses/npm-cache" npx --yes @gotcos/glasses-server@latest'))
+  console.log('    Source installs only: run ' + bold('npm install') + ' in the cloned repository.')
+  process.exit(1)
 }
 
 // Step 4: persistent config at ~/.cos-glasses/ (survives npx cache churn)
-mkdirSync(CONFIG_DIR, { recursive: true })
+function securePrivateDirectory(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stats = lstatSync(dir)
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`${dir} must be a private directory, not a symlink`)
+  }
+  chmodSync(dir, 0o700)
+}
+
+function securePrivateFile(file) {
+  if (!existsSync(file)) return
+  const stats = lstatSync(file)
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(`${file} must be a regular file, not a symlink`)
+  }
+  chmodSync(file, 0o600)
+}
+
+try {
+  securePrivateDirectory(CONFIG_DIR)
+} catch (err) {
+  console.log('')
+  console.log(red('  ✗ COS config directory is unsafe'))
+  console.log(`    ${err.message}`)
+  console.log('    Move it aside and rerun COS; do not use sudo or broad ownership changes.')
+  process.exit(1)
+}
 const ENV_FILE = join(CONFIG_DIR, '.env')
 const ENV_EXAMPLE = join(PKG_ROOT, '.env.example')
 if (!existsSync(ENV_FILE) && existsSync(ENV_EXAMPLE)) {
   copyFileSync(ENV_EXAMPLE, ENV_FILE)
+  chmodSync(ENV_FILE, 0o600)
   console.log(green('  ✓') + ` Created config at ${dim(ENV_FILE)}`)
 }
 if (existsSync(ENV_FILE)) {
+  try {
+    securePrivateFile(ENV_FILE)
+  } catch (err) {
+    console.log('')
+    console.log(red('  ✗ COS config file is unsafe'))
+    console.log(`    ${err.message}`)
+    process.exit(1)
+  }
   try {
     for (const line of readFileSync(ENV_FILE, 'utf-8').split('\n')) {
       const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)=(.*)$/)
@@ -130,6 +230,15 @@ const PROFILE_FILE = join(CONFIG_DIR, '.cos-profile.json')
 const PROFILE_EXAMPLE = join(PKG_ROOT, '.cos-profile.example.json')
 if (!existsSync(PROFILE_FILE) && existsSync(PROFILE_EXAMPLE)) {
   copyFileSync(PROFILE_EXAMPLE, PROFILE_FILE)
+  chmodSync(PROFILE_FILE, 0o600)
+}
+try {
+  securePrivateFile(PROFILE_FILE)
+} catch (err) {
+  console.log('')
+  console.log(red('  ✗ COS profile is unsafe'))
+  console.log(`    ${err.message}`)
+  process.exit(1)
 }
 if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
 
@@ -156,14 +265,15 @@ function isValidWhisperModel(p) {
 }
 const whisperCliPath = findWhisperCli()
 const hasValidModel = isValidWhisperModel(WHISPER_MODEL_PATH)
+let localVoiceReady = Boolean(whisperCliPath && hasValidModel)
 if (whisperCliPath && hasValidModel) {
   console.log(green('  ✓') + ' whisper.cpp + model ready ' + dim('— voice = local (FREE)'))
 } else if (whisperCliPath && !hasValidModel) {
   if (existsSync(WHISPER_MODEL_PATH)) { try { unlinkSync(WHISPER_MODEL_PATH) } catch {} }
   if (existsSync(WHISPER_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {} }
   console.log(yellow('  ⚠') + ' whisper.cpp installed but model missing')
-  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB). Ctrl-C to skip (voice remains unavailable by default).'))
-  console.log('    ' + dim('Skip permanently: SKIP_WHISPER_DOWNLOAD=1 npx @gotcos/glasses-server'))
+  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB).'))
+  console.log('    ' + dim('Skip: SKIP_WHISPER_DOWNLOAD=1 npx --yes @gotcos/glasses-server@latest'))
   if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
     console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — local voice unavailable')
   } else {
@@ -173,6 +283,7 @@ if (whisperCliPath && hasValidModel) {
       const stats = statSync(WHISPER_MODEL_PARTIAL)
       if (stats.size < WHISPER_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
       renameSync(WHISPER_MODEL_PARTIAL, WHISPER_MODEL_PATH)
+      localVoiceReady = true
       console.log(green('  ✓') + ' Model downloaded ' + dim('— voice = local (FREE)'))
     } catch (err) {
       try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {}
@@ -215,17 +326,23 @@ try {
     console.log(green('  ✓') + ` COS detected in ${dim(ld)} — glasses chat will load its brain`)
   }
 } catch { /* detection is best-effort */ }
+if (!localVoiceReady) {
+  console.log('')
+  console.log(yellow('  ⚠ LOCAL VOICE NOT READY'))
+  console.log('    Text chat can start. Under the default local-only policy, voice prompts remain unavailable.')
+  console.log('    Install: ' + bold('brew install whisper-cpp'))
+  console.log('    Then stop COS with Ctrl-C and rerun: ' + bold('npx --yes @gotcos/glasses-server@latest'))
+}
 console.log('')
 console.log(dim('  Starting server...'))
 console.log('')
 const serverProc = spawn(
   process.execPath,
-  ['--import', 'tsx/esm', 'server/index.ts'],
+  ['--import', tsxImport, 'server/index.ts'],
   { cwd: PKG_ROOT, stdio: 'inherit', env: { ...process.env } }
 )
 serverProc.on('error', (err) => {
   console.error(red(`  Server failed to start: ${err.message}`))
-  if (err.message.includes('tsx')) console.error('  Try: cd ' + PKG_ROOT + ' && npm install')
   process.exit(1)
 })
 serverProc.on('exit', (code) => process.exit(code ?? 0))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.12.1",
+  "version": "6.12.2",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -7,7 +7,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createServer as createHttpsServer } from 'node:https'
 import { createServer as createHttpServer } from 'node:http'
-import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
 import { networkInterfaces, homedir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
@@ -44,6 +44,7 @@ import { getMediaStore } from './lib/media-store.js'
 import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
 import { serverMetrics } from './lib/server-metrics.js'
 import { initializeServerInstanceId } from './lib/server-instance-id.js'
+import { appendPrivateEnvBlock, UnsafeUserConfigPathError } from './lib/secure-user-config.js'
 import { createQueryJobsRouter } from './routes/query-jobs.js'
 import {
   initQueryJobRuntime,
@@ -76,10 +77,16 @@ let API_TOKEN_PERSISTED = false
 if (API_TOKEN_AUTO) {
   try {
     const envDir = join(homedir(), '.cos-glasses')
-    mkdirSync(envDir, { recursive: true })
-    appendFileSync(join(envDir, '.env'), `\n# auto-generated by the server so the app token survives restarts\nCOS_API_TOKEN=${API_TOKEN}\n`)
+    appendPrivateEnvBlock(
+      join(envDir, '.env'),
+      `# auto-generated by the server so the app token survives restarts\nCOS_API_TOKEN=${API_TOKEN}\n`,
+    )
     API_TOKEN_PERSISTED = true
-  } catch { /* read-only home — token stays per-session */ }
+  } catch (error) {
+    // Read-only homes may continue with a per-session token, but an unsafe
+    // symlinked credential path must fail closed instead of being ignored.
+    if (error instanceof UnsafeUserConfigPathError) throw error
+  }
 }
 
 // IP allowlist — only accept connections from localhost, meshnet, and private networks.
@@ -294,7 +301,7 @@ listenRequiredServers(listeners).then(() => {
     claudeAvailable = true
     console.log('[COS API] Claude Code CLI detected')
   } catch {
-    console.warn('[COS API] Claude Code CLI not found — install from https://claude.ai/download')
+    console.warn('[COS API] Claude Code CLI not found — install from https://docs.anthropic.com/en/docs/claude-code/getting-started')
     console.warn('[COS API]   Claude models unavailable; Codex models still work when Codex CLI is installed')
   }
 

package/server/lib/secure-user-config.ts

@@ -0,0 +1,64 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+export class UnsafeUserConfigPathError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UnsafeUserConfigPathError'
+  }
+}
+
+export function securePrivateDirectory(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stats = lstatSync(dir)
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new UnsafeUserConfigPathError(`${dir} must be a private directory, not a symlink`)
+  }
+  chmodSync(dir, 0o700)
+}
+
+export function secureExistingPrivateFile(file: string): void {
+  if (!existsSync(file)) return
+  const stats = lstatSync(file)
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new UnsafeUserConfigPathError(`${file} must be a regular file, not a symlink`)
+  }
+  chmodSync(file, 0o600)
+}
+
+/**
+ * Append an env block without ever following a symlink or exposing a partially
+ * written credential file. The replacement is created beside the destination
+ * at 0600 and atomically renamed into place.
+ */
+export function appendPrivateEnvBlock(file: string, block: string): void {
+  const dir = dirname(file)
+  securePrivateDirectory(dir)
+  secureExistingPrivateFile(file)
+
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const separator = current.length > 0 && !current.endsWith('\n') ? '\n' : ''
+  const temp = join(dir, `.${basename(file)}.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(temp, `${current}${separator}${block}`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600,
+    })
+    chmodSync(temp, 0o600)
+    renameSync(temp, file)
+    chmodSync(file, 0o600)
+  } catch (error) {
+    try { unlinkSync(temp) } catch { /* best-effort cleanup */ }
+    throw error
+  }
+}