typeclaw 0.1.1 → 0.1.3

package/src/secrets/schema.ts

@@ -1,72 +1,192 @@
 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({
+import { CHANNEL_ENV_TO_FIELD } from './defaults'
+import { secretFieldSchema, type Secret } from './resolve'
+
+// providers.<id> for api-key credentials: the `key` field is a Secret (string
+// shorthand or `{ value?, env? }` object). resolveSecret turns this into a
+// flat string at read time so AuthStorage (which expects `key: string`)
+// stays happy. OAuth credentials carry stateful refresh/access tokens that
+// are not env-injectable, so they pass through unchanged via catchall.
+const apiKeyProviderSchema = z.object({
   type: z.literal('api_key'),
-  key: z.string().min(1),
+  key: secretFieldSchema,
 })
 
-// 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
+const oauthProviderSchema = z
   .object({
     type: z.literal('oauth'),
   })
   .catchall(z.unknown())
 
-export const llmCredentialSchema = z.discriminatedUnion('type', [llmApiKeyCredentialSchema, llmOAuthCredentialSchema])
+export const providerCredentialSchema = z.discriminatedUnion('type', [apiKeyProviderSchema, oauthProviderSchema])
+
+export const providersSchema = z.record(z.string(), providerCredentialSchema)
+
+// Per-adapter channel slots use named fields (`botToken`, `appToken`, `token`)
+// instead of env-var-name keys. The Secret union per field carries the env-var
+// override. Unknown adapter ids pass through via catchall so a future
+// plugin-contributed adapter doesn't fail validation.
+const slackBotChannelSchema = z.object({
+  botToken: secretFieldSchema.optional(),
+  appToken: secretFieldSchema.optional(),
+})
+
+const discordBotChannelSchema = z.object({
+  token: secretFieldSchema.optional(),
+})
+
+const telegramBotChannelSchema = z.object({
+  token: secretFieldSchema.optional(),
+})
+
+export const kakaoAccountRecordSchema = z.object({
+  account_id: z.string(),
+  oauth_token: z.string(),
+  user_id: z.string(),
+  refresh_token: z.string().optional(),
+  device_uuid: z.string(),
+  device_type: z.union([z.literal('pc'), z.literal('tablet')]),
+  auth_method: z.union([z.literal('login'), z.literal('extract')]).optional(),
+  created_at: z.string(),
+  updated_at: z.string(),
+})
+
+export const kakaoPendingLoginRecordSchema = z.object({
+  device_uuid: z.string(),
+  device_type: z.union([z.literal('pc'), z.literal('tablet')]),
+  email: z.string(),
+  created_at: z.string(),
+})
 
-// 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)
+export const kakaoChannelBlockSchema = z.object({
+  currentAccount: z.string().nullable(),
+  accounts: z.record(z.string(), kakaoAccountRecordSchema),
+  pendingLogin: kakaoPendingLoginRecordSchema.optional(),
+})
 
-// 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 channelsSchema = z
+  .object({
+    'slack-bot': slackBotChannelSchema.optional(),
+    'discord-bot': discordBotChannelSchema.optional(),
+    'telegram-bot': telegramBotChannelSchema.optional(),
+    kakaotalk: kakaoChannelBlockSchema.optional(),
+  })
+  .catchall(z.unknown())
+
+// version 2 = providers.* with Secret-typed api-key.key + per-adapter
+// channel field shapes. version 1 = the previous shape (flat `llm.*`, channel
+// slots keyed by env-var name). Legacy v1 input is upgraded transparently by
+// parseSecretsFile; the first write persists v2.
+export const SECRETS_FILE_VERSION = 2
 
 export const secretsFileSchema = z.object({
   $schema: z.string().optional(),
-  version: z.literal(1),
-  llm: llmCredentialsSchema.default({}),
+  version: z.literal(SECRETS_FILE_VERSION),
+  providers: providersSchema.default({}),
   channels: channelsSchema.default({}),
 })
 
-export type LlmCredential = z.infer<typeof llmCredentialSchema>
-export type LlmCredentials = z.infer<typeof llmCredentialsSchema>
+export type ProviderCredential = z.infer<typeof providerCredentialSchema>
+export type Providers = z.infer<typeof providersSchema>
+export type Channels = z.infer<typeof channelsSchema>
+export type KakaoAccountRecord = z.infer<typeof kakaoAccountRecordSchema>
+export type PendingLoginRecord = z.infer<typeof kakaoPendingLoginRecordSchema>
+export type KakaoChannelBlock = z.infer<typeof kakaoChannelBlockSchema>
 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.
+// parseSecretsFile recognises three shapes, in priority order:
+//   1. The v2 envelope (current): { version: 2, providers, channels }
+//   2. The v1 envelope (legacy): { version: 1, llm, channels } where channel
+//      slots are keyed by env-var name. Both `llm` and `channels` get
+//      reshaped — llm -> providers, env-keyed channel slots -> field-keyed.
+//   3. The pre-envelope flat shape (very legacy): Record<string, AuthCredential>
+//      at top level. Treated as { version: 2, providers: <flat>, channels: {} }
+//      so existing OAuth users transparently upgrade.
 //
-// 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.
+// Every legacy upgrade produces a v2-shaped SecretsFile in memory; the next
+// write persists v2 to disk. The legacy branches stay forever as a quiet
+// compatibility seam — only the v2 form is documented.
 export function parseSecretsFile(raw: unknown): ParseSecretsResult {
-  const direct = secretsFileSchema.safeParse(raw)
-  if (direct.success) return { ok: true, file: direct.data }
+  const v2 = secretsFileSchema.safeParse(raw)
+  if (v2.success) return { ok: true, file: v2.data }
+
+  const v1 = legacyV1Schema.safeParse(raw)
+  if (v1.success) return { ok: true, file: upgradeV1ToV2(v1.data) }
+
+  const flat = legacyFlatProviderSchema.safeParse(raw)
+  if (flat.success) {
+    return { ok: true, file: upgradeV1ToV2({ version: 1, llm: flat.data, channels: {} }) }
+  }
 
-  const legacy = llmCredentialsSchema.safeParse(raw)
-  if (legacy.success) {
-    return { ok: true, file: { version: 1, llm: legacy.data, channels: {} } }
+  return { ok: false, reason: v2.error.issues.map(formatIssue).join('; ') }
+}
+
+// Legacy v1 schema: `llm` (flat string-key) and `channels` (env-var-keyed
+// flat map per adapter). Used only for upgrade reads; never written.
+const legacyV1ApiKeySchema = z.object({
+  type: z.literal('api_key'),
+  key: z.string().min(1),
+})
+
+const legacyV1OAuthSchema = z
+  .object({
+    type: z.literal('oauth'),
+  })
+  .catchall(z.unknown())
+
+const legacyV1CredentialSchema = z.discriminatedUnion('type', [legacyV1ApiKeySchema, legacyV1OAuthSchema])
+
+const legacyV1LlmSchema = z.record(z.string(), legacyV1CredentialSchema)
+
+const legacyV1ChannelsSchema = z.record(z.string(), z.record(z.string(), z.string()))
+
+const legacyV1Schema = z.object({
+  $schema: z.string().optional(),
+  version: z.literal(1),
+  llm: legacyV1LlmSchema.default({}),
+  channels: legacyV1ChannelsSchema.default({}),
+})
+
+const legacyFlatProviderSchema = z.record(z.string(), legacyV1CredentialSchema)
+
+function upgradeV1ToV2(legacy: z.infer<typeof legacyV1Schema>): SecretsFile {
+  const providers: Providers = {}
+  for (const [providerId, cred] of Object.entries(legacy.llm)) {
+    if (cred.type === 'api_key') {
+      providers[providerId] = { type: 'api_key', key: { value: cred.key } }
+    } else {
+      providers[providerId] = cred
+    }
   }
 
-  // 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('; ') }
+  const channels: Channels = {}
+  for (const [adapterId, envKeyedSlot] of Object.entries(legacy.channels)) {
+    const upgradedSlot: Record<string, Secret> = {}
+    for (const [envKey, value] of Object.entries(envKeyedSlot)) {
+      const mapping = CHANNEL_ENV_TO_FIELD[envKey]
+      if (mapping && mapping.adapterId === adapterId) {
+        upgradedSlot[mapping.fieldName] = { value }
+      } else {
+        // Unknown env-var-name key on a known adapter, or an adapter we don't
+        // recognise: pass through verbatim under the original key. Better to
+        // preserve user data than drop it; the catchall on channelsSchema
+        // makes this safe.
+        upgradedSlot[envKey] = { value }
+      }
+    }
+    channels[adapterId] = upgradedSlot
+  }
+
+  const result: SecretsFile = {
+    version: SECRETS_FILE_VERSION,
+    providers,
+    channels,
+  }
+  if (legacy.$schema !== undefined) result.$schema = legacy.$schema
+  return result
 }
 
 function formatIssue(issue: { path: PropertyKey[]; message: string }): string {

package/src/secrets/storage.ts

@@ -8,8 +8,17 @@ import {
 } from '@mariozechner/pi-coding-agent'
 import lockfile from 'proper-lockfile'
 
+import { providerKeyDefaultEnv } from './defaults'
 import { migrateLegacyAuthJson } from './migrate'
-import { type SecretsFile, parseSecretsFile } from './schema'
+import { resolveSecret, type Secret } from './resolve'
+import {
+  type Channels,
+  type ProviderCredential,
+  type Providers,
+  type SecretsFile,
+  SECRETS_FILE_VERSION,
+  parseSecretsFile,
+} from './schema'
 
 const SCHEMA_REL = './node_modules/typeclaw/secrets.schema.json'
 const FILE_MODE = 0o600
@@ -23,26 +32,44 @@ const ASYNC_LOCK_OPTIONS = {
   stale: 30000,
 } as const
 
-// SecretsBackend implements pi-coding-agent's AuthStorageBackend contract
-// while keeping TypeClaw in control of the on-disk file shape.
+// SecretsBackend bridges TypeClaw's on-disk envelope (v2: providers with
+// Secret-typed keys, channels with per-adapter field shapes) to upstream
+// `AuthStorage`'s flat `Record<provider, AuthCredential>` contract.
 //
-// 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.
+// READ (withLock's `current` parameter):
+//   - Parse the envelope, walk `providers`, resolve each api-key `Secret` to
+//     a flat string via env-wins (process.env wins over file value).
+//   - OAuth credentials pass through untouched.
+//   - Capture the resolved string for each provider into `readSnapshot` so
+//     the write path can detect "unchanged" without re-resolving (the env
+//     can change between read and write, and re-resolving would misclassify
+//     env mutations as credential mutations).
+//   - Hand AuthStorage a flat-shape JSON string. Upstream is none the wiser.
 //
-// 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)
+// WRITE (the `next` field):
+//   - AuthStorage hands back the full flat slice as JSON. We do NOT
+//     wholesale-replace the on-disk `providers` slice with this.
+//   - Instead, we DIFF at credential level against the prior envelope using
+//     the read-time `readSnapshot`:
+//       * Provider unchanged (flatKey === readSnapshot[providerId]) → preserve
+//         on-disk Secret bytes verbatim (no flatten, no rewrap). This is the
+//         idempotency rule that prevents OAuth-refresh from accidentally
+//         persisting env-resolved api-key values into the file.
+//       * Provider changed → rewrap as Secret, preserving any prior `env`
+//         field the user authored.
+//       * Provider added → write as string shorthand (no env binding).
+//       * Provider removed → actually remove (do NOT resurrect).
+//   - OAuth credentials stay flat strings in the envelope (no Secret
+//     wrapping) — they're not env-injectable.
+//   - Unknown credential `type` values pass through verbatim, in case
+//     upstream adds a third type in a future release.
+//   - Empty/missing `key` from AuthStorage on api-key is treated as no-op
+//     (preserve prior on-disk Secret if any). The schema requires non-empty
+//     `value`, so writing an empty key would corrupt the file at next read.
 //
-// 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.
+// Locking and durability mirror upstream's FileAuthStorageBackend: sync
+// busy-loop retry on ELOCKED to keep callers synchronous, 0o600 file, 0o700
+// parent, atomic temp+rename.
 export class SecretsBackend implements AuthStorageBackend {
   constructor(private readonly secretsPath: string) {}
 
@@ -53,11 +80,11 @@ export class SecretsBackend implements AuthStorageBackend {
     try {
       release = this.acquireSyncLockWithRetry()
       const envelope = this.readEnvelope()
-      const innerCurrent = JSON.stringify(envelope.llm, null, 2)
+      const { flatJson, readSnapshot } = flattenProvidersForAuthStorage(envelope.providers, process.env)
 
-      const { result, next } = fn(innerCurrent)
+      const { result, next } = fn(flatJson)
       if (next !== undefined) {
-        const merged = mergeLlmIntoEnvelope(envelope, next)
+        const merged = mergeProvidersIntoEnvelope(envelope, next, readSnapshot)
         this.writeEnvelopeAtomic(merged)
       }
       return result
@@ -87,12 +114,12 @@ export class SecretsBackend implements AuthStorageBackend {
       })
       throwIfCompromised()
       const envelope = this.readEnvelope()
-      const innerCurrent = JSON.stringify(envelope.llm, null, 2)
+      const { flatJson, readSnapshot } = flattenProvidersForAuthStorage(envelope.providers, process.env)
 
-      const { result, next } = await fn(innerCurrent)
+      const { result, next } = await fn(flatJson)
       throwIfCompromised()
       if (next !== undefined) {
-        const merged = mergeLlmIntoEnvelope(envelope, next)
+        const merged = mergeProvidersIntoEnvelope(envelope, next, readSnapshot)
         this.writeEnvelopeAtomic(merged)
       }
       throwIfCompromised()
@@ -110,6 +137,92 @@ export class SecretsBackend implements AuthStorageBackend {
     }
   }
 
+  readChannelsSync(): Channels {
+    this.ensureParentDir()
+    this.ensureFileExists()
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      return this.readEnvelope().channels
+    } finally {
+      release?.()
+    }
+  }
+
+  tryReadChannelsSync(): Channels | null {
+    if (!existsSync(this.secretsPath)) return null
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      return this.readEnvelope().channels
+    } finally {
+      release?.()
+    }
+  }
+
+  writeChannelsSync(next: Channels): void {
+    this.ensureParentDir()
+    this.ensureFileExists()
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const envelope = this.readEnvelope()
+      const merged: SecretsFile = {
+        ...envelope,
+        $schema: envelope.$schema ?? SCHEMA_REL,
+        version: SECRETS_FILE_VERSION,
+        channels: next,
+      }
+      this.writeEnvelopeAtomic(merged)
+    } finally {
+      release?.()
+    }
+  }
+
+  async updateChannelsAsync<T>(
+    fn: (current: Record<string, unknown>) => Promise<{ result: T; next?: Record<string, unknown> }>,
+  ): 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 { result, next } = await fn(envelope.channels as Record<string, unknown>)
+      throwIfCompromised()
+      if (next !== undefined) {
+        const merged: SecretsFile = {
+          ...envelope,
+          $schema: envelope.$schema ?? SCHEMA_REL,
+          channels: next as SecretsFile['channels'],
+        }
+        this.writeEnvelopeAtomic(merged)
+      }
+      throwIfCompromised()
+      return result
+    } finally {
+      if (release) {
+        try {
+          await release()
+        } catch {}
+      }
+    }
+  }
+
   private ensureParentDir(): void {
     const dir = dirname(this.secretsPath)
     if (!existsSync(dir)) {
@@ -117,10 +230,6 @@ export class SecretsBackend implements AuthStorageBackend {
     }
   }
 
-  // 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()
@@ -140,11 +249,9 @@ export class SecretsBackend implements AuthStorageBackend {
             : 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
+          // intentionally empty: synchronous busy-wait to match upstream contract
         }
       }
     }
@@ -167,8 +274,6 @@ export class SecretsBackend implements AuthStorageBackend {
     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 })
@@ -186,44 +291,145 @@ export class SecretsBackend implements AuthStorageBackend {
   }
 }
 
-// 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: {} }
+  return { $schema: SCHEMA_REL, version: SECRETS_FILE_VERSION, providers: {}, channels: {} }
 }
 
 function stringifyEnvelope(envelope: SecretsFile): string {
   return `${JSON.stringify(envelope, null, 2)}\n`
 }
 
-function mergeLlmIntoEnvelope(envelope: SecretsFile, nextLlmJson: string): SecretsFile {
+type ReadSnapshot = Map<string, string>
+
+// Build the flat shape AuthStorage expects, resolving Secret-typed api-key
+// keys to plain strings on the way out. Also capture each resolved api-key
+// value into a snapshot keyed by providerId; the write path uses this
+// snapshot (NOT a re-resolution against current process.env) to detect
+// untouched providers. OAuth and unknown types are passed through verbatim
+// and never enter the snapshot — they don't participate in env-wins.
+function flattenProvidersForAuthStorage(
+  providers: Providers,
+  env: NodeJS.ProcessEnv,
+): { flatJson: string; readSnapshot: ReadSnapshot } {
+  const flat: Record<string, unknown> = {}
+  const readSnapshot: ReadSnapshot = new Map()
+  for (const [providerId, cred] of Object.entries(providers)) {
+    if (cred.type === 'api_key') {
+      const defaultEnv = providerKeyDefaultEnv(providerId)
+      const resolved = resolveSecret(cred.key, defaultEnv, env) ?? cred.key.value ?? ''
+      flat[providerId] = { type: 'api_key', key: resolved }
+      readSnapshot.set(providerId, resolved)
+    } else {
+      flat[providerId] = cred
+    }
+  }
+  return { flatJson: JSON.stringify(flat, null, 2), readSnapshot }
+}
+
+// Diff-and-preserve merge per the bridge idempotency rule. AuthStorage hands
+// back the full flat provider slice; we walk it credential-by-credential and
+// decide for each provider whether to:
+//   - preserve the prior on-disk Secret bytes verbatim (untouched provider,
+//     detected by comparing AuthStorage's flat value to the read-time
+//     snapshot, NOT a re-resolution against current env),
+//   - reconstruct as Secret with prior `env` preserved (api-key value changed),
+//   - write as new shape (provider added),
+// and we drop providers that disappeared from the flat slice (real removal).
+function mergeProvidersIntoEnvelope(
+  envelope: SecretsFile,
+  nextProvidersJson: string,
+  readSnapshot: ReadSnapshot,
+): SecretsFile {
   let parsed: unknown
   try {
-    parsed = JSON.parse(nextLlmJson)
+    parsed = JSON.parse(nextProvidersJson)
   } catch (err) {
     throw new Error(
-      `AuthStorage produced invalid JSON for the llm slice: ${err instanceof Error ? err.message : String(err)}`,
+      `AuthStorage produced invalid JSON for the providers slice: ${err instanceof Error ? err.message : String(err)}`,
     )
   }
   if (!isPlainObject(parsed)) {
-    throw new Error('AuthStorage produced a non-object llm slice')
+    throw new Error('AuthStorage produced a non-object providers slice')
   }
+
+  const nextProviders: Providers = {}
+  for (const [providerId, raw] of Object.entries(parsed)) {
+    const reconstructed = reconstructProviderCredential(
+      raw,
+      envelope.providers[providerId],
+      readSnapshot.get(providerId),
+    )
+    if (reconstructed !== undefined) {
+      nextProviders[providerId] = reconstructed
+    }
+  }
+
   return {
     ...envelope,
     $schema: envelope.$schema ?? SCHEMA_REL,
-    llm: parsed as SecretsFile['llm'],
+    version: SECRETS_FILE_VERSION,
+    providers: nextProviders,
+  }
+}
+
+function reconstructProviderCredential(
+  raw: unknown,
+  priorOnDisk: ProviderCredential | undefined,
+  resolvedAtRead: string | undefined,
+): ProviderCredential | undefined {
+  if (!isPlainObject(raw)) return undefined
+  const type = raw['type']
+
+  if (type === 'api_key') {
+    const flatKey = typeof raw['key'] === 'string' ? raw['key'] : ''
+
+    // Empty/missing key from AuthStorage on an api-key credential cannot
+    // round-trip: the schema requires `value` to be non-empty, so writing
+    // `{ value: '' }` would make the file unparseable on next read. Treat
+    // it as "no-op" and preserve the prior on-disk Secret if any. A real
+    // deletion comes through as the provider being absent from `next`,
+    // which is handled by the caller dropping it.
+    if (flatKey === '') {
+      if (priorOnDisk !== undefined) return priorOnDisk
+      return undefined
+    }
+
+    // Idempotency: if AuthStorage's flat key matches the resolved value
+    // captured at read time, the credential is untouched. Preserve the
+    // on-disk Secret verbatim — including any `env` binding and any string
+    // shorthand the user authored. Comparing against the read-time snapshot
+    // (not a re-resolution against current process.env) is what makes this
+    // safe against env mutations between read and write.
+    if (priorOnDisk && priorOnDisk.type === 'api_key' && resolvedAtRead === flatKey) {
+      return priorOnDisk
+    }
+
+    // Mutation path: rewrap as Secret, preserving the user's `env` binding
+    // when prior was also an api-key so the next boot's env-wins still
+    // consults the right variable.
+    if (priorOnDisk && priorOnDisk.type === 'api_key' && priorOnDisk.key.env !== undefined) {
+      return { type: 'api_key', key: { value: flatKey, env: priorOnDisk.key.env } satisfies Secret }
+    }
+
+    return { type: 'api_key', key: { value: flatKey } }
   }
+
+  if (type === 'oauth') {
+    // OAuth credentials are not env-injectable. Pass through verbatim,
+    // preserving every upstream-controlled field (access, refresh, expires,
+    // and any future additions covered by the catchall).
+    return raw as ProviderCredential
+  }
+
+  // Unknown credential type. Pass through verbatim as a defensive measure
+  // against upstream adding a third type in a future release. Better to
+  // round-trip user data than drop it.
+  return raw as ProviderCredential
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {