tools-legacy/openspec/changes/archive/2026-10-01-move-image-cropper/design.md

Design

Context

id-image-bot is three things: a Telegram intake bot (handlers disabled in code), a picture-review pipeline (Azure queue id-images, Minio files bucket, nodered review/process endpoints), and the operator web tool ("Smart Photo Editor": Vue 2 + vue-croppa, phone/OTP login against a2loft). Only the web tool moves; the bot and its deployment stay. The a2loft save route (POST /:domainCode/profile/picture) accepts only ?phone=&otp= — no key variant — so the operator OTP survives, but only at save time. See proposal.md for motivation.

Goals / Non-Goals

Goals:

• One login story: YOUreka session everywhere; the cropper adds only a save-time OTP (a2loft's requirement).
• Uniform crop_image authorization over every proxied cropper endpoint, cheap for the portal (read cache, live at save).
• Faithful behavior: same queue/review/nodered flows and review-reason list.

Non-Goals:

• Moving the Telegram bot; decommissioning spxa.yrka.app.
• Changing the review/reject workflow or the review-reason catalog.
• Replacing toastr/swal UX patterns wholesale.

Decisions

1. Namespaced router, tools/cropper.js with DI. createCropperRouter({ minio, queue, fetch, requireApi, cropGate, a2loftBase, ... }) — the same injectable pattern as the app factory, so tests fake minio/queue/upstreams. Mounted at /cropper in server.js; the UI uses relative request paths.
2. Unified login. The bot app's phone+OTP middleware validated every request; here the YOUreka session replaces it, and the one a2loft call that needs an OTP (picture save) takes an operator-entered OTP forwarded with the session phone and the picture's domain. Phone prefill from /auth/session.
3. crop_image gate with read cache. permit.js grows cropPermission( phone, {force}) beside the domain checker: same verifyOnce plumbing, relation: 'crop_image', object domain:idid, no fallback; results cached per phone for 5 minutes, save forces live. Router-level middleware covers every cropper route uniformly.
4. Credentials via env, URLs hardcoded. MINIO_ACCESS_KEY, MINIO_SECRET_KEY, AZURE_STORAGE_CONNECTION_STRING, NODERED_HTTP_USERNAME, NODERED_HTTP_PASSWORD, CARVEKIT_API_KEY — same names the bot app used, so an existing .env is drop-in. Clients are built only when the env is present; without it the router answers 503 and the rest of the app is unaffected.
5. Restyle to the tools design language. Same stylesheet and panel structure as /fingerprint (navbar, step chips, badges, buttons); toastr stays for toasts. No behavior change beyond namespacing and auth.
6. Native FormData (Node 22) replaces the form-data dependency for the cleanup proxy.

Risks / Trade-offs

• [a2loft validateOtp may not recognize the YOUreka session phone format] → the fingerprint walkthrough already saw a2loft accept the session phone on lookups; the field pass confirms on the save path before cutover.
• [Cached crop gate lets a revoked operator act for ≤5 minutes] → reads only; the save verifies live, and a2loft's OTP check remains the hard gate.
• [Review/process endpoints depend on nodered availability] → unchanged from the bot app; failures surface as route errors, not crashes.
• [Two auth domains (mnet/ucth) disappear from the login] → the save validates against the picture's domain; the field pass exercises a real item.

Migration Plan

1. Land the cropper in tools/ while id-image-bot keeps running unchanged.
2. Field pass: login → gate → load a real queued item (or by ID) → crop → clean → save with OTP; confirm the picture lands in a2loft.
3. Repoint the landing card (done in the same change); leave spxa.yrka.app running until the team confirms the new home.
4. Rollback: the old deployment still serves the tool.

Open Questions

None — auth unification, secret handling and scope were confirmed with the operator.