cg_api_secure-webshare/AI_MASTER_PLAN.md

AI Master Plan — cg.cx Refinement Pass

1. Current Repo Understanding

Architecture

• 10-crate Rust workspace (cgcx-core, cgcx-config, cgcx-crypto, cgcx-db, cgcx-storage, cgcx-content-typing, cgcx-file-pipeline, cgcx-moderation, cgcx-bot, cgcx-server)
• SQLite database with WAL mode, 7 migrations already applied (001_init through 007_hash_blacklist)
• Svelte 5 SPA frontend (frontend/), Vite build, served as static files by Axum fallback
• Teloxide bot (standalone binary) + Axum server (standalone binary), both share DB and config
• Content encrypted with XChaCha20-Poly1305, per-file CEKs wrapped with AES-KW under a master key
• BLAKE3 plaintext hashes stored for deduplication and hash-blacklist enforcement

Already Implemented (verified in code)

Task	Status	Location
D — GLOBAL_BAN config	✅	config/default.toml [groups] global_ban; propagate_punishment() in bot
F — Approval message with media batches	✅	handle_forward_callback "approve" — decrypts files, batches up to 10, appends caption to last batch
G — Review group media	✅	finalize_upload — decrypts and sends media batches to review group, appends review text to last batch
H — Review buttons (Ban, Blackl., Ban/BL u.)	✅	Inline keyboard in finalize_upload and handlers in handle_forward_callback
K — Show/Hide Author toggle	✅	UploadOptions.show_author, toggle_author callback, show_author DB column (migration 005)
L — File list metadata	✅	ViewContent.svelte shows created_at, total_size, author (username hyperlink + ID)
M — Deduplication	✅	FilePipeline::ingest_file checks find_active_by_plaintext_hash, increments ref_count
N — Hash blacklist	✅	HashBlacklistRepo, migration 007, blocked-hash rejection in pipeline
O — Username change tracking	✅	UserRepo::ensure_exists logs changes to data/uname_changes.json (configurable path in config)
Partial A — Misc report UI	✅	Home.svelte already has "Report Content via Telegram" link + "Report Content directly" input/button
Partial Q — Homepage bot link	✅	Home.svelte already has t.me/{BOT_USERNAME} link, but in wrong DOM order and styling needs tweak

Actual Bugs / Gaps to Fix

Task	Root Cause	Fix Strategy
B — /get_id	Admin commands gated behind msg.chat.is_group() || msg.chat.is_supergroup(), excluding channels. Also, HTML parse errors in logs come from unescaped <arg> tokens in /help, but /get_id must also be hardened for channels where msg.from / admin visibility differs.	Add msg.chat.is_channel() to admin command scope. Ensure handle_get_id_search gracefully handles channels (get_chat_administrators works in channels too if bot is admin).
C — /help	help_text raw string contains literal <ID>, <@username>, <displayname>, <user_id>, <dur>, <unit>. Telegram HTML parse mode rejects unsupported tags like <id>.	Escape all argument placeholders: replace <arg> with &lt;arg&gt; or [arg]. Minimally invasive: keep the rest of the formatting intact.
E — blacklist_uid / whitelist_uid	Commands are technically restricted to admin_group_ids inside the handler, but the outer command dispatch allows them in any group for admins, producing a confusing "only available in admin group" message. Missing-parameter handling exists but UX is inconsistent with other admin commands.	Move the admin-group check into the command dispatch so non-admin-group chats get a clear "Unauthorized" response. Ensure missing-parameter usage info is returned before the admin-group gate when possible, so users in the admin group see usage info immediately.
I — Password + auto-destroy 410	serve_file increments view_count for HEAD requests because is_conditional only checks If-None-Match, not request method. Some browsers/proxies/link previews issue HEAD before GET, consuming the view and causing the subsequent GET to hit view_count >= max_views → 410.	Add Method extractor to serve_file and skip view increment when method == Method::HEAD. Also skip increment for any non-GET method as defense-in-depth.
J — Password field UX	Home.svelte submit() calls fetchMetadata(cxid) without password first. For password-protected content this returns 401, throws, and the catch block sets a raw JSON error string. needsPassword is never set to true, so the password field never appears on the home page. Users cannot access password content from the home page at all.	Restructure submit(): on 401 from fetchMetadata, explicitly check if the error is auth-related and set needsPassword = true instead of treating it as a generic error. Ensure password verification only runs on explicit submit/Enter, not on keystrokes.
A — Misc report (complete)	Frontend UI exists but the "direct" report still opens a Telegram deep link instead of submitting via the web backend. The hardcoded harmfulmeowbot username is wrong; should use BOT_USERNAME from api.js.	Add POST /api/report endpoint to the server (it has access to config.telegram.bot_token). Server inserts report into DB and forwards a notification to configured review groups via direct Bot API HTTP calls. Update frontend to call the API instead of opening Telegram.
Q — Homepage bot link	Bot link is present in Home.svelte but DOM order is wrong (currently above Content ID label; should be between Content ID field and "-- cannibal girls --"). Styling says underline + very dark green/blackish green; current color is var(--retro-green) which may need to be var(--retro-accent) or a darker custom value.	Reorder elements in Home.svelte. Adjust CSS to match spec. Keep BOT_USERNAME dynamic import.

2. Locked Implementation Rules

• No broad rewrites. Fix only the targeted bugs and gaps.
• No redesign of working flows. The upload pipeline, encryption, submission forward system, and moderation engine are working — do not touch them except where task I requires the HEAD-request guard.
• Preserve existing frontend style and behavior. Keep retro theme, fonts, colors, and animations. Only adjust the specific elements requested in A, J, Q.
• No cleanup-only changes. Do not refactor unrelated code, rename variables, or change formatting.
• 4-agent cycle mandatory for implementation batches.
• SQLite schema is frozen except if a new migration is absolutely required. Tasks A–Q do not need new DB tables (report endpoint can reuse existing reports table with reporter_user_id = 0 for web reports).

3. Exact Batch Order for This Refinement Pass

Batch 1: Security + Stability (Agent 1)

• B — /get_id channel support and robustness
• C — /help HTML escaping fix
• E — blacklist_uid/whitelist_uid command behavior refinement
• I — HEAD request view-count bugfix in serve_file

Batch 2: Telegram Bot + Permissions (Agent 2)

• Verify Batch 1 bot changes compile and pass basic smoke tests
• A backend — Add POST /api/report endpoint to server (reuse reports table, forward to Telegram review groups via reqwest HTTP call to Bot API)
• O verification — Confirm username tracking writes correctly in channels/groups
• D verification — Confirm global_ban propagation logic works with recent schema

Batch 3: Content Delivery + Rendering (Agent 3)

• A frontend — Wire "Report Content directly" to call POST /api/report instead of Telegram deep link
• J — Fix home page password flow (needsPassword trigger on 401)
• Q — Reorder bot link, adjust underline/dark-green styling
• L verification — Ensure metadata bar renders correctly after Batch 1 server changes

Batch 4: Docs + QA + Regression (Agent 4)

• P — Update docs/COMMANDS.md, docs/API.md, docs/MODERATION.md, README.md to reflect all changes
• Regression test checklist: /get_id in group + channel, /help output, blacklist_uid usage, password+auto-destroy content loads on first GET, home page password flow, report submission API, bot link styling
• Run cargo check --workspace and cargo test --workspace
• Run frontend build (cd frontend && npm run build) and verify no new warnings

4. Key Risks

Risk	Mitigation
Adding Method extractor to serve_file changes its signature and could break route registration if not matched exactly.	Use extract::Method in the handler signature; Axum get() accepts handlers with extra extractors.
POST /api/report needs to send Telegram messages from the server, which currently has no Telegram client.	Use reqwest (already transitive via Axum) to make direct HTTPS POSTs to https://api.telegram.org/bot<token>/sendMessage. Add reqwest explicitly to cgcx-server/Cargo.toml.
Channel admin command handling may behave differently because msg.from in channels can be the channel itself or anonymous.	Use msg.sender_chat or check msg.from carefully; is_admin still works with the bot's own admin check.
Frontend fetchMetadata 401 handling change in J must not break non-password flows.	Only set needsPassword = true when err.status === 401. Keep existing catch behavior for other errors.

5. Exact 4-Agent Loop

Batch N assigned to 4 subagents -> execute in parallel -> wait for all 4 ->
brief review -> update AI_CHECKPOINT.md -> continue to Batch N+1

Agent definitions (always use these exact names):

1. Security + Stability — Server-side hardening, HTML escaping, view-count logic, command permission gates
2. Telegram Bot + Permissions — Bot command behavior, channel support, global_ban, backend API wiring
3. Content Delivery + Rendering — Frontend UX, Svelte components, API integration, styling
4. Docs + QA + Regression — Documentation updates, end-to-end verification, build checks, regression checklist

6. Resume Rules

• On any resume, read this file first, then AI_CHECKPOINT.md, then AI_RESUME_PROMPT.md.
• Do not skip batches. Do not merge batches.
• If a batch fails review, re-run that batch before advancing.
• Update AI_CHECKPOINT.md after every batch completes.
• Preserve all existing working behavior not explicitly listed for change.