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

Proposal: move-image-cropper

Why

The tools landing page sends operators to an external deployment for identity photo cropping (spxa.yrka.app — the proposal's original text said smart-pxa.yrka.app, which was wrong), with a separate phone/OTP login and no shared session. Moving the cropper into the tools app unifies auth, deployment and the UI, and puts its externally-proxied endpoints (background cleanup, picture storage) behind the same authorization as the rest of the tools.

What Changes

• BREAKING: Add the Image Cropper ("Smart Photo Editor") to the tools app at /cropper — page + namespaced API router (/cropper/picture/*, /cropper/profile/picture, /cropper/dequeue, /cropper/api/*) — replacing the landing page's external link.
• Unified login: the cropper's phone/OTP "Artist Login" is removed. Identity comes from the YOUreka session; a single OTP is entered only when saving to a2loft (the only call a2loft requires it for).
• Crop permission gate: page load, picture loading, background cleanup and saving each verify crop_image on domain:idid (subsystem idid) via the portal OpenFGA endpoint — fail closed; reads may serve a 5-minute cached result, saving always checks live.
• Restyle: the cropper UI adopts the tools design language (navbar, cards, badges) instead of the old grey standalone page.
• Credentials via environment: Minio, Azure storage, nodered and Carvekit credentials come from process.env (documented in .env.example) — the sole exception to the hardcoded-configuration rule; URLs stay hardcoded.
• The Telegram intake bot stays in id-image-bot untouched; the old cropper deployment remains until this one is field-proven.

Capabilities

New Capabilities

• image-cropper: the /cropper photo review/crop tool — permission gate, picture loading, background cleanup, save to a2loft with OTP.

Modified Capabilities

• tools-app: landing page links the cropper internally (/cropper), and the hardcoded-configuration requirement gains a credentials-via-environment carve-out.

Impact

• New code: tools/cropper.js (DI router), tools/public/assets/cropper/, permit.js generalization (crop_image check with cache).
• New dependencies: minio, azure-storage. Removed dependency risk: none (form-data replaced by native FormData).
• New env vars: Minio keys, Azure storage connection string, nodered credentials, Carvekit key (.env.example documents all).
• External systems unchanged: Azure queue id-images, Minio files bucket, nodered.a2loft.net, removebg.itcass.net, apis.a2loft.net.