Technical improvement roadmap

Status

Superseded on 2026-08-28 by the complete remediation plan, which is the canonical execution authority. This document remains available as historical context and must not be used to infer the current scope; in particular, the new plan explicitly keeps the .env.example findings outside its execution boundary without closing them.

Objective

Bring MonStaff from a functioning early product to a defensible multi-tenant service without rewriting the modular monolith.

Phase 0 — Immediate containment

Status: proposed

1. Rotate all credentials exposed in .env.example and replace them with placeholders.
2. Add secret scanning and inspect Git history only after rotation.
3. Fix every admin query to scope records by project.organizationId.
4. Stream or directly presign desktop-update uploads; reduce the temporary size limit.
5. Correct OLLAMA_BASE_URL and create the update bucket in production Compose.

Exit evidence: rotated provider records, cross-tenant regression tests, bounded upload test and rendered deployment configuration.

Phase 1 — Authorization and data integrity

Status: proposed

1. Introduce central requireProjectMember, requireOrgAdmin, requireTimeEntryOwner and resource-in-organization policies.
2. Apply them to projects, issues, timers, screenshots, activity and import mappings.
3. Reconcile removed GitHub memberships.
4. Add the one-running-timer partial unique constraint.
5. Make screenshot/object deletion idempotent and recoverable.

Dependency: agreed security model.

Phase 2 — Identity redesign

Status: proposed

1. Replace bearer-token deep links with a one-time authorization code.
2. Use Authorization Code + PKCE and secret, expiring state.
3. Store/consume challenge state atomically in PostgreSQL or Redis.
4. Introduce short access tokens and rotating, revocable refresh tokens.
5. Re-read current server-side authorization for sensitive actions.

Phase 3 — Quality and dependency baseline

Status: proposed

1. Add a clean root typecheck and real lint scripts.
2. Fix desktop contract/type errors.
3. Add security-first unit and integration tests.
4. Gate deploy and release on full verification.
5. Upgrade Fastify/JWT, Electron, AWS SDK/XML parser and build tooling in controlled groups.
6. Enable automated dependency update and vulnerability scanning.

Phase 4 — Durable asynchronous work

Status: proposed

1. Introduce a worker and durable job queue for imports and large GitHub syncs.
2. Add lease, heartbeat, cancellation, checkpoints and recovery.
3. Add idempotency keys and server deduplication to desktop retries.
4. Encrypt queued local payloads or replace embedded bearer tokens with safe references.
5. Standardize outbound timeouts, backoff and retry eligibility.

Phase 5 — Operability and scale

Status: proposed

1. Separate liveness and readiness and expose dependency status.
2. Add metrics, tracing/correlation and security audit events.
3. Move unbounded analytics to paginated database aggregation.
4. Establish PostgreSQL/S3 backup and recovery tests and disruption budgets.
5. Pin images, run non-root and add security/network policies.
6. Define service-level objectives and alert thresholds.

Completion protocol

When work lands, update the relevant item to completed with date, commit, tests and residual risk. Update the risk register separately; implementation alone does not prove closure.