@lf_maple/koishi-plugin-phi-plugin-full 0.1.80

package/core/model/theme/marketClient.js

@@ -0,0 +1,294 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import Config from '../../components/Config.js'
+import makeRequest from '../api/makeRequest.js'
+import { classifyApiConnectionError } from '../api/phiApiErrors.js'
+
+const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024
+const AUTH_ATTEMPTS = 3
+const DOWNLOAD_ATTEMPTS = 2
+const DOWNLOAD_TIMEOUT_MS = 60_000
+
+export class ThemeMarketClientError extends Error {
+    /** @param {string} code @param {number} [status] */
+    constructor(code, status = 0) {
+        super(code)
+        this.name = 'ThemeMarketClientError'
+        this.code = code
+        this.status = status
+    }
+}
+
+const SLUG_RE = /^[a-z][a-z0-9_-]{0,119}$/
+
+/** @param {unknown} value */
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * The API has shipped both response-level and theme-level capability fields.
+ * Accept either layout, but never guess when the field is absent or conflicts.
+ * @param {any} response
+ * @param {any} theme
+ */
+export function resolveBotDownloadAllowed(response, theme) {
+    const hasResponseValue = isRecord(response) && Object.hasOwn(response, 'botDownloadAllowed')
+    const hasThemeValue = isRecord(theme) && Object.hasOwn(theme, 'botDownloadAllowed')
+    const responseValue = hasResponseValue ? response.botDownloadAllowed : undefined
+    const themeValue = hasThemeValue ? theme.botDownloadAllowed : undefined
+    if (
+        hasResponseValue && typeof responseValue !== 'boolean'
+        || hasThemeValue && typeof themeValue !== 'boolean'
+        || !hasResponseValue && !hasThemeValue
+        || hasResponseValue && hasThemeValue && responseValue !== themeValue
+    ) {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    return /** @type {boolean} */ (hasThemeValue ? themeValue : responseValue)
+}
+
+/** @param {any} theme @param {boolean} botDownloadAllowed */
+function validateTheme(theme, botDownloadAllowed) {
+    if (!isRecord(theme)
+        || typeof theme.slug !== 'string' || !SLUG_RE.test(theme.slug)
+        || typeof theme.name !== 'string' || !theme.name.trim() || theme.name.length > 100
+        || !['public', 'restricted', 'bot_only'].includes(theme.downloadPolicy)) {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    return { ...theme, name: theme.name.trim(), botDownloadAllowed }
+}
+
+export async function getAvailableMarketThemes() {
+    const response = await makeRequest.getThemeMarketList()
+    if (!isRecord(response) || response.ok !== true || !Array.isArray(response.themes) || response.themes.length > 500) {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    return response.themes.map((/** @type {any} */ theme) => validateTheme(
+        theme,
+        resolveBotDownloadAllowed(response, theme),
+    ))
+}
+
+/** @param {string} themeId */
+export async function getAvailableMarketTheme(themeId) {
+    const response = await makeRequest.getThemeMarketDetail(themeId)
+    if (!isRecord(response) || response.ok !== true || !isRecord(response.theme)) {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    const theme = validateTheme(response.theme, resolveBotDownloadAllowed(response, response.theme))
+    if (theme.slug !== themeId) throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    if (!theme.botDownloadAllowed) throw new ThemeMarketClientError('theme_not_allowed_by_bot', 403)
+    return theme
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/** @param {any} error @param {number} attempt */
+function retryDelay(error, attempt) {
+    const raw = error?.data?.retryAfter
+    if (raw) {
+        const seconds = Number(raw)
+        const date = Date.parse(raw)
+        const value = Number.isFinite(seconds) ? seconds * 1000 : date - Date.now()
+        if (Number.isFinite(value)) return Math.max(0, Math.min(value, 15_000))
+    }
+    return 250 * (2 ** attempt) + Math.floor(Math.random() * 150)
+}
+
+/** @param {any} error */
+function retryableAuthorization(error) {
+    const status = Number(error?.status || 0)
+    return status === 0 || [408, 425, 429].includes(status) || status >= 500
+}
+
+function configuredDownloadOrigin() {
+    const raw = String(Config.getUserCfg('config', 'themeMarketDownloadOrigin') || '').trim()
+    let url
+    try {
+        url = new URL(raw)
+    } catch {
+        throw new ThemeMarketClientError('theme_market_origin_invalid')
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash || url.search || url.pathname !== '/') {
+        throw new ThemeMarketClientError('theme_market_origin_invalid')
+    }
+    return url.origin
+}
+
+/** @param {any} value @param {string} themeId */
+function validateDownload(value, themeId) {
+    const download = value?.download
+    let url
+    try {
+        url = new URL(download?.downloadUrl)
+    } catch {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    if (
+        value?.ok !== true
+        || typeof download?.downloadId !== 'string'
+        || download.downloadId.length < 1
+        || download.downloadId.length > 128
+        || download.themeId !== themeId
+        || typeof download.version !== 'string'
+        || download.version.length < 1
+        || download.version.length > 64
+        || typeof download.fileName !== 'string'
+        || download.fileName.length < 1
+        || download.fileName.length > 255
+        || /[\\/\u0000-\u001f\u007f]/.test(download.fileName)
+        || download.contentType !== 'application/zip'
+        || !Number.isSafeInteger(download.size)
+        || download.size <= 0
+        || download.size > MAX_ARCHIVE_BYTES
+        || !/^[a-f0-9]{64}$/.test(download.sha256)
+        || !Number.isFinite(Date.parse(download.expiresAt))
+        || Date.parse(download.expiresAt) <= Date.now()
+        || url.protocol !== 'https:'
+        || url.origin !== configuredDownloadOrigin()
+        || url.username
+        || url.password
+        || url.hash
+    ) {
+        throw new ThemeMarketClientError('theme_store_invalid_response', 502)
+    }
+    return {
+        downloadId: download.downloadId,
+        themeId: download.themeId,
+        version: download.version,
+        fileName: download.fileName,
+        contentType: 'application/zip',
+        size: download.size,
+        sha256: download.sha256,
+        downloadUrl: url.toString(),
+        expiresAt: download.expiresAt,
+    }
+}
+
+/**
+ * @param {string} themeId
+ * @param {string} [requestId]
+ */
+export async function authorizeThemeDownload(themeId, requestId = crypto.randomUUID()) {
+    for (let attempt = 0; attempt < AUTH_ATTEMPTS; attempt++) {
+        try {
+            const response = await makeRequest.requestThemeDownload({ requestId, themeId })
+            return validateDownload(response, themeId)
+        } catch (error) {
+            if (!retryableAuthorization(error) || attempt + 1 >= AUTH_ATTEMPTS) throw error
+            await sleep(retryDelay(error, attempt))
+        }
+    }
+    throw new ThemeMarketClientError('theme_store_unavailable', 503)
+}
+
+/** @param {fs.promises.FileHandle} handle @param {Uint8Array} chunk @param {number} position */
+async function writeChunk(handle, chunk, position) {
+    let written = 0
+    while (written < chunk.byteLength) {
+        const result = await handle.write(chunk, written, chunk.byteLength - written, position + written)
+        if (result.bytesWritten <= 0) throw new ThemeMarketClientError('theme_download_write_failed')
+        written += result.bytesWritten
+    }
+}
+
+/**
+ * @param {ReturnType<typeof validateDownload>} download
+ * @param {string} targetPath
+ * @param {{fetchImpl?:typeof fetch}} [options]
+ */
+export async function downloadThemeArchive(download, targetPath, options = {}) {
+    const fetchImpl = options.fetchImpl || fetch
+    let lastError = null
+    for (let attempt = 0; attempt < DOWNLOAD_ATTEMPTS; attempt++) {
+        if (Date.parse(download.expiresAt) <= Date.now()) {
+            throw new ThemeMarketClientError('theme_download_url_expired', 410)
+        }
+        await fs.promises.rm(targetPath, { force: true }).catch(() => {})
+        let handle
+        try {
+            const url = new URL(download.downloadUrl)
+            if (url.origin !== configuredDownloadOrigin() || url.protocol !== 'https:' || url.username || url.password || url.hash) {
+                throw new ThemeMarketClientError('theme_download_url_untrusted')
+            }
+            let response
+            try {
+                response = await fetchImpl(url, {
+                    method: 'GET',
+                    headers: { Accept: 'application/zip' },
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+                })
+            } catch (error) {
+                throw classifyApiConnectionError(error)
+            }
+            if ([401, 403, 410].includes(response.status)) {
+                await response.body?.cancel()
+                throw new ThemeMarketClientError('theme_download_url_expired', response.status)
+            }
+            if (!response.ok) {
+                await response.body?.cancel()
+                const error = new ThemeMarketClientError('theme_download_unavailable', response.status)
+                // @ts-ignore response headers are deliberately reduced to the one retry hint
+                error.retryAfter = response.headers.get('retry-after')
+                throw error
+            }
+            if (!response.body) throw new ThemeMarketClientError('theme_download_empty')
+            const contentType = response.headers.get('content-type')?.split(';', 1)[0].trim()
+            const contentLength = response.headers.get('content-length')
+            if (contentType !== 'application/zip' || (contentLength !== null && contentLength !== String(download.size))) {
+                await response.body.cancel()
+                throw new ThemeMarketClientError('theme_package_integrity_failed')
+            }
+
+            handle = await fs.promises.open(targetPath, 'wx', 0o600)
+            const reader = response.body.getReader()
+            const hash = crypto.createHash('sha256')
+            let total = 0
+            while (true) {
+                let chunk
+                try {
+                    chunk = await reader.read()
+                } catch (error) {
+                    throw classifyApiConnectionError(error)
+                }
+                const { done, value } = chunk
+                if (done) break
+                if (!value) continue
+                total += value.byteLength
+                if (total > download.size || total > MAX_ARCHIVE_BYTES) {
+                    await reader.cancel()
+                    throw new ThemeMarketClientError('theme_package_integrity_failed')
+                }
+                await writeChunk(handle, value, total - value.byteLength)
+                hash.update(value)
+            }
+            await handle.sync()
+            await handle.close()
+            handle = undefined
+            if (total !== download.size || hash.digest('hex') !== download.sha256) {
+                throw new ThemeMarketClientError('theme_package_integrity_failed')
+            }
+            return targetPath
+        } catch (error) {
+            lastError = error
+            await handle?.close().catch(() => {})
+            await fs.promises.rm(targetPath, { force: true }).catch(() => {})
+            const caught = /** @type {any} */ (error)
+            const status = Number(caught?.status || 0)
+            const retryable = !(error instanceof ThemeMarketClientError)
+                || error.code === 'theme_download_unavailable' && ([408, 425, 429].includes(status) || status >= 500)
+            if (!retryable || attempt + 1 >= DOWNLOAD_ATTEMPTS) throw error
+            const rawRetryAfter = caught?.retryAfter
+            const delay = rawRetryAfter && Number.isFinite(Number(rawRetryAfter))
+                ? Math.min(Number(rawRetryAfter) * 1000, 15_000)
+                : 250 * (2 ** attempt) + Math.floor(Math.random() * 150)
+            await sleep(delay)
+        }
+    }
+    throw lastError || new ThemeMarketClientError('theme_download_unavailable')
+}

package/core/model/theme/paths.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import YAML from 'yaml'
+import { pluginResources } from '../filesystem/path.js'
+
+export const themesDir = path.join(pluginResources, 'themes')
+
+const legacyThemeDirs = [
+    path.join(pluginResources, 'html', 'b19', 'res', 'themes'),
+    path.join(pluginResources, 'html', 'b19', 'themes'),
+]
+const THEME_ID_RE = /^[a-zA-Z0-9_-]+$/
+const RESERVED_IDS = new Set(['default', 'snow', 'star', 'dss2', 'topText', 'foolsDay'])
+
+/**
+ * Move themes from historical resource locations and normalize each folder to
+ * its declared theme id. Existing destinations are never overwritten.
+ * @returns {{from:string,to:string}[]}
+ */
+export function migrateLegacyThemeDirectories() {
+    fs.mkdirSync(themesDir, { recursive: true, mode: 0o700 })
+    /** @type {{from:string,to:string}[]} */
+    const moved = []
+    for (const root of [...legacyThemeDirs, themesDir]) {
+        if (!fs.existsSync(root)) continue
+        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith('.phi-market-')) continue
+            const source = path.join(root, entry.name)
+            let id = ''
+            try {
+                const info = YAML.parse(fs.readFileSync(path.join(source, 'info.yaml'), 'utf8'))
+                id = typeof info?.id === 'string' ? info.id : ''
+            } catch { continue }
+            if (!THEME_ID_RE.test(id) || RESERVED_IDS.has(id)) continue
+            const destination = path.join(themesDir, id)
+            if (path.resolve(source) === path.resolve(destination) || fs.existsSync(destination)) continue
+            fs.renameSync(source, destination)
+            moved.push({ from: source, to: destination })
+        }
+    }
+    return moved
+}

package/core/model/theme/policy.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { dataPath } from '../filesystem/path.js'
+
+const SLUG_RE = /^[a-z][a-z0-9_-]{0,119}$/
+
+export class ThemePolicyCache {
+    /** @param {string} filePath */
+    constructor(filePath) {
+        this.filePath = filePath
+        this.mode = 'blacklist'
+        /** @type {Set<string>} */
+        this.entries = new Set()
+        this.load()
+    }
+
+    load() {
+        try {
+            const value = JSON.parse(fs.readFileSync(this.filePath, 'utf8'))
+            this.apply(value, false)
+        } catch { /* empty blacklist is the safe, documented default */ }
+    }
+
+    /** @param {any} value @param {boolean} [persist=true] */
+    apply(value, persist = true) {
+        if (!value || !['blacklist', 'whitelist'].includes(value.mode) || !Array.isArray(value.entries)) return false
+        const entries = value.entries
+            .filter((/** @type {unknown} */ entry) => typeof entry === 'string' && SLUG_RE.test(entry))
+            .slice(0, 500)
+        this.mode = value.mode
+        this.entries = new Set(entries)
+        if (persist) this.save()
+        return true
+    }
+
+    save() {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true })
+        const temporary = `${this.filePath}.${process.pid}.tmp`
+        fs.writeFileSync(temporary, JSON.stringify({ mode: this.mode, entries: [...this.entries].sort() }), { mode: 0o600 })
+        fs.renameSync(temporary, this.filePath)
+    }
+
+    /** @param {string} slug */
+    isAllowed(slug) {
+        const contains = this.entries.has(slug)
+        return this.mode === 'blacklist' ? !contains : contains
+    }
+
+    snapshot() {
+        return { mode: this.mode, entries: [...this.entries] }
+    }
+}
+
+export default new ThemePolicyCache(path.join(dataPath, 'theme-policy.json'))

package/core/model/theme/recovery.js

@@ -0,0 +1,167 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import YAML from 'yaml'
+import { migrateLegacyThemeDirectories, themesDir } from './paths.js'
+
+const WORK_DIR = path.join(themesDir, '.phi-market-work')
+const WORK_STALE_MS = 60 * 60_000
+const UUID_PATTERN = '[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}'
+
+/** @param {string} receiptPath */
+export async function readMarketReceipt(receiptPath) {
+    try {
+        const value = JSON.parse(await fs.promises.readFile(receiptPath, 'utf8'))
+        if (value?.source !== 'phi-theme-marketplace' || typeof value?.slug !== 'string'
+            || typeof value?.version !== 'string' || !/^[a-f0-9]{64}$/.test(value?.sha256)) return null
+        return value
+    } catch {
+        return null
+    }
+}
+
+/** @param {string} value */
+const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** @param {string} themeId @param {string} entryName */
+function isThemeBackupName(themeId, entryName) {
+    return new RegExp(`^\\.phi-market-backup-${escapeRegExp(themeId)}-${UUID_PATTERN}$`, 'i').test(entryName)
+}
+
+/** @param {string} entryName */
+export function getBackupThemeId(entryName) {
+    const match = new RegExp(`^\\.phi-market-backup-([a-z][a-z0-9_-]{0,119})-${UUID_PATTERN}$`, 'i').exec(entryName)
+    return match?.[1] || null
+}
+
+/**
+ * @param {string} directory
+ * @param {string} themeId
+ * @returns {Promise<{exists:boolean,healthy:boolean,marketOwned:boolean,receipt:any}>}
+ */
+async function inspectMarketThemeDirectory(directory, themeId) {
+    const stat = await fs.promises.lstat(directory).catch(() => null)
+    if (!stat) return { exists: false, healthy: false, marketOwned: false, receipt: null }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        return { exists: true, healthy: false, marketOwned: false, receipt: null }
+    }
+
+    const receiptPath = path.join(directory, '.phi-market.json')
+    const receiptMarker = await fs.promises.lstat(receiptPath).catch(() => null)
+    const receipt = await readMarketReceipt(receiptPath)
+    let info = null
+    try {
+        info = YAML.parse(await fs.promises.readFile(path.join(directory, 'info.yaml'), 'utf8'))
+    } catch { }
+    return {
+        exists: true,
+        healthy: info?.id === themeId && receipt?.slug === themeId,
+        // This marker is reserved for marketplace installs. A truncated marker
+        // still distinguishes an interrupted install from a same-name local theme.
+        marketOwned: Boolean(receiptMarker?.isFile()),
+        receipt,
+    }
+}
+
+/** @param {boolean} [force] @param {string} [workDirectory] */
+export async function cleanStaleMarketWork(force = false, workDirectory = WORK_DIR) {
+    const now = Date.now()
+    const entries = await fs.promises.readdir(workDirectory, { withFileTypes: true }).catch(error => {
+        if (/** @type {any} */ (error)?.code === 'ENOENT') return []
+        throw error
+    })
+    for (const entry of entries) {
+        const fullPath = path.join(workDirectory, entry.name)
+        const stat = await fs.promises.stat(fullPath).catch(() => null)
+        if (stat && (force || now - stat.mtimeMs > WORK_STALE_MS)) {
+            await fs.promises.rm(fullPath, { recursive: true, force: true })
+        }
+    }
+}
+
+/** @param {string} themeId */
+export async function recoverMarketInstall(themeId) {
+    migrateLegacyThemeDirectories()
+    await fs.promises.mkdir(WORK_DIR, { recursive: true, mode: 0o700 })
+    const target = path.join(themesDir, themeId)
+    const entries = await fs.promises.readdir(themesDir, { withFileTypes: true })
+    const backups = entries.filter(entry => entry.isDirectory() && isThemeBackupName(themeId, entry.name))
+    const candidates = await Promise.all(backups.map(async entry => {
+        const fullPath = path.join(themesDir, entry.name)
+        return {
+            fullPath,
+            stat: await fs.promises.stat(fullPath),
+            state: await inspectMarketThemeDirectory(fullPath, themeId),
+        }
+    }))
+    const healthyBackups = candidates
+        .filter(item => item.state.healthy)
+        .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
+    let targetState = await inspectMarketThemeDirectory(target, themeId)
+    let recovered = false
+
+    if ((!targetState.exists || targetState.marketOwned) && !targetState.healthy && healthyBackups.length) {
+        const recoverable = healthyBackups[0]
+        let displaced = ''
+        if (targetState.exists) {
+            displaced = path.join(WORK_DIR, `corrupt-${themeId}-${crypto.randomUUID()}`)
+            await fs.promises.rename(target, displaced)
+        }
+        try {
+            await fs.promises.rename(recoverable.fullPath, target)
+            targetState = await inspectMarketThemeDirectory(target, themeId)
+            if (!targetState.healthy) throw new Error(`Recovered theme ${themeId} failed validation`)
+            recovered = true
+            if (displaced) await fs.promises.rm(displaced, { recursive: true, force: true })
+        } catch (error) {
+            const restoredBackup = await fs.promises.lstat(target).catch(() => null)
+            if (restoredBackup) await fs.promises.rename(target, recoverable.fullPath).catch(() => {})
+            if (displaced) await fs.promises.rename(displaced, target).catch(() => {})
+            throw error
+        }
+    }
+
+    // Never discard a backup until a healthy marketplace target is present.
+    // A same-name local theme blocks recovery but does not destroy the backup.
+    if (targetState.healthy) {
+        for (const candidate of candidates) {
+            await fs.promises.rm(candidate.fullPath, { recursive: true, force: true })
+        }
+    }
+    return { recovered, healthy: targetState.healthy }
+}
+
+/**
+ * Recover every interrupted directory swap before the first theme scan.
+ * `cleanAllWork` is safe only while the global install lock is held.
+ * @param {{cleanAllWork?:boolean}} [options]
+ */
+export async function recoverAllMarketInstalls(options = {}) {
+    await fs.promises.mkdir(themesDir, { recursive: true, mode: 0o700 })
+    const entries = await fs.promises.readdir(themesDir, { withFileTypes: true })
+    const themeIds = new Set(entries
+        .filter(entry => entry.isDirectory())
+        .map(entry => getBackupThemeId(entry.name))
+        .filter(Boolean))
+    /** @type {{themeId:string,error:unknown}[]} */
+    const failures = []
+    for (const themeId of themeIds) {
+        try {
+            await recoverMarketInstall(/** @type {string} */ (themeId))
+        } catch (error) {
+            failures.push({ themeId: /** @type {string} */ (themeId), error })
+        }
+    }
+    try {
+        await cleanStaleMarketWork(options.cleanAllWork === true)
+        if (options.cleanAllWork) {
+            for (const entry of entries) {
+                if (!entry.isDirectory() || !/^\.phi-market-restore-[a-zA-Z0-9]+$/.test(entry.name)) continue
+                await fs.promises.rm(path.join(themesDir, entry.name), { recursive: true, force: true })
+            }
+        }
+    } catch (error) {
+        failures.push({ themeId: '.phi-market-work', error })
+    }
+    return failures
+}