Skip to content
LibCheckerPublic

Repository files navigation

LibChecker APK Bot and Web UI

This repository contains two deployable parts:

Part Path Platform Purpose
tgbot packages/bot-worker/ Cloudflare Workers Telegram bot, APK link preview, WebUI upload guidance, report rendering, webhook/admin APIs.
Web UI packages/apk-webui/ Cloudflare Pages Standalone browser APK analyzer powered by the same parser and LibChecker rules.
Local MCP packages/apk-mcp/ Node >=24 / stdio Offline local APK analysis for desktop MCP clients.
Shared analyzer packages/shared/ Worker and Pages APK parser, signature parser, SDK marker runtime, and generated local bundles.

tgbot

The Worker bot accepts APK links and guides local APK, APKS, APKM, and XAPK uploads to the Web UI. Link previews return a short Telegram summary and a full LibChecker-style report page.

Key capabilities:

  • Telegram webhook handling for private chats, groups, and channels.
  • Range-based APK link preview parsing for manifest, resources, permissions, components, and native libraries.
  • LibChecker-Rules-Bundle matching for SDK names, icons, and component markers.
  • /upload guidance to the browser Web UI for local APK, APKS, APKM, and XAPK files.
  • Protected admin APIs for webhook and command-menu management.
  • Structured Worker logs and Analytics Engine events.

Web UI

The Pages app is a separate browser-first APK analyzer. It runs the analysis locally in the browser through a Web Worker, so APK files do not need to be sent to the Telegram bot flow.

Key capabilities:

  • Local APK analysis in the browser.
  • Shared parser and generated local LibChecker rule bundles.
  • Static Cloudflare Pages deployment.
  • Independent development and deployment commands.

Usage

  • Send an APK download link for range-based preview parsing.
  • Reply to an APK link with /apkinfo.
  • Use /upload for local APK, APKS, APKM, and XAPK files.
  • Open the Web UI when you want browser-only local analysis.

Group behavior depends on Telegram Privacy Mode. For the most reliable group flow, use /apkinfo@your_bot_name or disable Privacy Mode in BotFather.

Quick Start

Install workspace dependencies from the repository root:

npm install

Run the Worker bot locally:

npm run dev

Run the Web UI locally:

npm run pages:dev

Worker Deployment

Configure Worker secrets:

npx wrangler secret put BOT_TOKEN --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put BOT_TOKEN --config packages/bot-worker/wrangler.jsonc --env preview
npx wrangler secret put ADMIN_TOKEN --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put ADMIN_TOKEN --config packages/bot-worker/wrangler.jsonc --env preview
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET --config packages/bot-worker/wrangler.jsonc --env preview

Use a dedicated test bot token for the preview environment. In GitHub Actions, set TEST_BOT_TOKEN; the workflow syncs it into the preview Worker as BOT_TOKEN so production BOT_TOKEN stays isolated.

TELEGRAM_WEBHOOK_SECRET is optional, but recommended for production.

Report sharing uses the REPORT_DATA_BUCKET R2 binding declared in packages/bot-worker/wrangler.jsonc. Deploys use separate preview and production buckets, and the deploy script creates the target bucket when it is missing during a real deploy. The deploy CLOUDFLARE_API_TOKEN must include R2 Admin Read & Write permission for bucket creation.

SDK custom emoji ids are runtime data. The sync and deploy scripts resolve a Workers KV namespace named tgbot-sdk-emojis; real sync/deploy runs create it automatically when it does not exist. Set TELEGRAM_SDK_EMOJI_KV_NAMESPACE_NAME only if you want a different namespace name. When the KV binding or key is absent, the Worker still lists SDK markers but omits custom emoji icons.

Run the deploy preflight locally before shipping:

npm run deploy:preflight -- --target=preview
npm run deploy:preflight -- --target=production

Deploy preview or production:

npm run deploy:preview
npm run deploy:production

Deploy production and register the Telegram webhook:

npm run deploy:setup

The Worker has explicit Wrangler environments in packages/bot-worker/wrangler.jsonc:

  • preview: deploys tgbot-preview on workers.dev, binds the custom domain from repository variable PREVIEW_WORKER_URL, uses Libchecker_TG_Bot_Preview, uses TEST_BOT_TOKEN for preview bot testing, points report buttons at PREVIEW_WEBUI_SITE_URL or the fixed Cloudflare Pages preview alias, registers the preview Web UI Pages custom domain when configured, and injects the preview Worker origin so Web UI report links can resolve ?r=....
  • production: deploys tgbot, binds the custom domain from repository variable WORKER_URL, uses Libchecker_TG_Bot, injects that URL as PUBLIC_WEBHOOK_URL, points report buttons at WEBUI_SITE_URL, registers the production Web UI Pages custom domain when configured, and injects the production Worker origin so Web UI report links can resolve ?r=....

Web UI Deployment

Build and deploy the Pages app directly:

npm run pages:build
npm run pages:deploy:preview
npm run pages:deploy:production

The root Cloudflare deploy commands are preferred because they always run check, WebUI build, WebUI performance budgets, and Worker dry-run size budgets before deployment. Pages preview deploys use the current branch name, while production deploys use the main branch.

The Web UI build publishes machine-readable discovery resources for its real public URL-analysis API:

  • /.well-known/api-catalog
  • /openapi.json and /api-docs.md
  • /.well-known/agent-skills/index.json
  • /auth.md, which documents that the public API needs no registration or credentials
  • /health

DNS-AID is an external DNS-zone operation and is not changed by the Pages deploy. After resolving WEBUI_SITE_URL to its hostname, publish an organization-index record like the following, using a Private Use numeric SvcParamKey for the unregistered well-known path parameter, and enable DNSSEC for the public zone:

_index._agents.<webui-host>. 3600 IN SVCB 1 <webui-host>. mandatory=alpn,port alpn="h2" port=443 key65400="/.well-known/agent-skills/index.json"

Do not advertise mcp in DNS until the /mcp endpoint is deployed and verified. Do not advertise a2a or OAuth services that do not exist.

MCP clients