madar

Imported from 20057AMO/madar (AGENTS.md). Install upstream with npx skills add 20057AMO/madar. Copyright stays with the author.

AGENTS.md — Madar

Naming (2026-08): the product was renamed WSD-Pro → Madar (مدار). All user-facing strings, docs and baked opencode content say Madar; the GitHub repo is now 20057AMO/madar and backup downloads are named madar-backup-*.json (legacy wsd-pro-backup exports still importable). Deliberately KEPT for data/infra compatibility: wsd.* localStorage keys, WSD_* env vars, docker resource names (wsd-pro container, wsd-pro-app image, wsd-<slug> project containers, wsd/workspace image), the per-project goals filename WSD_PROJECT.md, and the legacy wsd-pro-backup import marker alongside the new madar-backup. The retired JWT default-secret literals now survive ONLY in the jwt-secret-core.ts deny-list, the jwt-secret.test.ts regression cases and this paragraph (they must be recognizable to be refused, and no code path may ever use them as key material) — nothing signs with them, see "JWT signing secret" below.

Vertical Goal (الهدف الرأسي)

Madar is an excellent, professional environment for a development team — بيئة متكاملة واحترافية لفريق تطوير.

The product unifies the whole development lifecycle in one place:

• بيئة تطوير مستقلة لكل مشروع — حاوية خاصة + محرر VS Code مضمّن + طرفية + ملفات + سجلات
• تخطيط وتوثيق — لوحة التخطيط البصري (Canvas) + ملاحظات (أفكار/أخطاء/أهداف) + نظرة سياق ذكية
• ذكاء اصطناعي مدمج — opencode + وكلاء/مهارات/أوامر + محادثة بسياق المشروع الكامل
• تعاون وفريق — أعضاء وأدوار وصلاحيات + لقطات/نسخ احتياطية + مراقبة وتنبيهات + مقاييس تخزين

كل ميزة أو تعديل يجب أن يخدم هذا الهدف: بيئة واحدة احترافية يعمل فيها الفريق من التخطيط إلى التطوير والاختبار والإنتاج.

Docker Rebuild Rule

After every code change to frontend/ or backend/, always rebuild and restart the container:

docker compose build app && docker compose up -d app

No exceptions. Every feature, fix, or refactor must be tested inside the running container.

Build & Verify

Local (development)

cd frontend && node node_modules\typescript\bin\tsc --noEmit
cd frontend && node node_modules\vite\bin\vite.js build
cd backend && node node_modules\typescript\bin\tsc --noEmit

Docker (integration)

docker compose build app && docker compose up -d app

Testing

Full backend suite against the running container (server must be up on port 3000):

cd backend && node --test --test-concurrency=1 "tests/**/*.test.ts"

Test notes:

• Tests sign their own JWT using the same resolved secret the server uses (no real password needed) — see "JWT signing secret" for the order: JWT_SECRET env, else the container's persisted data/jwt.secret
• Run serially (--test-concurrency=1) — parallel runs + browser polling can trip the rate limiter
• Optional real-login test activates with WSD_TEST_USER / WSD_TEST_PASS env vars
• Every suite cleans up its own data (projects, agents, providers, sessions)
• Change-password is intentionally NOT auto-tested (would mutate the real account)

UI E2E (Playwright)

backend/tests/e2e/limits_ui.py — a browser-level suite, covering the Resource-limits UI end to end against the running container: create-modal CPU/Memory inputs → create-with-limits (cap applied immediately) → edit → honest "Recreate to apply" pending banner → blanking both fields removes the limits (banner persists while the cap is live) → CPU/RAM meta-chips on Projects/Dashboard/Planner cards. It forges an admin-session JWT from the repo JWT_SECRET (the real account has TOTP, and the UI login route always steps the FIRST user through the authenticator — see user-store.isTotpEnabled()), seeds it into localStorage['wsd.token'] before first paint, and cleans up every e2e-* project before/after. Exit 0 = all green, 1 = failures, 42 = skip. Host deps: python 3.x + pip install playwright pyjwt requests (+ playwright install chromium); server must be up. Run: python backend/tests/e2e/limits_ui.py backend/tests/e2e/reviews_ui.py — the File-reviews UI suite: thread lifecycle end to end (create on src/app.ts with a real workspace file → reply → resolve/reopen badge flips → 'file not found' badge on a missing path → ConfirmModal thread delete with counters + API counts re-checked → viewer member sees the read-only surface with no composer/resolve/reply/delete controls). Same forged-admin-JWT + e2e-* cleanup contract as limits_ui.py; uses ONE shared browser context so two back-to-back runs stay under the global rate budget. Run: python backend/tests/e2e/reviews_ui.py

Project Structure

frontend/   — Preact + TypeScript + Vite (served at /)
backend/    — Express 5 + Node 22 + WebSocket ws
Dockerfile  — Multi-stage: frontend build → backend build → runtime
Dockerfile.workspace — Ubuntu 24.04 base image for project containers

Architecture Notes

WebSocket Endpoints

• Project access over the chat WS (mirrors requireProjectAccess): only project members may connect to a project's chat room (outsiders are closed with 1008 before any replay is sent) and only members with at least editor access may send prompt/stop — a viewer's write attempt gets a read-only error frame while the socket stays open (they keep live read). Global editors (system role editor) pass as write-level on every project. global chat remains open to every authenticated user; system admins always pass; legacy projects without membership data stay open | /ws/agent/:id/:chatId | ws-agent.ts | Agent chat with tools |

Frontend Pages

Authentication

• Unified auth: Single user password = providers password
• Per-user identities: POST /api/auth/login resolves the authenticated user BY USERNAME and mints a session carrying THEIR OWN id/username/role/tv/jti (never the first admin's — login() in user-store.ts; legacy first-admin issueSessionToken removed). POST /api/auth/login/verify signs the user who completed the challenge (signLoginSession(pendingUserId)). Team member logins/multi-role access depend on this: editor/viewer tokens now really are editor/viewer (403 on admin routes), not admin
• Backend: bcrypt (10 rounds) + JWT (24h expiry) stored in data/users.json
• Frontend: auth.tsx AuthProvider context, token in localStorage as wsd.token
• HTTP: authMiddleware on all routes after /api/auth/* (returns 401 without Bearer token)
• WebSocket: JWT token passed via ?token= query param on upgrade, validated server-side
• API helper: api() auto-attaches Authorization header; 401 responses redirect to /login
• Routes: /login accessible without auth, all other routes require authenticated user
• Global Editor role: system editor is the global editor — checkProjectAccess (auth.ts) treats role editor like a write-level member on EVERY project without needing membership (delete/transfer-owner/member-add stay admin-only, and user/settings/providers management is admin-only), so an editor can act on any project the moment the account exists. UI surfaces this in Team ("Editor · global")
• Chat context & session routes are project-gated (the F1 finding): GET /api/chat/context and the four chat-session routes (GET/POST /api/projects/:slug/chat-sessions, PUT/DELETE …/:id) authenticated but never authorized — ANY authenticated user could read another project's getProjectContext payload (files, notes, goals, canvas) and list/create/delete its chat sessions; a viewer member could too, since nothing asked for even viewer access. Now the slug is folded ONCE to canonicalProjectSlug before the gate (the same invariant as /api/opencode/open — near-misses like slug!/uppercase/space-padded fold then 403, junk → 400 Project slug is invalid, empty → 400 Missing project query), checkProjectAccess(..., 'viewer') guards reads and 'editor' guards mutations through one tiny shared chatSessionGate(req, project, level) helper, refusals are plain 403 {error:'Access denied to this project'} with no payload, downstream code uses the one canonical value, project=all stays open to every authenticated user, unknown-but-canonical slugs keep the legacy ABSENT-meta fallback 200 (/workspace not found/ context), and unscoped/global session rows stay ungated. Live-proven in the F1 matrix inside tests/providers-agents-chat.test.ts (against the running container)
• Members write gate (the F14 rule): POST /api/projects/:slug/members refuses an ABSENT store (readMeta(slug).state === 'absent') with 404 Project not found, so a request can never be answered by writing a phantom meta; but a LEGACY project that really exists on disk (meta.json present with neither ownerId nor members) now accepts its first member (200) — a system admin may add it, while the legacy fallback still caps the admin gate so a global editor/viewer stays 403. The first row crosses the project from the legacy open fallback into a member-restricted model; this is deliberate and narrower than the removed guard, which used to 404 the first add forever. A CORRUPT store is fail-closed (403) at the gate before the handler runs. Pinned by tests/team-members-cleanup.test.ts (F14 roundtrip) + tests/access-core-gate.test.ts (offline cap)
• Deleting a user cleans their membership rows conditionally (F5): DELETE /api/users/:id strips the user from every meta.members but writes ONLY for projects that actually carry a row for them (a read-only memberList(existing).some(...) probe before updateMeta), and calls invalidateProjectsCache() only when something changed. A row-less legacy store is therefore left byte-for-byte untouched instead of being rewritten into members: [], which would silently disable the legacy no-membership access fallback. Best-effort per project; the activity feed keeps the historical actor by design

Two-Factor Authentication (optional TOTP)

• RFC 6238 TOTP implemented from scratch in backend/src/services/totp.ts (HMAC-SHA1, 30s steps, 6 digits, ±1 step drift) — verified against the official Appendix B vectors in tests/totp.test.ts; compatible with Google Authenticator/Authy/Aegis
• Login flow with 2FA on: POST /api/auth/login verifies credentials then returns {requires2fa:true, pendingToken} — a 5-min JWT (scope:'2fa-pending'), NOT a session. The challenge is per-user: only an account whose OWN TOTP is enabled gets diverted; everyone else gets a direct session (an editor is never blocked because the admin enabled 2FA). POST /api/auth/login/verify {pendingToken, code} exchanges it for a session signed for the user who went through the challenge; guarded by a dedicated totp rate-limit scope (8/min/IP)
• Enrollment: POST /api/auth/2fa/setup → {secret, uri} (pending secret, disabled until proven); POST /api/auth/2fa/enable {code} activates only after a live code verifies; POST /api/auth/2fa/disable {accountPassword} requires sudo re-auth
• Frontend: Login shows an authenticator-code step when pending2fa is set in AuthProvider; Settings → Two-Factor panel renders the QR (qrcode npm pkg) + manual base32 key, activate/cancel, disable via ReAuthModal
• Audit: 2fa-enabled/-failed, 2fa-disabled/-failed, login-2fa-failed
• Lost authenticator: self-hosted recovery = remove totp from data/users.json and restart (documented in UI copy as admin-level escape hatch)

Providers Security Lock (optional second layer)

• Separate bcrypt password stored in users.json (providersPasswordHash) — independent from the account password
• Managed exclusively from Settings → Providers Security via a two-step sudo-style flow: pick the new lock password, then confirm identity in ReAuthModal (shows the signed-in username, asks for the account password)
• The same ReAuthModal pattern authorizes every sensitive op: lock save/remove, backup export/import, logout-everywhere
• Unlock issues a scoped JWT (scope:'providers', 30 min) sent as X-Providers-Unlock; version counter (pv) invalidates all unlock tokens on password change
• Session-bound unlock: login tokens carry a random jti; the unlock token embeds it as sid and providersLockMiddleware requires a match with the requesting session — a stolen unlock token replayed from another session is rejected (legacy tokens without jti use '' consistently on both sides)
• Strict instant gate (frontend): Providers page persists last-known lock state in localStorage['wsd.providers.lockEnabled'] — when a lock is known-enabled and no valid local token exists, the gate renders on first paint before any network call, so provider content can never flash. Expiry is re-checked every 1s plus on pageshow/visibilitychange (bfcache/sleep-wake safe)
• Wrong-password never logs out: every intentional password-verification call (unlockProviders, providers-password set/remove, logout-all, settings export/import, 2FA disable) passes skipAuthRedirect: true so its 401 surfaces as an inline message instead of triggering the global session-expiry handler in api() (which wipes the token and redirects to /login)
• Unlock feedback: success shows an "Unlocked · N min" notice; the no-lock-configured case ({unlocked:true} without a token) explains that protection is off instead of silently accepting any word; welcome modal ("Protect your API keys") shows once per browser (wsd.providers.onboarded in localStorage)
• Gate never silent: when the gate appears it says why — Auto-relocked after inactivity. (idle timer breadcrumb in sessionStorage['wsd.providers.autoRelocked'], set by auth.tsx) or Your unlock window ended. (1s tick expiry detection)
• POST /api/providers/unlock is brute-force guarded by a dedicated unlock limiter scope (15/min) plus a progressive cooldown (5 consecutive failures per IP → 15-min window returning 429 + Retry-After, in-memory, reset on success); audited (providers-unlock / providers-unlock-failed / providers-unlock-cooldown)
• Scoped tokens are never sessions: verifyToken rejects any JWT carrying a scope claim, so providers-unlock and 2FA-pending tokens cannot authenticate generic routes even though they share the signing secret
• Auto-relock: Settings → Idle security offers an idle timer ('off'/5/15/30 min, stored as wsd.providersAutoRelock) that calls relock + clears the local token after inactivity; same activity-throttle + cross-tab storage-sync machinery as auto-logout
• Unlock badge: sidebar shows "🔓 Providers · Nm" only while unlocked (countdown from expiresAt); click → confirm → instant relock
• Enabling/changing the lock returns a ready-to-use unlock token — the current session stays open on the Providers page (no immediate re-entry)
• POST /api/providers/relock ("Lock now") bumps the version server-side — kills every outstanding unlock token across all tabs/devices; audited (providers-relock)
• Unlock token lives in localStorage (time-boxed by its expiry) so the storage event keeps all tabs in sync about lock state
• When enabled, management endpoints return 403 {error:'providers_locked'} without a valid token
• Always-open endpoints: GET /api/providers/options (id/name/type only) and GET /api/providers/templates
• Chat/agent LLM usage is server-side and never blocked by the lock
• Providers page UX states: skeleton shimmer (checking) → welcome modal explaining protection (when unconfigured, dismissible per tab session) → centered login-style unlock modal (when locked)

At-rest encryption (secret box)

• Provider API keys in data/providers.json are sealed with AES-256-GCM (backend/src/services/secret-box.ts): format enc1:<iv>:<tag>:<ct>:<last4>
• Key = scrypt(WSD_ENCRYPTION_KEY env → falls back to the resolved signing secret, salt persisted once in data/crypto.salt, mode 0600); rotating the master secret makes old blobs open to '' (upstream auth failures — re-enter keys from the UI)
• Migration is automatic: on first load any plaintext key is sealed and the file rewritten; masking uses the stored <last4> so it never decrypts; duplicate detection opens values transparently
• Backup export strips keys entirely (unchanged), so ciphertext never leaves the server either
• Lost/rotated key recovery: delete crypto.salt only if starting fresh — otherwise restore the previous env value; plaintext keys pasted by users are re-sealed on next save

Security hardening (post-audit)

• Chat session stores are traversal-safe: data/chat-sessions.json + the per-session chats/<slug>/<chatId>/events.jsonl tree accepted dot-only ids — a poisoned '..' chatId made deleteSession's rmSync target the whole chats/ dir, and a '..'/'..' pair escaped to DATA_DIR itself. Both writers now fold dot-only values to stable fallbacks (global / chat-unspecified — deliberately duplicated 3-line rules in chat-sessions.ts AND chat-store.ts with cross-reference comments, no shared import so each stays import-free), chatDirFor structurally refuses any pair that is not exactly 2 non-dot segments under chats/ BEFORE any rm/splice/save, and deleteSession never removes a directory outside its own. Covered by tests/chat-sessions-core.test.ts (5 offline units; non-vacuity proven — the same suite fails 0/5 with the fix stashed)
• WSD_TRUST_PROXY=1 opts into trusting one reverse-proxy hop for req.ip; default is OFF so directly-published ports can't spoof X-Forwarded-For past the rate limiters
• SSRF guard on provider detection/testing: hosts must be http(s); cloud-metadata endpoints (169.254.x, metadata.google.internal, 100.100.100.200, link-local) are refused before any fetch — private LAN/loopback stays allowed (local Ollama is a core feature)
• Masked-key echo guard rejects both pure bullets and the displayed <8 bullets><last4> shape
• Provider ids are own-property checked (__proto__ etc. → 404); providers.json / users.json / audit.json persist with mode 0600
• Startup banner reports the RESOLVED signing secret's origin (see "JWT signing secret" below) — an env value logs one informational line, a generated one prints the warning box naming the file and the command to run
• CORS is opt-in via WSD_CORS_ORIGINS (comma-separated allowlist) — no env set means no ACAO headers at all; the UI is always same-origin (vite dev proxies /api + /ws), so a wildcard would only ever help attacker sites read the authenticated API
• Provider health-check cache keys hash the API key with SHA-256 — raw secrets never sit in memory-map keys
• Chat markdown href filter is a scheme whitelist (http:/https:/mailto:/#//) after stripping control chars, so java\tscript: obfuscation can't reach the DOM

Workspace files & the meta store (audit hardening)

• Path containment — ONE primitive (services/workspace-paths-core.ts) — the single enforcement point for every project-workspace path and the only place that answers "is this inside the workspace". Its import graph is {fs, path} → project-slug-core, so node --test loads it offline (like janitor-core / archive-core / serve-core). The rules: the workspace root is realpath-ed (realWorkspaceRoot) and every decision is made against that, never the raw env value; the

Truncated - read the full file at https://github.com/20057AMO/madar/blob/3e40681a51cd1e5e830cad3a5dc2d4cd193d5c7a/AGENTS.md.