@goodandready/dsh-messenger-gateway 0.1.0 → 0.2.0

package/lib/groups.js

@@ -0,0 +1,72 @@
+/** Group/supergroup mention & reply gating for Telegram. */
+
+export function isPrivateChat(chatType) {
+  return !chatType || chatType === 'private'
+}
+
+export function isGroupChat(chatType) {
+  return chatType === 'group' || chatType === 'supergroup'
+}
+
+/** True if text entities mention @botUsername or /cmd@botUsername. */
+export function textMentionsBot(text, entities, botUsername) {
+  const uname = String(botUsername || '').replace(/^@/, '').toLowerCase()
+  if (!uname) return false
+  const body = String(text || '')
+  if (Array.isArray(entities)) {
+    for (const ent of entities) {
+      if (!ent || typeof ent.offset !== 'number' || typeof ent.length !== 'number') continue
+      const slice = body.slice(ent.offset, ent.offset + ent.length)
+      if (ent.type === 'mention' && slice.replace(/^@/, '').toLowerCase() === uname) return true
+      if (ent.type === 'text_mention' && ent.user?.is_bot && String(ent.user?.username || '').toLowerCase() === uname) return true
+      if (ent.type === 'bot_command') {
+        const cmd = slice.toLowerCase()
+        if (cmd.includes('@') && cmd.endsWith('@' + uname)) return true
+      }
+    }
+  }
+  const lower = body.toLowerCase()
+  if (lower.includes('@' + uname)) return true
+  return false
+}
+
+export function isReplyToBot(replyTo, botId) {
+  if (!replyTo?.from) return false
+  const id = Number(botId)
+  if (Number.isFinite(id) && Number(replyTo.from.id) === id) return true
+  return Boolean(replyTo.from.is_bot)
+}
+
+/**
+ * Decide whether the gateway should process this inbound message.
+ * Private: always. Groups: only if enabled + (mention | reply-to-bot | command).
+ */
+export function shouldProcessTelegramMessage({
+  chatType,
+  text,
+  entities,
+  replyTo,
+  botId,
+  botUsername,
+  groupsEnabled = true,
+  requireMention = true,
+}) {
+  if (isPrivateChat(chatType)) return { ok: true, reason: 'private' }
+  if (!isGroupChat(chatType)) return { ok: false, reason: 'unsupported-chat' }
+  if (!groupsEnabled) return { ok: false, reason: 'groups-disabled' }
+  const body = String(text || '').trim()
+  if (body.startsWith('/')) return { ok: true, reason: 'command' }
+  if (isReplyToBot(replyTo, botId)) return { ok: true, reason: 'reply-to-bot' }
+  if (!requireMention) return { ok: true, reason: 'groups-open' }
+  if (textMentionsBot(body, entities, botUsername)) return { ok: true, reason: 'mention' }
+  return { ok: false, reason: 'no-mention' }
+}
+
+/** Strip @bot from /cmd@bot for command parsing. */
+export function stripBotCommandSuffix(text, botUsername) {
+  const raw = String(text || '')
+  const uname = String(botUsername || '').replace(/^@/, '')
+  if (!uname) return raw
+  const escaped = uname.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return raw.replace(new RegExp('^(/[a-z0-9_]+)@' + escaped + '\\b', 'i'), '$1')
+}

package/lib/homes.js

@@ -0,0 +1,58 @@
+import { normalizeThreadId } from "./topics.js"
+
+export function normalizeHomeName(name) {
+  return String(name || "").trim().toLowerCase().replace(/\s+/g, "-").slice(0, 32)
+}
+
+/** Legacy single home + named list → unified list. */
+export function listHomes(tg = {}) {
+  const out = []
+  const seen = new Set()
+  const push = (name, chatId, threadId) => {
+    const n = normalizeHomeName(name) || "default"
+    if (seen.has(n)) return
+    if (chatId === undefined || chatId === null || String(chatId).trim() === "") return
+    seen.add(n)
+    out.push({ name: n, chatId, threadId: normalizeThreadId(threadId) })
+  }
+  const homes = Array.isArray(tg.homes) ? tg.homes : []
+  for (const h of homes) {
+    if (!h || typeof h !== "object") continue
+    push(h.name || h.id, h.chatId, h.threadId)
+  }
+  // legacy fields as default if not already present
+  if (tg.homeChatId !== undefined && tg.homeChatId !== null && String(tg.homeChatId).trim() !== "") {
+    push("default", tg.homeChatId, tg.homeThreadId)
+  }
+  return out
+}
+
+export function resolveNamedHome(tg, nameOrTarget) {
+  const homes = listHomes(tg)
+  if (!homes.length) return null
+  if (!nameOrTarget) return homes.find((h) => h.name === "default") || homes[0]
+  if (typeof nameOrTarget === "object") {
+    if (nameOrTarget.chatId != null && String(nameOrTarget.chatId).trim() !== "") {
+      return {
+        name: normalizeHomeName(nameOrTarget.name) || "custom",
+        chatId: nameOrTarget.chatId,
+        threadId: normalizeThreadId(nameOrTarget.threadId),
+      }
+    }
+    nameOrTarget = nameOrTarget.name || nameOrTarget.home
+  }
+  const want = normalizeHomeName(nameOrTarget)
+  return homes.find((h) => h.name === want) || null
+}
+
+export function upsertHome(tg, { name, chatId, threadId }) {
+  const n = normalizeHomeName(name) || "default"
+  const homes = listHomes(tg).filter((h) => h.name !== n)
+  homes.push({ name: n, chatId, threadId: normalizeThreadId(threadId) })
+  const next = { ...tg, homes }
+  if (n === "default") {
+    next.homeChatId = chatId
+    next.homeThreadId = normalizeThreadId(threadId)
+  }
+  return next
+}

package/lib/index.js

@@ -1,52 +1,21 @@
-import z from '@deepseek-ai/schemastery'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { defineTool } from '@deepseek-ai/dsh-tools'
 import { Gateway } from './gateway.js'
 import { readBody, writeJson, isTrustedSettingsRequest } from './http.js'
 import {
   createMessengerService, dispatchMessenger, httpStatusForError,
   messengerApiSchema, parseMessengerBody,
 } from './messenger-api.js'
+import { listHomes } from './homes.js'
+import { Config } from './config.js'
 
 export const name = 'dsh-messenger-gateway'
-export const inject = ['agentDefaultModel', 'agents', 'sessions', 'loader', 'settings', 'webServer', 'attachments']
+export const inject = ['agentDefaultModel', 'agents', 'sessions', 'loader', 'settings', 'webServer', 'attachments', 'tools']
 
 export const SETTINGS_NAMESPACE = settingsNamespace('dsh-messenger-gateway')
-
-export const Config = z.object({
-  enabled: z.boolean().default(true),
-  internalBaseURL: z.string().default('http://127.0.0.1:3080'),
-  telegram: z.object({
-    enabled: z.boolean().default(false),
-    botToken: z.string().role('secret').default(''),
-    allowedUserIds: z.array(z.number()).default([]),
-    pollTimeoutSeconds: z.number().default(50),
-    pollIntervalMs: z.number().default(500),
-  }),
-  discord: z.object({
-    enabled: z.boolean().default(false),
-    botToken: z.string().role('secret').default(''),
-  }),
-  media: z.object({
-    cacheDir: z.string().default(''),
-    maxDocBytes: z.number().default(20 * 1024 * 1024),
-    maxTextInjectBytes: z.number().default(100 * 1024),
-    maxImageBytes: z.number().default(20 * 1024 * 1024),
-  }),
-  tts: z.object({
-    enabled: z.boolean().default(false),
-    maxChars: z.number().default(4000),
-  }),
-  agent: z.object({
-    provider: z.string().default(''),
-    model: z.string().default(''),
-    cwd: z.string().default(''),
-    instructionPrefix: z.string().default(''),
-    maxMessageLength: z.number().default(4000),
-    idleTimeoutMs: z.number().default(3_600_000),
-  }),
-})
+export { Config }
 
 function resolveConfig(raw) {
   const cfg = Config(raw)
@@ -66,12 +35,44 @@ function publicConfig(cfg) {
       allowedUserIds: cfg.telegram.allowedUserIds,
       pollTimeoutSeconds: cfg.telegram.pollTimeoutSeconds,
       pollIntervalMs: cfg.telegram.pollIntervalMs,
+      commands: cfg.telegram.commands,
+      textFormat: cfg.telegram.textFormat,
+      homeChatId: cfg.telegram.homeChatId,
+      homeThreadId: cfg.telegram.homeThreadId,
+      homes: listHomes(cfg.telegram),
+      pairingEnabled: cfg.telegram.pairingEnabled,
+      streaming: cfg.telegram.streaming,
+      progressEnabled: cfg.telegram.progressEnabled,
+      approvalsEnabled: cfg.telegram.approvalsEnabled,
+      groupsEnabled: cfg.telegram.groupsEnabled,
+      groupRequireMention: cfg.telegram.groupRequireMention,
+      reactionsEnabled: cfg.telegram.reactionsEnabled,
+      transport: cfg.telegram.transport,
+      webhookUrl: cfg.telegram.webhookUrl,
+      webhookPath: cfg.telegram.webhookPath,
+      webhookSecretConfigured: Boolean(String(cfg.telegram.webhookSecret || '').trim()),
       botTokenConfigured: Boolean(String(cfg.telegram.botToken || '').trim()),
+      voiceMode: cfg.telegram.voiceMode,
+      notifyBridge: {
+        enabled: Boolean(cfg.telegram.notifyBridge?.enabled),
+        events: cfg.telegram.notifyBridge?.events || ['task_done', 'error'],
+        home: cfg.telegram.notifyBridge?.home || 'default',
+        excludeSessionPrefixes: cfg.telegram.notifyBridge?.excludeSessionPrefixes || ['msgw-'],
+      },
     },
     discord: { enabled: cfg.discord.enabled, botTokenConfigured: Boolean(String(cfg.discord.botToken || '').trim()) },
     media: { maxDocBytes: cfg.media.maxDocBytes, maxTextInjectBytes: cfg.media.maxTextInjectBytes, maxImageBytes: cfg.media.maxImageBytes },
     tts: cfg.tts,
-    agent: cfg.agent,
+    agent: {
+      provider: cfg.agent.provider,
+      model: cfg.agent.model,
+      photoOnlyMode: cfg.agent.photoOnlyMode,
+      maxMessageLength: cfg.agent.maxMessageLength,
+      turnTimeoutMs: cfg.agent.turnTimeoutMs,
+      idleTimeoutMs: cfg.agent.idleTimeoutMs,
+      instructionPrefix: cfg.agent.instructionPrefix,
+      sessionScope: cfg.agent.sessionScope,
+    },
   }
 }
 
@@ -96,17 +97,59 @@ function registerMessengerRoute(ctx, getGw, path, action) {
   }), `dsh-messenger-gateway: ${action}`)
 }
 
+function isExcludedSession(sessionId, prefixes) {
+  const sid = String(sessionId || '')
+  for (const p of prefixes || []) {
+    if (typeof p === 'string' && p.length > 0 && sid.startsWith(p)) return true
+  }
+  return false
+}
+
 export function apply(ctx, config) {
   const entry = resolveConfig(structuredClone(config || {}))
   let gateway
   let source = () => entry
   let settingsApi
+  const turnStarts = new Map()
 
   const sync = () => {
     if (gateway) { gateway.stop(); gateway = undefined }
     const effective = source()
     if (effective.enabled === false) return
-    gateway = new Gateway(ctx, effective)
+    gateway = new Gateway(ctx, effective, {
+      persistAllowedUserIds: async (ids) => {
+        if (!settingsApi) return
+        const cur = source()
+        await settingsApi.replace(Config({
+          ...cur,
+          telegram: { ...cur.telegram, allowedUserIds: ids },
+        }))
+      },
+      persistHome: async ({ chatId, threadId }) => {
+        if (!settingsApi) throw new Error('settings not ready')
+        const cur = source()
+        await settingsApi.replace(Config({
+          ...cur,
+          telegram: { ...cur.telegram, homeChatId: chatId, homeThreadId: threadId || 0 },
+        }))
+      },
+      persistHomes: async (nextTelegram) => {
+        if (!settingsApi) throw new Error('settings not ready')
+        const cur = source()
+        await settingsApi.replace(Config({
+          ...cur,
+          telegram: { ...cur.telegram, ...nextTelegram },
+        }))
+      },
+      persistAgentModel: async ({ provider, model }) => {
+        if (!settingsApi) return
+        const cur = source()
+        await settingsApi.replace(Config({
+          ...cur,
+          agent: { ...cur.agent, provider, model },
+        }))
+      },
+    })
     gateway.start().catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: ${err.message}`))
   }
 
@@ -120,6 +163,91 @@ export function apply(ctx, config) {
 
   ctx.effect(() => ctx.provide('messenger', createMessengerService(getGw)), 'dsh-messenger-gateway: messenger service')
 
+  // Agent tool: inline buttons in the telegram chat bound to this msgw session
+  if (ctx.tools?.register) {
+    ctx.effect(() => ctx.tools.register(defineTool({
+      name: 'messenger_ask',
+      description:
+        'Ask the Telegram user a multiple-choice question with inline buttons and wait for their choice. '
+        + 'Use for confirmations and short choices. Only works inside messenger-gateway sessions (msgw-*).',
+      parameters: {
+        text: { type: 'string', required: true, description: 'Question text shown in Telegram.' },
+        buttons: {
+          type: 'array',
+          required: true,
+          description: 'Rows of buttons: [[{ id, text }, ...], ...]',
+        },
+        timeoutMs: { type: 'number', description: 'Wait timeout ms (default 300000).' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean' },
+            buttonId: { type: 'string' },
+            data: { type: 'string' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [{
+          type: 'text',
+          text: value && value.ok
+            ? `User chose: ${value.buttonId}`
+            : `messenger_ask failed: ${value && value.error ? value.error : 'unknown'}`,
+        }],
+      },
+      execute: async (args, exec) => {
+        const gw = getGw()
+        if (!gw) return { ok: false, error: 'gateway not running' }
+        try {
+          const buttons = args.buttons
+          const result = await gw.messengerAskFromAgent(exec.agent, {
+            text: String(args.text || ''),
+            buttons,
+          }, Number(args.timeoutMs) || 300_000)
+          return { ok: true, buttonId: result?.buttonId, data: result?.data }
+        } catch (err) {
+          return { ok: false, error: err instanceof Error ? err.message : String(err) }
+        }
+      },
+    })), 'dsh-messenger-gateway: messenger_ask tool')
+  }
+
+  // Notify → Telegram home bridge (non-msgw sessions only)
+  ctx.effect(() => ctx.on('session/event', (session, event) => {
+    const cfg = source().telegram?.notifyBridge
+    if (!cfg?.enabled) return
+    if (event.type === 'turn/start') {
+      turnStarts.set(String(session.id), Date.now())
+      return
+    }
+    if (event.type !== 'turn/end') return
+    const prefixes = cfg.excludeSessionPrefixes || ['msgw-']
+    if (isExcludedSession(session.id, prefixes)) return
+    const reason = event.data?.reason
+    const kind = reason?.kind === 'completed' ? 'task_done' : 'error'
+    const events = new Set(cfg.events?.length ? cfg.events : ['task_done', 'error'])
+    if (!events.has(kind)) return
+    const gw = getGw()
+    if (!gw) return
+    const started = turnStarts.get(String(session.id))
+    turnStarts.delete(String(session.id))
+    const dur = started ? Math.round((Date.now() - started) / 1000) : null
+    const title = kind === 'task_done' ? 'Задача завершена' : 'Ошибка агента'
+    const lines = [
+      `【${title}】`,
+      `session: ${session.id}`,
+    ]
+    if (dur != null) lines.push(`duration: ${dur}s`)
+    if (reason?.kind === 'error') {
+      lines.push(`error: ${reason.error?.message || reason.error?.code || 'unknown'}`)
+    }
+    const homeName = cfg.home || 'default'
+    gw.messengerSend({ platform: 'telegram', home: homeName }, { text: lines.join('\n') })
+      .catch((e) => ctx.logger?.warn?.(`notify bridge: ${e.message}`))
+  }), 'dsh-messenger-gateway: notify bridge')
+
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact', path: '/dsh-messenger-gateway/status',
     handler: async (req, res) => {
@@ -132,6 +260,9 @@ export function apply(ctx, config) {
         activeChats: gw?.messenger.activeChats() || 0,
         ttsEnabled: Boolean(source().tts?.enabled),
         messengerService: 'messenger',
+        home: gateway?.messenger.home?.() || null,
+        homes: gateway?.messenger.homes?.() || [],
+        pairingPending: gw?.messenger.pairingPending?.()?.length || 0,
         config: publicConfig(source()),
       })
     },
@@ -156,7 +287,23 @@ export function apply(ctx, config) {
       try { payload = JSON.parse((await readBody(req)).toString('utf8') || '{}') } catch { return writeJson(res, 400, { ok: false, error: 'invalid json' }) }
       if (payload && typeof payload.config === 'object') payload = payload.config
       try {
-        await settingsApi.replace(Config({ ...source(), ...payload }))
+        const cur = source()
+        const nextTg = { ...cur.telegram, ...(payload.telegram || {}) }
+        if (payload.telegram && !String(payload.telegram.botToken || '').trim()) nextTg.botToken = cur.telegram.botToken
+        if (payload.telegram && Object.prototype.hasOwnProperty.call(payload.telegram, 'webhookSecret') && !String(payload.telegram.webhookSecret || '').trim()) {
+          nextTg.webhookSecret = cur.telegram.webhookSecret
+        }
+        if (payload.telegram?.notifyBridge) {
+          nextTg.notifyBridge = { ...cur.telegram.notifyBridge, ...payload.telegram.notifyBridge }
+        }
+        await settingsApi.replace(Config({
+          ...cur,
+          ...payload,
+          telegram: nextTg,
+          tts: { ...cur.tts, ...(payload.tts || {}) },
+          agent: { ...cur.agent, ...(payload.agent || {}) },
+          media: { ...cur.media, ...(payload.media || {}) },
+        }))
         sync()
         writeJson(res, 200, { ok: true, config: publicConfig(source()) })
       } catch (err) {
@@ -165,6 +312,81 @@ export function apply(ctx, config) {
     },
   }), 'dsh-messenger-gateway: config')
 
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/pairing',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
+      if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'forbidden' })
+      const gw = getGw()
+      if (!gw) return writeJson(res, 503, { ok: false, error: 'gateway not running' })
+      writeJson(res, 200, {
+        ok: true,
+        pending: gw.messenger.pairingPending(),
+        approved: gw.messenger.pairingApproved(),
+      })
+    },
+  }), 'dsh-messenger-gateway: pairing list')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/pairing/approve',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'forbidden' })
+      const gw = getGw()
+      if (!gw) return writeJson(res, 503, { ok: false, error: 'gateway not running' })
+      let payload
+      try { payload = JSON.parse((await readBody(req)).toString('utf8') || '{}') } catch { return writeJson(res, 400, { ok: false, error: 'invalid json' }) }
+      const resu = await gw.approvePairingCode(payload.code)
+      writeJson(res, resu.ok ? 200 : 400, resu)
+    },
+  }), 'dsh-messenger-gateway: pairing approve')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/pairing/reject',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'forbidden' })
+      const gw = getGw()
+      if (!gw) return writeJson(res, 503, { ok: false, error: 'gateway not running' })
+      let payload
+      try { payload = JSON.parse((await readBody(req)).toString('utf8') || '{}') } catch { return writeJson(res, 400, { ok: false, error: 'invalid json' }) }
+      const resu = gw.rejectPairingCode(payload.code)
+      writeJson(res, resu.ok ? 200 : 400, resu)
+    },
+  }), 'dsh-messenger-gateway: pairing reject')
+
+  const webhookPath = () => {
+    const p = String(source().telegram?.webhookPath || '').trim()
+    return p || '/dsh-messenger-gateway/telegram/webhook'
+  }
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: webhookPath(),
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      const cfg = source().telegram || {}
+      if (cfg.transport !== 'webhook') return writeJson(res, 404, { ok: false, error: 'webhook transport disabled' })
+      const secret = String(cfg.webhookSecret || '').trim()
+      if (secret) {
+        const hdr = String(req.headers['x-telegram-bot-api-secret-token'] || '')
+        if (hdr !== secret) return writeJson(res, 403, { ok: false, error: 'bad secret' })
+      }
+      const gw = getGw()
+      const adapter = gw?.getAdapter?.('telegram')
+      if (!adapter?.handleWebhookUpdate) return writeJson(res, 503, { ok: false, error: 'telegram adapter unavailable' })
+      let update
+      try { update = JSON.parse((await readBody(req)).toString('utf8') || '{}') } catch {
+        return writeJson(res, 400, { ok: false, error: 'invalid json' })
+      }
+      try {
+        await adapter.handleWebhookUpdate(update)
+        writeJson(res, 200, { ok: true })
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: err.message })
+      }
+    },
+  }), 'dsh-messenger-gateway: telegram webhook')
+
   registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/send', 'send')
   registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/progress', 'progress')
   registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/ask', 'ask')

package/lib/messenger-api.js

@@ -60,12 +60,12 @@ export function validateTarget(target) {
     throw err
   }
   const chatId = target.chatId
-  if (chatId === undefined || chatId === null || String(chatId).trim() === '') {
-    const err = new Error('target.chatId is required')
-    err.status = 400
-    throw err
+  const out = { platform }
+  if (chatId !== undefined && chatId !== null && String(chatId).trim() !== '') {
+    out.chatId = chatId
   }
-  const out = { platform, chatId }
+  const home = String(target.home || target.name || '').trim()
+  if (home) out.home = home
   const threadId = normalizeThreadId(target.threadId)
   if (threadId > 0) out.threadId = threadId
   return out

package/lib/pairing.js

@@ -0,0 +1,110 @@
+import { randomBytes } from 'node:crypto'
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+
+export function generatePairingCode(length = 8) {
+  const bytes = randomBytes(length)
+  let out = ''
+  for (let i = 0; i < length; i++) out += ALPHABET[bytes[i] % ALPHABET.length]
+  return out
+}
+
+export function createPairingStore(filePath) {
+  const state = { pending: {}, /** @type {number[]} */ approved: [] }
+  if (filePath && existsSync(filePath)) {
+    try {
+      const raw = JSON.parse(readFileSync(filePath, 'utf8'))
+      if (Array.isArray(raw.approved)) state.approved = raw.approved.map(Number).filter(Number.isFinite)
+      if (raw.pending && typeof raw.pending === 'object') state.pending = raw.pending
+    } catch {}
+  }
+  const persist = () => {
+    if (!filePath) return
+    mkdirSync(dirname(filePath), { recursive: true })
+    writeFileSync(filePath, JSON.stringify({ approved: state.approved, pending: state.pending }, null, 2))
+  }
+  const prune = () => {
+    const now = Date.now()
+    for (const [code, row] of Object.entries(state.pending)) {
+      if (!row || now > Number(row.expiresAt || 0)) delete state.pending[code]
+    }
+  }
+  return {
+    listApproved: () => [...state.approved],
+    listPending: () => {
+      prune()
+      return Object.entries(state.pending).map(([code, row]) => ({
+        code,
+        userId: Number(row.userId),
+        username: String(row.username || ''),
+        createdAt: Number(row.createdAt) || 0,
+        expiresAt: Number(row.expiresAt) || 0,
+      })).sort((a, b) => a.createdAt - b.createdAt)
+    },
+    isApproved: (userId) => state.approved.includes(Number(userId)),
+    addApproved: (userId) => {
+      const id = Number(userId)
+      if (!Number.isFinite(id)) return false
+      if (!state.approved.includes(id)) {
+        state.approved.push(id)
+        persist()
+      }
+      return true
+    },
+    requestCode(userId, meta = {}) {
+      prune()
+      const uid = Number(userId)
+      for (const [code, row] of Object.entries(state.pending)) {
+        if (Number(row.userId) === uid && Date.now() < Number(row.expiresAt)) return { code, reused: true, ...row }
+      }
+      const recent = Object.values(state.pending).find((r) => Number(r.userId) === uid && Date.now() - Number(r.createdAt || 0) < 600_000)
+      if (recent) {
+        const err = new Error('pairing rate limited')
+        err.code = 'RATE_LIMIT'
+        throw err
+      }
+      if (Object.keys(state.pending).length >= 20) {
+        const err = new Error('too many pending pairing codes')
+        err.code = 'FULL'
+        throw err
+      }
+      const code = generatePairingCode()
+      const row = {
+        userId: uid,
+        username: String(meta.username || ''),
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 3_600_000,
+      }
+      state.pending[code] = row
+      persist()
+      return { code, reused: false, ...row }
+    },
+    approveCode(code, actorUserId) {
+      prune()
+      const key = String(code || '').trim().toUpperCase()
+      const row = state.pending[key]
+      if (!row) return { ok: false, error: 'unknown or expired code' }
+      if (Date.now() > Number(row.expiresAt)) {
+        delete state.pending[key]
+        persist()
+        return { ok: false, error: 'code expired' }
+      }
+      delete state.pending[key]
+      const id = Number(row.userId)
+      if (Number.isFinite(id) && !state.approved.includes(id)) state.approved.push(id)
+      persist()
+      return { ok: true, userId: row.userId, username: row.username, actorUserId: Number(actorUserId) }
+    },
+    rejectCode(code) {
+      prune()
+      const key = String(code || '').trim().toUpperCase()
+      if (!state.pending[key]) return { ok: false, error: 'unknown or expired code' }
+      const row = state.pending[key]
+      delete state.pending[key]
+      persist()
+      return { ok: true, userId: row.userId, username: row.username }
+    },
+  }
+}