[Samuel-Ricardo]

V2 - Axum tickets API + full project analysis & documentation

Summary

This PR brings the v2 branch up against main: a full Axum + SQLx implementation of the tickets API plus a comprehensive project analysis consolidated into README.md and a structured docs/ directory.

It spans the complete v2 codebase (auth, crypt, RPC layer, model/service/store, Docker, CI) and a multi-specialist review (architecture, security, deployment, ops) with ADRs and a prioritized issue roadmap.

⚠️ Status: NOT deployable. The analysis identifies 6 P0 blockers that prevent the app from running end-to-end. This PR is a working codebase + a complete audit — see Known blockers and the issue roadmap before merging.

---

What's in this PR

Application code (tickets_api/src/)

• Layered architecture — controller → service → model/store with Axum State-based DI.
• Auth subsystem — signed-cookie token scheme (b64u(ident).b64u(exp).sign_b64u), mw_ctx_resolver middleware, CTX extractor, login/logoff handlers.
• Crypt — HMAC-SHA512 password encryption (#01# prefix) + token signing, per-row UUID salts.
• JSON-RPC façade — POST /api/rpc dispatching create_task / list_tasks / update_task / delete_task via sqlb runtime SQL builder over PostgreSQL.
• Generic CRUD — base::db DbBmc trait + typed get/list/create/update/delete over sqlb.
• Config — OnceLock<Config> env-driven singleton (SERVICE_*).
• Error pipeline — typed Error enum → IntoResponse (500 + extension) → main_response_mapper → client JSON {"error":{"type","req_uuid"}}.
• Dev bootstrap — _dev_utils::init_dev() (DB recreate + seed), SQL scripts under sql/dev_initial/.
• Containerization — Dockerfile, docker-compose.yaml (api + postgres).
• CI — .github/workflows/docker-publish.yml (Buildx → ghcr.io → cosign signing).

Documentation (README.md + docs/) — added in this PR

A full project analysis consolidated into 18 files:

Doc	Content
README.md	Executive summary, status, blockers, quick start, API table, config, docs index
docs/overview.md	Goals, capabilities, status, branches
docs/architecture.md	Layering, module dependency graph, DI, error/auth/config architecture, blockers
docs/api-reference.md	HTTP endpoints + RPC methods + examples + error envelope
docs/module-map.md	Type-level map of all 20 directories / 46 files
docs/data-models.md	Rust models ⇄ DB schema & the drift
docs/auth-flow.md	Token format, cookie lifecycle, sequence diagrams, weaknesses
docs/security-review.md	S1–S15 security + Q1–Q10 quality findings, OWASP checklist, roadmap
docs/deployment-operations.md	Docker, compose, observability, CI/CD, hardened artifacts
docs/issue-roadmap.md	Consolidated issue register + remediation sequencing (P0–P3)
docs/adr/	6 ADRs: axum, sqlx+sqlb, signed-cookie token, OnceLock config, layering, error middleware

---

🔴 Known blockers

The review found 6 P0 issues — the API cannot currently run end-to-end:

#	Blocker	Evidence
1	CTX is never inserted into request extensions → every /api/rpc returns 403	middleware/auth.rs:38-44
2	Token generation is todo!() → POST /api/login panics	crypt/token.rs:17-19
3	Dev bootstrap runs on every startup — hardcoded postgres://postgres:welcome@db, DROP DATABASE, .unwrap()	server.rs:16, _dev_utils/dev_db.rs:14-15
4	Schema ⇔ code drift — user.username vs User.name; table task vs TaskService.TABLE="tasks"	01-create-schema.sql vs service/user.rs, service/task.rs
5	Unwrap-panics on the request path — DB failure or malformed RPC params → panic	rpc/task/mod.rs, rpc/mod.rs
6	Cookie has no Secure/SameSite → CSRF exposure	controller/login.rs:21-23

Full details and fix sketches: docs/security-review.md · docs/auth-flow.md · docs/issue-roadmap.md.

---

Security posture

• 🔴 S2 CRITICAL — dev cryptographic keys & DB credentials committed in .cargo/config.toml (decode to ASCII dev_only_pwd_key / dev_only_token_key).
• 🟠 S3 HIGH — password storage is keyed HMAC-SHA512, not a KDF (non-constant-time; offline crack >1M/sec). → recommends argon2id.
• 🟠 S8 HIGH — broken access control: ctx is ignored by base::db → IDOR.
• ✅ A03 Injection passes — sqlb is parameterized.

OWASP 2021: A03 ✅ · A09 Partial · A01/A02/A04/A05/A07/A08 ❌

---

Deployment readiness

Verdict: 0/10 — the container panic-crashes before binding port 8080.

Two independent startup panic conditions:

1. _dev_utils::init_dev() → hardcoded db hostname doesn't resolve (compose service is db_test).
2. ModelManager::new() → config() → missing SERVICE_DB_URL (compose doesn't inject it; .cargo/config.toml [env] doesn't apply to the bare binary).

Hardened Dockerfile, docker-compose.yaml, .env template, a ci.yml quality workflow, and 7 source fixes are provided in docs/deployment-operations.md.

---

Test plan

• P0 fixes — implement CTX insertion + _generate_token + validate_pwd bug + feature-gate _dev_utils + schema alignment (see docs/issue-roadmap.md).
• cargo fmt --check
• cargo clippy --all-targets -- -D warnings -W clippy::unwrap_used
• cargo test --all-features (requires live PostgreSQL)
• cargo audit (no supply-chain gate in CI today)
• cargo build --release --locked (after committing Cargo.lock)
• Docker: docker compose build && docker compose up → healthcheck passes on /health
• Manual: POST /api/login → 200 + auth-token cookie; POST /api/rpc with create_task → 200.

⚠️ Until P0 items 1 & 2 are fixed, login panics and /api/rpc returns 403 — manual testing will fail. The test plan above defines the target state after P0 remediation. Current effective test coverage ≈ 15% (4 running service-level tests; 4 no-op tests missing #[tokio::test]/#[test]).

---

Scope note

This PR contains:

1. The full v2 feature work (auth, crypt, RPC, model/store, Docker, CI) — ~93 of the 110 commits, pre-existing.
2. The project analysis + documentation (17 atomic commits, :memo: prefixed) — added via a multi-specialist review and consolidated here.

The analysis documents the codebase as-is, including the blockers above. No source fixes are applied in this PR — fixes are sequenced in the issue roadmap (P0 → P1 → P2 → P3).