typeclaw 0.1.5 → 0.2.0

package/src/secrets/encryption.ts

@@ -0,0 +1,116 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+
+// AES-256-GCM authenticated encryption for at-rest secrets. The threat model
+// is narrow and conditional: "agent folder leaked but the effective TypeClaw
+// home (default ~/.typeclaw/, overridable via TYPECLAW_HOME) did not." That
+// covers accidental `git add secrets.json`, agent-folder backups, shared
+// mounts that expose only the agent dir. It does NOT cover (a) full host
+// compromise (the live OAuth tokens in the same secrets.json grant equivalent
+// capability), (b) whole-$HOME backups that capture both the agent dir and
+// ~/.typeclaw/, or (c) misconfiguration where TYPECLAW_HOME points inside the
+// leaked scope (e.g. inside the agent folder itself).
+//
+// AAD binds the ciphertext to the specific (containerName, accountId, version)
+// it was produced for, so a ciphertext copied between accounts or containers
+// fails authentication on decrypt even if the same key happens to unlock both.
+
+const ALGORITHM = 'AES-256-GCM' as const
+const KEY_BYTES = 32
+const IV_BYTES = 12
+const AUTH_TAG_BYTES = 16
+const ENVELOPE_VERSION = 1
+
+export type EncryptedEnvelope = {
+  v: typeof ENVELOPE_VERSION
+  alg: typeof ALGORITHM
+  kid: string
+  iv: string
+  ciphertext: string
+  authTag: string
+  createdAt: string
+}
+
+export type EncryptionContext = {
+  containerName: string
+  accountId: string
+}
+
+export class EncryptionError extends Error {
+  constructor(
+    message: string,
+    public readonly code: 'decrypt_failed' | 'envelope_invalid' | 'key_size_invalid' | 'algorithm_unsupported',
+  ) {
+    super(message)
+    this.name = 'EncryptionError'
+  }
+}
+
+export function generateKey(): Buffer {
+  return randomBytes(KEY_BYTES)
+}
+
+export function fingerprintKey(key: Buffer): string {
+  if (key.length !== KEY_BYTES) {
+    throw new EncryptionError(`key must be ${KEY_BYTES} bytes, got ${key.length}`, 'key_size_invalid')
+  }
+  return `sha256:${createHash('sha256').update(key).digest('hex').slice(0, 16)}`
+}
+
+export function encrypt(plaintext: string, key: Buffer, context: EncryptionContext): EncryptedEnvelope {
+  if (key.length !== KEY_BYTES) {
+    throw new EncryptionError(`key must be ${KEY_BYTES} bytes, got ${key.length}`, 'key_size_invalid')
+  }
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  cipher.setAAD(buildAad(context))
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  const authTag = cipher.getAuthTag()
+  return {
+    v: ENVELOPE_VERSION,
+    alg: ALGORITHM,
+    kid: fingerprintKey(key),
+    iv: iv.toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+    authTag: authTag.toString('base64'),
+    createdAt: new Date().toISOString(),
+  }
+}
+
+export function decrypt(envelope: EncryptedEnvelope, key: Buffer, context: EncryptionContext): string {
+  if (envelope.v !== ENVELOPE_VERSION) {
+    throw new EncryptionError(`unsupported envelope version: ${envelope.v}`, 'envelope_invalid')
+  }
+  if (envelope.alg !== ALGORITHM) {
+    throw new EncryptionError(`unsupported algorithm: ${envelope.alg}`, 'algorithm_unsupported')
+  }
+  if (key.length !== KEY_BYTES) {
+    throw new EncryptionError(`key must be ${KEY_BYTES} bytes, got ${key.length}`, 'key_size_invalid')
+  }
+  const iv = Buffer.from(envelope.iv, 'base64')
+  if (iv.length !== IV_BYTES) {
+    throw new EncryptionError(`iv must be ${IV_BYTES} bytes, got ${iv.length}`, 'envelope_invalid')
+  }
+  const authTag = Buffer.from(envelope.authTag, 'base64')
+  if (authTag.length !== AUTH_TAG_BYTES) {
+    throw new EncryptionError(`authTag must be ${AUTH_TAG_BYTES} bytes, got ${authTag.length}`, 'envelope_invalid')
+  }
+  const ciphertext = Buffer.from(envelope.ciphertext, 'base64')
+  const decipher = createDecipheriv('aes-256-gcm', key, iv)
+  decipher.setAAD(buildAad(context))
+  decipher.setAuthTag(authTag)
+  try {
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+    return plaintext.toString('utf8')
+  } catch (err) {
+    // GCM auth failure produces an opaque "Unsupported state or unable to
+    // authenticate data" — wrap it so callers can distinguish a wrong key /
+    // tampered blob from invariant violations on the envelope shape.
+    throw new EncryptionError(`decrypt failed: ${err instanceof Error ? err.message : String(err)}`, 'decrypt_failed')
+  }
+}
+
+// Changing this format breaks decryption of every previously-stored ciphertext.
+// See the module-header threat-model comment for the binding rationale.
+function buildAad(context: EncryptionContext): Buffer {
+  return Buffer.from(`typeclaw:kakaotalk-password:v1:${context.containerName}:${context.accountId}`, 'utf8')
+}

package/src/secrets/kakao-renewal.ts

@@ -0,0 +1,248 @@
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+import type { KakaoDeviceType } from 'agent-messenger/kakaotalk'
+
+import { decrypt, EncryptionError } from './encryption'
+import { SecretsKakaoCredentialStore } from './kakao-store'
+import { type KeyStore, KeyStoreError } from './keys'
+import { type KakaoChannelBlock } from './schema'
+import { SecretsBackend } from './storage'
+
+// Mirrors KakaoLoginResult from agent-messenger/kakaotalk's types.d.ts. The
+// upstream interface is not re-exported from the package root, so we declare
+// the structural shape locally. If a future version adds new fields, this
+// stays forward-compatible because we only read the ones declared here.
+export type KakaoLoginResult = {
+  authenticated: boolean
+  next_action?: string
+  message?: string
+  warning?: string
+  account_id?: string
+  device_type?: KakaoDeviceType
+  user_id?: string
+  error?: string
+}
+
+export const RENEWAL_THRESHOLD_MS = 5 * 24 * 60 * 60 * 1000
+
+// Hard ~7-day TTL on KakaoTalk sub-device tokens means renewal must happen
+// before that wall. We refresh at >5 days old to leave a 2-day safety margin
+// for cron skips (host asleep, daemon respawning, etc.) and to absorb any
+// downward drift in KakaoTalk's actual TTL.
+
+export type RenewalDecision =
+  | { kind: 'skip'; reason: 'no_account' | 'fresh_enough'; ageMs?: number }
+  | { kind: 'reauth_required'; reason: 'no_password' | 'no_email' | 'key_missing' | 'decrypt_failed'; message: string }
+  | { kind: 'should_renew'; account: AccountSnapshot; password: string }
+
+export type AccountSnapshot = {
+  account_id: string
+  email: string
+  device_uuid: string
+  device_type: KakaoDeviceType
+  created_at: string
+  updated_at: string
+}
+
+export type RenewalAttempt =
+  | { kind: 'ok'; account_id: string; previousUpdatedAt: string; nextUpdatedAt: string }
+  | { kind: 'reauth_required'; account_id: string; reason: string; message: string }
+  | { kind: 'transient_failure'; account_id: string; reason: string }
+
+export type AttemptLoginFn = (
+  email: string,
+  password: string,
+  deviceUuid: string,
+  deviceType: KakaoDeviceType,
+  forced: boolean,
+) => Promise<KakaoLoginResult & { credentials?: LoginCredentials }>
+
+export type LoginCredentials = {
+  access_token: string
+  refresh_token: string
+  user_id: string
+  device_uuid: string
+  device_type: KakaoDeviceType
+}
+
+export type RenewalContext = {
+  containerName: string
+  agentDir: string
+  keyStore: KeyStore
+  now?: () => number
+  attemptLogin?: AttemptLoginFn
+}
+
+export async function decideRenewal(block: KakaoChannelBlock, ctx: RenewalContext): Promise<RenewalDecision> {
+  const accountId = block.currentAccount
+  if (!accountId) return { kind: 'skip', reason: 'no_account' }
+  const account = block.accounts[accountId]
+  if (!account) return { kind: 'skip', reason: 'no_account' }
+
+  const now = (ctx.now ?? Date.now)()
+  const ageMs = now - Date.parse(account.updated_at)
+  if (Number.isFinite(ageMs) && ageMs < RENEWAL_THRESHOLD_MS) {
+    return { kind: 'skip', reason: 'fresh_enough', ageMs }
+  }
+
+  if (!account.email) {
+    return {
+      kind: 'reauth_required',
+      reason: 'no_email',
+      message: `KakaoTalk account ${accountId} has no stored email — run \`typeclaw channel reauth kakaotalk\`.`,
+    }
+  }
+  if (!account.encryptedPassword) {
+    return {
+      kind: 'reauth_required',
+      reason: 'no_password',
+      message: `KakaoTalk account ${accountId} has no stored password — run \`typeclaw channel reauth kakaotalk\`.`,
+    }
+  }
+
+  let plaintextPassword: string
+  try {
+    const key = await ctx.keyStore.read(ctx.containerName)
+    plaintextPassword = decrypt(account.encryptedPassword, key, {
+      containerName: ctx.containerName,
+      accountId: account.account_id,
+    })
+  } catch (err) {
+    return classifyDecryptFailure(err, accountId)
+  }
+
+  return {
+    kind: 'should_renew',
+    account: {
+      account_id: account.account_id,
+      email: account.email,
+      device_uuid: account.device_uuid,
+      device_type: account.device_type,
+      created_at: account.created_at,
+      updated_at: account.updated_at,
+    },
+    password: plaintextPassword,
+  }
+}
+
+export async function renewCurrentAccount(
+  ctx: RenewalContext,
+): Promise<RenewalAttempt | { kind: 'skipped'; reason: string; ageMs?: number }> {
+  const secretsPath = join(ctx.agentDir, 'secrets.json')
+  const backend = new SecretsBackend(secretsPath)
+  const block = backend.readChannelsSync()?.kakaotalk
+  const parsed = parseBlockOrEmpty(block)
+  const decision = await decideRenewal(parsed, ctx)
+
+  if (decision.kind === 'skip') {
+    return {
+      kind: 'skipped',
+      reason: decision.reason,
+      ...(decision.ageMs !== undefined ? { ageMs: decision.ageMs } : {}),
+    }
+  }
+  if (decision.kind === 'reauth_required') {
+    return {
+      kind: 'reauth_required',
+      account_id: parsed.currentAccount ?? '',
+      reason: decision.reason,
+      message: decision.message,
+    }
+  }
+
+  const attemptLogin = ctx.attemptLogin ?? (await resolveAttemptLogin())
+  const result = await attemptLogin(
+    decision.account.email,
+    decision.password,
+    decision.account.device_uuid,
+    decision.account.device_type,
+    false,
+  )
+
+  if (!result.authenticated || !result.credentials) {
+    const message = result.message ?? result.error ?? 'login did not authenticate'
+    if (result.error === 'bad_credentials' || result.next_action === 'provide_passcode') {
+      return {
+        kind: 'reauth_required',
+        account_id: decision.account.account_id,
+        reason: result.error ?? result.next_action ?? 'login_failed',
+        message,
+      }
+    }
+    return {
+      kind: 'transient_failure',
+      account_id: decision.account.account_id,
+      reason: message,
+    }
+  }
+
+  const store = new SecretsKakaoCredentialStore({ mode: 'host', secretsPath })
+  const nowIso = new Date().toISOString()
+  await store.setAccount({
+    account_id: decision.account.account_id,
+    oauth_token: result.credentials.access_token,
+    user_id: result.credentials.user_id,
+    refresh_token: result.credentials.refresh_token,
+    device_uuid: result.credentials.device_uuid,
+    device_type: result.credentials.device_type,
+    auth_method: 'login',
+    created_at: decision.account.created_at,
+    updated_at: nowIso,
+  })
+
+  return {
+    kind: 'ok',
+    account_id: decision.account.account_id,
+    previousUpdatedAt: decision.account.updated_at,
+    nextUpdatedAt: nowIso,
+  }
+}
+
+function parseBlockOrEmpty(value: unknown): KakaoChannelBlock {
+  if (value === undefined) return { currentAccount: null, accounts: {} }
+  return value as KakaoChannelBlock
+}
+
+function classifyDecryptFailure(err: unknown, accountId: string): RenewalDecision {
+  if (err instanceof KeyStoreError) {
+    if (err.code === 'missing') {
+      return {
+        kind: 'reauth_required',
+        reason: 'key_missing',
+        message: `Encryption key missing for KakaoTalk account ${accountId} — run \`typeclaw channel reauth kakaotalk\` to mint a fresh one.`,
+      }
+    }
+    return {
+      kind: 'reauth_required',
+      reason: 'key_missing',
+      message: `Encryption key for KakaoTalk account ${accountId} is unusable (${err.code}: ${err.message}). Move it aside and run \`typeclaw channel reauth kakaotalk\` to mint a fresh one.`,
+    }
+  }
+  if (err instanceof EncryptionError) {
+    return {
+      kind: 'reauth_required',
+      reason: 'decrypt_failed',
+      message: `Could not decrypt stored KakaoTalk password (${err.code}) — run \`typeclaw channel reauth kakaotalk\`.`,
+    }
+  }
+  return {
+    kind: 'reauth_required',
+    reason: 'decrypt_failed',
+    message: `Could not decrypt stored KakaoTalk password (${err instanceof Error ? err.message : String(err)}).`,
+  }
+}
+
+async function resolveAttemptLogin(): Promise<AttemptLoginFn> {
+  // agent-messenger does not export `attemptLogin` from its public exports
+  // map. Resolve the package's installed location and import the auth
+  // implementation file directly — same pattern as runKakaotalkBootstrap's
+  // loginFlow resolution in src/init/kakaotalk-auth.ts.
+  const require = createRequire(import.meta.url)
+  const pkgJson = require.resolve('agent-messenger/package.json')
+  const pkgDir = pkgJson.replace(/\/package\.json$/, '')
+  const mod = (await import(`${pkgDir}/dist/src/platforms/kakaotalk/auth/kakao-login.js`)) as {
+    attemptLogin: AttemptLoginFn
+  }
+  return mod.attemptLogin
+}

package/src/secrets/kakao-store.ts

@@ -3,9 +3,19 @@ import type { PendingLoginState } from 'agent-messenger/kakaotalk'
 
 import { sendHttp } from '@/hostd/client'
 
-import { type KakaoChannelBlock, kakaoChannelBlockSchema } from './schema'
+import { type KakaoChannelBlock, type KakaoEncryptedPassword, kakaoChannelBlockSchema } from './schema'
 import { SecretsBackend } from './storage'
 
+// Account shape accepted by setAccount(). Extends the upstream
+// KakaoAccountCredentials with the typeclaw-only renewal fields (email +
+// encrypted password). Callers that don't care about renewal can pass the
+// upstream slice unchanged; production's runKakaotalkBootstrap supplies the
+// extra fields so the renewal cron can use them.
+export type SetKakaoAccountInput = KakaoAccountCredentials & {
+  email?: string
+  encryptedPassword?: KakaoEncryptedPassword
+}
+
 export type SecretsKakaoCredentialStoreOptions =
   | { mode: 'host'; secretsPath: string }
   | { mode: 'container'; secretsPath: string; hostdUrl: string; restartToken: string; containerName: string }
@@ -25,7 +35,7 @@ export class SecretsKakaoCredentialStore {
   }
 
   async save(config: KakaoConfig): Promise<void> {
-    await this.writeBlock(() => fromKakaoConfig(config))
+    await this.writeBlock((prior) => fromKakaoConfig(config, prior))
   }
 
   async getAccount(id?: string): Promise<KakaoAccountCredentials | null> {
@@ -35,9 +45,21 @@ export class SecretsKakaoCredentialStore {
     return config.accounts[config.current_account] ?? null
   }
 
-  async setAccount(account: KakaoAccountCredentials): Promise<void> {
+  // Same as getAccount but preserves the typeclaw-only renewal fields
+  // (email + encryptedPassword). Use this when the caller cares about
+  // those fields; the bare getAccount() returns the upstream-shaped slice
+  // that the agent-messenger SDK consumes via load()/save().
+  async getAccountWithRenewalFields(id?: string): Promise<KakaoChannelBlock['accounts'][string] | null> {
+    const block = this.readBlock()
+    const accountId = id ?? block.currentAccount
+    if (!accountId) return null
+    return block.accounts[accountId] ?? null
+  }
+
+  async setAccount(account: SetKakaoAccountInput): Promise<void> {
     await this.writeBlock((block) => {
-      const accounts = { ...block.accounts, [account.account_id]: account }
+      const merged = mergeAccountPreservingRenewalFields(account, block.accounts[account.account_id])
+      const accounts = { ...block.accounts, [account.account_id]: merged }
       return { ...block, currentAccount: block.currentAccount ?? account.account_id, accounts }
     })
   }
@@ -120,10 +142,47 @@ function parseBlock(value: unknown): KakaoChannelBlock {
   return kakaoChannelBlockSchema.parse(value)
 }
 
+// Strips the typeclaw-only renewal fields (email + encryptedPassword) when
+// projecting the on-disk block to the upstream SDK's KakaoConfig shape. This
+// keeps getAccount()'s runtime contract honest with its TypeScript type, and
+// means the SDK's KakaoCredentialManager never sees fields it doesn't know
+// about (forward-compat for future SDK validation tightening).
 function toKakaoConfig(block: KakaoChannelBlock): KakaoConfig {
-  return { current_account: block.currentAccount, accounts: block.accounts }
+  const accounts: KakaoConfig['accounts'] = {}
+  for (const [id, account] of Object.entries(block.accounts)) {
+    const { email: _email, encryptedPassword: _encryptedPassword, ...upstream } = account
+    accounts[id] = upstream
+  }
+  return { current_account: block.currentAccount, accounts }
+}
+
+// The upstream KakaoConfig/KakaoAccountCredentials types have no awareness of
+// `email` or `encryptedPassword`, so any SDK-driven round-trip (save() after
+// token refresh, KakaoCredentialManager replacing a config slot) would strip
+// them. Re-attach them per-account from the prior on-disk block, keyed by
+// account_id, so token rotations preserve the renewal credentials the cron
+// depends on.
+function fromKakaoConfig(config: KakaoConfig, prior: KakaoChannelBlock): KakaoChannelBlock {
+  const accounts: KakaoChannelBlock['accounts'] = {}
+  for (const [id, account] of Object.entries(config.accounts)) {
+    accounts[id] = mergeAccountPreservingRenewalFields(account, prior.accounts[id])
+  }
+  return { ...prior, currentAccount: config.current_account, accounts }
 }
 
-function fromKakaoConfig(config: KakaoConfig): KakaoChannelBlock {
-  return { currentAccount: config.current_account, accounts: config.accounts }
+function mergeAccountPreservingRenewalFields(
+  incoming: SetKakaoAccountInput | KakaoAccountCredentials,
+  priorOnDisk: KakaoChannelBlock['accounts'][string] | undefined,
+): KakaoChannelBlock['accounts'][string] {
+  const incomingExt = incoming as SetKakaoAccountInput
+  const merged: KakaoChannelBlock['accounts'][string] = { ...incoming }
+  // Incoming wins for fields it explicitly carries (e.g. fresh login provides
+  // email + encryptedPassword); otherwise we fall back to the prior on-disk
+  // record so token-refresh round-trips through the SDK don't strip our
+  // renewal credentials.
+  if (incomingExt.email !== undefined) merged.email = incomingExt.email
+  else if (priorOnDisk?.email !== undefined) merged.email = priorOnDisk.email
+  if (incomingExt.encryptedPassword !== undefined) merged.encryptedPassword = incomingExt.encryptedPassword
+  else if (priorOnDisk?.encryptedPassword !== undefined) merged.encryptedPassword = priorOnDisk.encryptedPassword
+  return merged
 }

package/src/secrets/keys.ts

@@ -0,0 +1,173 @@
+import { existsSync } from 'node:fs'
+import { chmod, lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { fingerprintKey, generateKey } from './encryption'
+
+const KEY_FILE_MODE = 0o600
+const KEY_DIR_MODE = 0o700
+const KEY_BYTES = 32
+
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
+
+export class KeyStoreError extends Error {
+  constructor(
+    message: string,
+    public readonly code: 'invalid_name' | 'missing' | 'corrupt_size' | 'not_a_regular_file' | 'race_lost',
+  ) {
+    super(message)
+    this.name = 'KeyStoreError'
+  }
+}
+
+export type KeyStoreOptions = {
+  keysDir: string
+}
+
+// Per-agent symmetric key store. Each container/agent gets its own 32-byte
+// random key under <keysDir>/<containerName>.key (file mode 0600, dir 0700).
+// The host CLI generates and reads these; hostd reads them during scheduled
+// renewal. The container never receives the key — that's load-bearing for the
+// encryption-vs-collocation argument in encryption.ts's threat model comment.
+export function createKeyStore(opts: KeyStoreOptions): KeyStore {
+  const ensureDir = async (): Promise<void> => {
+    await mkdir(opts.keysDir, { recursive: true })
+    await chmod(opts.keysDir, KEY_DIR_MODE).catch(() => {})
+    await chmod(dirname(opts.keysDir), KEY_DIR_MODE).catch(() => {})
+  }
+
+  const keyPath = (containerName: string): string => {
+    if (!SAFE_NAME.test(containerName)) {
+      throw new KeyStoreError(`invalid container name for key file: ${JSON.stringify(containerName)}`, 'invalid_name')
+    }
+    return join(opts.keysDir, `${containerName}.key`)
+  }
+
+  return {
+    keyPath,
+
+    exists(containerName: string): boolean {
+      try {
+        return existsSync(keyPath(containerName))
+      } catch {
+        return false
+      }
+    },
+
+    async read(containerName: string): Promise<Buffer> {
+      const path = keyPath(containerName)
+      if (!existsSync(path)) {
+        throw new KeyStoreError(`key file missing: ${path}`, 'missing')
+      }
+      await assertRegularFile(path)
+      const buf = await readFile(path)
+      if (buf.length !== KEY_BYTES) {
+        throw new KeyStoreError(`key file is ${buf.length} bytes (expected ${KEY_BYTES}): ${path}`, 'corrupt_size')
+      }
+      return buf
+    },
+
+    async ensure(containerName: string): Promise<Buffer> {
+      const path = keyPath(containerName)
+      if (existsSync(path)) {
+        await assertRegularFile(path)
+        const existing = await readFile(path)
+        if (existing.length === KEY_BYTES) return existing
+        // Corrupt-size key: surface rather than silently overwrite. The user
+        // may have a backup; replacing it here would make every existing
+        // ciphertext permanently undecryptable without telling them.
+        throw new KeyStoreError(
+          `existing key file is ${existing.length} bytes (expected ${KEY_BYTES}): ${path}. ` +
+            'Move it aside and re-run reauth to mint a fresh key.',
+          'corrupt_size',
+        )
+      }
+      await ensureDir()
+      // Exclusive-create (wx flag) makes the first-write race-safe: if two
+      // processes both pass the existsSync check above and race, only one
+      // wx open of the temp file (or the final-path file via rename below)
+      // succeeds. The loser reads the winning key off disk and returns IT
+      // rather than its own bytes. Without this, the loser's
+      // secrets.json#encryptedPassword would be ciphertext for a key that
+      // just got overwritten by the winner's rename — silent
+      // undecryptable-ness.
+      const fresh = generateKey()
+      // Per-PID-and-randomized temp path so two same-process concurrent
+      // ensure() calls don't collide on the same temp file. The crypto-random
+      // suffix is the only reason same-process concurrency is safe at all.
+      const tmpSuffix = Math.random().toString(36).slice(2, 10)
+      const tmp = `${path}.${process.pid}.${tmpSuffix}.tmp`
+      try {
+        await writeFile(tmp, fresh, { mode: KEY_FILE_MODE, flag: 'wx' })
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code
+        if (code !== 'EEXIST') throw err
+        // Astronomically unlikely (same pid AND same random suffix). Treat
+        // as a corruption signal and surface; do not silently overwrite.
+        throw new KeyStoreError(`temp key path collision at ${tmp}; refusing to overwrite`, 'race_lost')
+      }
+      try {
+        // link() is atomic and refuses to overwrite an existing dest. If the
+        // dest already exists, another process won the race; link will throw
+        // EEXIST. We then unlink our tmp and read the winner's bytes.
+        const fs = await import('node:fs/promises')
+        await fs.link(tmp, path)
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code
+        const fs = await import('node:fs/promises')
+        if (code === 'EEXIST') {
+          await fs.unlink(tmp).catch(() => {})
+          if (!existsSync(path)) {
+            throw new KeyStoreError(
+              `key path ${path} reports EEXIST but is not present; refusing to retry`,
+              'race_lost',
+            )
+          }
+          await assertRegularFile(path)
+          const winner = await readFile(path)
+          if (winner.length !== KEY_BYTES) {
+            throw new KeyStoreError(
+              `race winner key at ${path} is ${winner.length} bytes (expected ${KEY_BYTES})`,
+              'race_lost',
+            )
+          }
+          return winner
+        }
+        await fs.unlink(tmp).catch(() => {})
+        throw err
+      }
+      // Clean up the temp file (the link succeeded; tmp is now a second
+      // hardlink that we no longer need). Best-effort.
+      const fs2 = await import('node:fs/promises')
+      await fs2.unlink(tmp).catch(() => {})
+      await chmod(path, KEY_FILE_MODE).catch(() => {})
+      return fresh
+    },
+
+    fingerprint(key: Buffer): string {
+      return fingerprintKey(key)
+    },
+  }
+}
+
+export type KeyStore = {
+  keyPath: (containerName: string) => string
+  exists: (containerName: string) => boolean
+  read: (containerName: string) => Promise<Buffer>
+  ensure: (containerName: string) => Promise<Buffer>
+  fingerprint: (key: Buffer) => string
+}
+
+// Reject symlinks (and other non-regular files) so a same-user attacker who
+// can write under ~/.typeclaw/keys/ can't pre-place <name>.key as a symlink
+// to another 32-byte readable file and have TypeClaw treat that file's
+// content as the encryption key. lstat refuses to follow the link itself.
+async function assertRegularFile(path: string): Promise<void> {
+  const info = await lstat(path)
+  if (!info.isFile()) {
+    throw new KeyStoreError(
+      `key path ${path} is not a regular file (mode=${info.mode.toString(8)})`,
+      'not_a_regular_file',
+    )
+  }
+}

package/src/secrets/schema.ts

@@ -40,6 +40,22 @@ const telegramBotChannelSchema = z.object({
   token: secretFieldSchema.optional(),
 })
 
+// Encrypted password envelope produced by src/secrets/encryption.ts. Optional
+// in the schema because legacy v2 accounts (pre-renewal feature) don't have
+// one; the renewal cron treats a missing envelope as "reauth required" and
+// degrades to logged warnings rather than crashing.
+const kakaoEncryptedPasswordSchema = z
+  .object({
+    v: z.literal(1),
+    alg: z.literal('AES-256-GCM'),
+    kid: z.string(),
+    iv: z.string(),
+    ciphertext: z.string(),
+    authTag: z.string(),
+    createdAt: z.string(),
+  })
+  .strict()
+
 export const kakaoAccountRecordSchema = z.object({
   account_id: z.string(),
   oauth_token: z.string(),
@@ -50,8 +66,15 @@ export const kakaoAccountRecordSchema = z.object({
   auth_method: z.union([z.literal('login'), z.literal('extract')]).optional(),
   created_at: z.string(),
   updated_at: z.string(),
+  // Renewal-feature additions. Both optional to preserve compatibility with
+  // legacy accounts; renewal degrades to "reauth required" when either is
+  // absent. See src/secrets/kakao-renewal.ts.
+  email: z.string().optional(),
+  encryptedPassword: kakaoEncryptedPasswordSchema.optional(),
 })
 
+export type KakaoEncryptedPassword = z.infer<typeof kakaoEncryptedPasswordSchema>
+
 export const kakaoPendingLoginRecordSchema = z.object({
   device_uuid: z.string(),
   device_type: z.union([z.literal('pc'), z.literal('tablet')]),