typeclaw 0.1.0

package/src/secrets/index.ts

@@ -0,0 +1,13 @@
+export {
+  channelsSchema,
+  llmCredentialSchema,
+  llmCredentialsSchema,
+  parseSecretsFile,
+  secretsFileSchema,
+  type LlmCredential,
+  type LlmCredentials,
+  type ParseSecretsResult,
+  type SecretsFile,
+} from './schema'
+
+export { createSecretsStoreForAgent, SecretsBackend } from './storage'

package/src/secrets/migrate.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, renameSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseSecretsFile } from './schema'
+
+const LEGACY_FILENAME = 'auth.json'
+const TARGET_FILENAME = 'secrets.json'
+
+// One-shot rename of an old agent folder's auth.json to secrets.json. Called
+// from createSecretsStoreForAgent before the backend opens the file so the
+// rest of the storage pipeline only ever sees secrets.json. The rename runs
+// on every store construction because it's cheap (existsSync + early return
+// in the common case) and the rename itself is the state — no flag file.
+//
+// Cases:
+//   1. only auth.json exists                                  -> renameSync to secrets.json
+//   2. only secrets.json                                      -> no-op
+//   3. neither                                                -> no-op (backend will seed secrets.json)
+//   4. both exist, auth.json is the empty seed envelope       -> unlink auth.json
+//   5. both exist, secrets.json is the empty seed envelope    -> renameSync auth.json over the empty seed
+//   6. both exist, both carry credentials                     -> throw, refuse to merge
+//
+// The "both non-empty" hard error matters: if a user copied an old agent
+// folder, edited auth.json by hand, AND a newer typeclaw later created
+// secrets.json with real credentials, we don't know which is the source of
+// truth. Loud failure beats silent merge.
+export function migrateLegacyAuthJson(agentDir: string): void {
+  const legacyPath = join(agentDir, LEGACY_FILENAME)
+  const targetPath = join(agentDir, TARGET_FILENAME)
+
+  if (!existsSync(legacyPath)) return
+
+  if (!existsSync(targetPath)) {
+    renameWithRaceFallback(legacyPath, targetPath)
+    return
+  }
+
+  if (isEmptyEnvelope(legacyPath)) {
+    unlinkSync(legacyPath)
+    return
+  }
+
+  if (isEmptyEnvelope(targetPath)) {
+    // POSIX renameSync atomically replaces the destination; the empty
+    // secrets.json is the safer thing to lose vs an auth.json with
+    // credentials. Race-safe by the same reasoning as the no-target branch.
+    renameWithRaceFallback(legacyPath, targetPath)
+    return
+  }
+
+  throw new Error(
+    `Both ${LEGACY_FILENAME} and a non-empty ${TARGET_FILENAME} exist in ${agentDir}. ` +
+      `Inspect manually and remove the stale file before re-running.`,
+  )
+}
+
+// renameSync is atomic per syscall, but two concurrent createSecretsStoreForAgent
+// callers can both observe `auth.json` exists and `secrets.json` does not, then
+// race on the rename. One wins; the other gets ENOENT because the legacy file
+// is already gone. That's effectively a successful migration from the loser's
+// POV — recheck the target and swallow the ENOENT.
+function renameWithRaceFallback(from: string, to: string): void {
+  try {
+    renameSync(from, to)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT' && existsSync(to)) {
+      return
+    }
+    throw err
+  }
+}
+
+// "Empty envelope" = no actual credentials. Parsed shape with empty llm and
+// empty channels. We do NOT try to be clever about "approximately empty" —
+// exact emptiness is the only safe auto-delete / auto-overwrite case.
+function isEmptyEnvelope(path: string): boolean {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return false
+  }
+  if (raw.trim() === '') return true
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return false
+  }
+
+  const result = parseSecretsFile(parsed)
+  if (!result.ok) return false
+  return Object.keys(result.file.llm).length === 0 && Object.keys(result.file.channels).length === 0
+}

package/src/secrets/schema.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod'
+
+// The api_key shape exactly matches pi-coding-agent's ApiKeyCredential. We
+// re-state it here (rather than import the upstream type into the schema)
+// because Zod schemas are the source of truth for validation and JSON Schema
+// generation, and pi-coding-agent does not export Zod schemas.
+const llmApiKeyCredentialSchema = z.object({
+  type: z.literal('api_key'),
+  key: z.string().min(1),
+})
+
+// pi-coding-agent's OAuth credential carries provider-specific fields
+// (access, refresh, expires, plus arbitrary upstream additions). We accept
+// them as a passthrough object so future upstream additions don't break parse.
+// Upstream is the runtime authority on OAuth shape; our job here is only to
+// route the slice safely through the file envelope.
+const llmOAuthCredentialSchema = z
+  .object({
+    type: z.literal('oauth'),
+  })
+  .catchall(z.unknown())
+
+export const llmCredentialSchema = z.discriminatedUnion('type', [llmApiKeyCredentialSchema, llmOAuthCredentialSchema])
+
+// Map keyed by provider id ("openai", "openai-codex", "fireworks", ...).
+// Exactly the shape pi-coding-agent persists today as the entire secrets file.
+export const llmCredentialsSchema = z.record(z.string(), llmCredentialSchema)
+
+// Empty channels schema today; channel adapter tokens (Slack/Discord/Telegram)
+// will move here in a follow-up plan. The catchall keeps forward compatibility
+// when a future TypeClaw reads a file written by an even-newer TypeClaw.
+export const channelsSchema = z.object({}).catchall(z.unknown())
+
+export const secretsFileSchema = z.object({
+  $schema: z.string().optional(),
+  version: z.literal(1),
+  llm: llmCredentialsSchema.default({}),
+  channels: channelsSchema.default({}),
+})
+
+export type LlmCredential = z.infer<typeof llmCredentialSchema>
+export type LlmCredentials = z.infer<typeof llmCredentialsSchema>
+export type SecretsFile = z.infer<typeof secretsFileSchema>
+
+export type ParseSecretsResult = { ok: true; file: SecretsFile } | { ok: false; reason: string }
+
+// parseSecretsFile recognises two shapes:
+//   1. The new envelope: { version: 1, llm: {...}, channels: {...} }
+//   2. The legacy flat shape pi-coding-agent writes today: a top-level
+//      Record<string, AuthCredential>. Treated as { version: 1, llm: <flat>,
+//      channels: {} } so existing OAuth users transparently upgrade on the
+//      next write that goes through this code path.
+//
+// An empty object {} is a legitimate legacy state — a freshly-created
+// secrets file with no providers logged in yet. It upgrades cleanly to the
+// new envelope with empty llm and channels.
+export function parseSecretsFile(raw: unknown): ParseSecretsResult {
+  const direct = secretsFileSchema.safeParse(raw)
+  if (direct.success) return { ok: true, file: direct.data }
+
+  const legacy = llmCredentialsSchema.safeParse(raw)
+  if (legacy.success) {
+    return { ok: true, file: { version: 1, llm: legacy.data, channels: {} } }
+  }
+
+  // Neither shape matched. We surface the new-shape error because that's the
+  // target the user is presumably moving toward; the legacy path is a quiet
+  // compatibility seam, not a documented format.
+  return { ok: false, reason: direct.error.issues.map(formatIssue).join('; ') }
+}
+
+function formatIssue(issue: { path: PropertyKey[]; message: string }): string {
+  const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '<root>'
+  return `${path}: ${issue.message}`
+}

package/src/secrets/storage.ts

@@ -0,0 +1,231 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import {
+  type AuthStorage,
+  type AuthStorageBackend,
+  AuthStorage as AuthStorageImpl,
+} from '@mariozechner/pi-coding-agent'
+import lockfile from 'proper-lockfile'
+
+import { migrateLegacyAuthJson } from './migrate'
+import { type SecretsFile, parseSecretsFile } from './schema'
+
+const SCHEMA_REL = './node_modules/typeclaw/secrets.schema.json'
+const FILE_MODE = 0o600
+const DIR_MODE = 0o700
+
+const SYNC_LOCK_RETRIES = 10
+const SYNC_LOCK_DELAY_MS = 20
+
+const ASYNC_LOCK_OPTIONS = {
+  retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10000, randomize: true },
+  stale: 30000,
+} as const
+
+// SecretsBackend implements pi-coding-agent's AuthStorageBackend contract
+// while keeping TypeClaw in control of the on-disk file shape.
+//
+// Upstream's FileAuthStorageBackend assumes the entire file IS the
+// AuthStorageData (a flat Record<string, AuthCredential>). TypeClaw needs the
+// file to also carry version + channels alongside the LLM slice, so we wrap:
+// every withLock cycle reads the full envelope, presents only file.llm to the
+// AuthStorage instance as if it were the whole file, and merges the result
+// back into the envelope on write.
+//
+// Locking and durability semantics mirror upstream's FileAuthStorageBackend:
+// - proper-lockfile, sync version uses busy-loop retry on ELOCKED so callers
+//   stay synchronous (matching upstream's API contract)
+// - parent directory created with 0o700, file written with 0o600
+// - empty file is created on first access so proper-lockfile has something
+//   to lock against (it requires the target to exist)
+//
+// We additionally write atomically (temp + rename) for durability — upstream
+// uses plain writeFileSync, but we own a richer envelope and a half-write
+// would leave us with neither the old nor the new shape parseable.
+export class SecretsBackend implements AuthStorageBackend {
+  constructor(private readonly secretsPath: string) {}
+
+  withLock<T>(fn: (current: string | undefined) => { result: T; next?: string }): T {
+    this.ensureParentDir()
+    this.ensureFileExists()
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const envelope = this.readEnvelope()
+      const innerCurrent = JSON.stringify(envelope.llm, null, 2)
+
+      const { result, next } = fn(innerCurrent)
+      if (next !== undefined) {
+        const merged = mergeLlmIntoEnvelope(envelope, next)
+        this.writeEnvelopeAtomic(merged)
+      }
+      return result
+    } finally {
+      release?.()
+    }
+  }
+
+  async withLockAsync<T>(fn: (current: string | undefined) => Promise<{ result: T; next?: string }>): Promise<T> {
+    this.ensureParentDir()
+    this.ensureFileExists()
+    let release: (() => Promise<void>) | undefined
+    let lockCompromised = false
+    let lockCompromisedError: Error | undefined
+    const throwIfCompromised = (): void => {
+      if (lockCompromised) {
+        throw lockCompromisedError ?? new Error('Secrets store lock was compromised')
+      }
+    }
+    try {
+      release = await lockfile.lock(this.secretsPath, {
+        ...ASYNC_LOCK_OPTIONS,
+        onCompromised: (err: Error) => {
+          lockCompromised = true
+          lockCompromisedError = err
+        },
+      })
+      throwIfCompromised()
+      const envelope = this.readEnvelope()
+      const innerCurrent = JSON.stringify(envelope.llm, null, 2)
+
+      const { result, next } = await fn(innerCurrent)
+      throwIfCompromised()
+      if (next !== undefined) {
+        const merged = mergeLlmIntoEnvelope(envelope, next)
+        this.writeEnvelopeAtomic(merged)
+      }
+      throwIfCompromised()
+      return result
+    } finally {
+      if (release) {
+        try {
+          await release()
+        } catch {
+          // Ignore unlock errors when the lock is compromised — there is
+          // nothing useful we can do, and surfacing the secondary error would
+          // mask the primary failure (mirrors upstream behaviour).
+        }
+      }
+    }
+  }
+
+  private ensureParentDir(): void {
+    const dir = dirname(this.secretsPath)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: DIR_MODE })
+    }
+  }
+
+  // proper-lockfile requires the target to exist before locking. We seed an
+  // empty new-shape envelope so the very first call has something to lock,
+  // and so the file is parseable by a third-party reader even before the
+  // first credential is written.
+  private ensureFileExists(): void {
+    if (existsSync(this.secretsPath)) return
+    const seed = newEmptyEnvelope()
+    writeFileSync(this.secretsPath, stringifyEnvelope(seed), 'utf8')
+    chmodSync(this.secretsPath, FILE_MODE)
+  }
+
+  private acquireSyncLockWithRetry(): () => void {
+    let lastError: unknown
+    for (let attempt = 1; attempt <= SYNC_LOCK_RETRIES; attempt++) {
+      try {
+        return lockfile.lockSync(this.secretsPath, { realpath: false })
+      } catch (error) {
+        const code =
+          typeof error === 'object' && error !== null && 'code' in error
+            ? String((error as { code: unknown }).code)
+            : undefined
+        if (code !== 'ELOCKED' || attempt === SYNC_LOCK_RETRIES) throw error
+        lastError = error
+        // Busy-wait so the call stays synchronous. Matches upstream's
+        // FileAuthStorageBackend.acquireLockSyncWithRetry.
+        const start = Date.now()
+        while (Date.now() - start < SYNC_LOCK_DELAY_MS) {
+          // intentionally empty
+        }
+      }
+    }
+    throw (lastError as Error | undefined) ?? new Error('Failed to acquire secrets store lock')
+  }
+
+  private readEnvelope(): SecretsFile {
+    const raw = existsSync(this.secretsPath) ? readFileSync(this.secretsPath, 'utf8') : ''
+    if (!raw.trim()) return newEmptyEnvelope()
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch (err) {
+      throw new Error(`secrets file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`)
+    }
+    const result = parseSecretsFile(parsed)
+    if (!result.ok) {
+      throw new Error(`secrets file is not a valid TypeClaw secrets file: ${result.reason}`)
+    }
+    return result.file
+  }
+
+  // Atomic temp+rename, same pattern as src/hostd/daemon.ts:persistRegistration.
+  // The temp file lives in the same directory so rename is intra-filesystem.
+  private writeEnvelopeAtomic(envelope: SecretsFile): void {
+    const tmp = `${this.secretsPath}.${process.pid}.${Date.now()}.tmp`
+    writeFileSync(tmp, stringifyEnvelope(envelope), { encoding: 'utf8', mode: FILE_MODE })
+    try {
+      renameSync(tmp, this.secretsPath)
+    } catch (err) {
+      try {
+        unlinkSync(tmp)
+      } catch {
+        // best-effort cleanup of the temp file when rename fails
+      }
+      throw err
+    }
+    chmodSync(this.secretsPath, FILE_MODE)
+  }
+}
+
+// createSecretsStoreForAgent is the single seam every TypeClaw caller should
+// use to obtain an AuthStorage tied to an agent folder's secrets file. Keeps
+// the upstream constructor (AuthStorage.fromStorage) usage isolated to one
+// module so a future change to upstream wiring only touches this file.
+//
+// Performs the one-shot auth.json -> secrets.json rename before opening the
+// backend, so callers never observe the legacy filename even on agents that
+// pre-date the rename.
+export function createSecretsStoreForAgent(secretsPath: string): AuthStorage {
+  migrateLegacyAuthJson(dirname(secretsPath))
+  return AuthStorageImpl.fromStorage(new SecretsBackend(secretsPath))
+}
+
+function newEmptyEnvelope(): SecretsFile {
+  return { $schema: SCHEMA_REL, version: 1, llm: {}, channels: {} }
+}
+
+function stringifyEnvelope(envelope: SecretsFile): string {
+  return `${JSON.stringify(envelope, null, 2)}\n`
+}
+
+function mergeLlmIntoEnvelope(envelope: SecretsFile, nextLlmJson: string): SecretsFile {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(nextLlmJson)
+  } catch (err) {
+    throw new Error(
+      `AuthStorage produced invalid JSON for the llm slice: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error('AuthStorage produced a non-object llm slice')
+  }
+  return {
+    ...envelope,
+    $schema: envelope.$schema ?? SCHEMA_REL,
+    llm: parsed as SecretsFile['llm'],
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}