SOLO Monorepo

این مخزن یک مونو‌ریپو شامل سه پکیج اصلی است:

• /workspace/backend — بک‌اند Fastify + TypeScript + WebSocket + Playwright
• /workspace/extension — افزونه Firefox (Manifest V2) با TypeScript (bundled via esbuild)
• /workspace/shared — typeها و JSON Schema پروتکل WebSocket

پیش‌نیازها

• Node.js (ترجیحاً 20+)
• برای Playwright: وابستگی‌های سیستم‌عامل (در devcontainer نصب می‌شود)

نصب

در ریشه:

npm install

اجرای توسعه

npm run dev

• بک‌اند: http://localhost:8080 و WS روی ws://localhost:8080/ws
• افزونه: خروجی build در /workspace/extension/dist

build

npm run build

تنظیمات امنیتی (allowlist و ضد SSRF)

بک‌اند به‌صورت پیش‌فرض deny-by-default است و فقط دامنه‌هایی که در allowlist هستند را قبول می‌کند:

• فایل نمونه: /workspace/backend/.env.example
• متغیر: ALLOWLIST_DOMAINS=example.com,*.example.com
• برای توسعه (خطرناک): ALLOWLIST_ALL=true

جزئیات بیشتر در:

• /workspace/docs/security.md

احراز هویت (Shared Secret) برای HTTP/WS

برای جلوگیری از سوءاستفاده، می‌توانید یک توکن ثابت فعال کنید:

• در بک‌اند: SHARED_SECRET=... (در backend/.env.example)
• برای WebSocket: افزونه بعد از اتصال، پیام auth را ارسال می‌کند.
• برای HTTP (endpointهای تست): باید یکی از این‌ها را بفرستید:
  • x-solo-secret: <token>
  • یا Authorization: Bearer <token>

پروتکل WebSocket

typeها در:

• /workspace/shared/src/ws-protocol.ts

و JSON Schema در:

• /workspace/shared/schema/ws-protocol.schema.json

حالت‌ها (modes)

1) fetch

درخواست HTTP ساده از سمت بک‌اند (با redirect=manual)، خروجی به صورت bodyBase64.

2) render (HTML rewrite + sanitize)

با Playwright صفحه باز می‌شود، سپس:

1. src/href نسبی → absolute rewrite می‌شود
2. HTML با sanitize-html امن‌سازی می‌شود (حذف script و handlerها و …)

3) screenshot streaming (frames only)

یک session در Playwright ساخته می‌شود و سپس فریم‌ها به صورت پیام‌های frame (JPEG base64) روی WS ارسال می‌شوند.

افزونه Firefox

1. ابتدا npm run build را اجرا کنید.
2. در Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on…
3. فایل manifest.json را از مسیر زیر انتخاب کنید:
   • /workspace/extension/dist/manifest.json

در popup:

• Fetch / Render / Stream

مستندات تکمیلی

• /workspace/docs/troubleshooting.md
• /workspace/docs/security.md
• /workspace/docs/diagrams.md