feat: observability, auth hardening, and tenant isolation

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/CODEOWNERS

@@ -5,8 +5,10 @@
 * @YieldVault-RWA/core-maintainers
 
 # Tier 1: Smart Contracts & Value Transfer
-/contracts/ @YieldVault-RWA/contracts-maintainers @YieldVault-RWA/security-team
-/contracts/**/src/ @YieldVault-RWA/contracts-maintainers @YieldVault-RWA/security-team
+/contracts/ @Junirezz @contract-reviewers
+/contracts @Junirezz @contract-reviewers
+/contracts/**/src/ @Junirezz @contract-reviewers
+*.rs @rust-reviewers
 /deployments/ @YieldVault-RWA/contracts-maintainers
 
 # Tier 2: Backend Services & API Layer

.github/ISSUE_TEMPLATE/perf_regression.md

@@ -0,0 +1,52 @@
+---
+name: Performance Regression
+about: Report a backend latency regression, memory leak, or throughput degradation
+title: 'Perf: [Short description of performance regression]'
+labels: 'type: perf, scope: backend, status: needs-triage'
+assignees: 'YieldVault-RWA/backend-maintainers'
+---
+
+## ⚡ Summary
+Provide a concise overview of the performance regression, when it was detected, and its impact on backend latency, throughput, or resource consumption.
+
+## 🎯 Endpoint & Scope
+- **Endpoint**: e.g. `POST /api/v1/vault/deposit` or `GET /api/v1/transactions`
+- **Component Scope**: `scope: backend`
+- **Environment**: Production / Staging / Testnet / Local
+- **Deployment / Commit**: e.g. `sha-abcdef1` or `v1.4.2`
+
+## ⏱️ Latency & Performance Metrics (p95 before/after)
+- **p95 Before**: e.g. `45 ms` (historical baseline)
+- **p95 After**: e.g. `380 ms` (observed degraded latency)
+- **p99 Before / After**: e.g. `80 ms` / `750 ms`
+- **Memory / CPU Impact**: e.g. Node process memory grew from 250MB to 1.8GB (suspected memory leak)
+
+## 🚦 Traffic & Load (QPS)
+- **QPS**: e.g. `250 req/s` (or traffic rate during regression)
+- **Concurrency**: e.g. `50 concurrent connections`
+
+## 🎯 Expected SLO
+- **Expected SLO**: e.g. `Read P95 < 200 ms` / `Write P95 < 500 ms` (as defined in `docs/api/SLA_SLO.md` and `docs/nfr-baselines.json`)
+- **Error Budget Impact**: e.g. Consuming 15% of monthly error budget / SLO breach
+
+## 🗄️ DB Query Plan
+Attach the `EXPLAIN ANALYZE` execution plan, Prisma query trace, or slow query log below:
+
+```sql
+-- Paste EXPLAIN ANALYZE or slow query plan here
+```
+
+## 🔄 Repro Steps
+1. Configure load generator or HTTP client:
+2. Execute command or load script (e.g. `k6 run load-test.js` or `autocannon -c 50 -d 30s <endpoint>`):
+3. Send payload:
+4. Observe latency metric spike or memory growth in metrics dashboard:
+
+## 📊 Profiling & Diagnostic Evidence
+- **Flamegraph / Profiler Trace**: (Attach SVG or link to CPU flamegraph/pprof trace)
+- **Heap Snapshot / Memory Profile**: (Attach snapshot or leak analysis)
+- **Grafana / Prometheus Dashboard Link**:
+- **APM Trace IDs / OpenTelemetry Span**:
+
+## 📝 Additional Context
+Include any relevant recent PRs, schema migrations, database index changes, third-party RPC bottlenecks, or potential root cause hypotheses.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,91 @@
 # Pull Request Template
 
 ## 📋 Description
-Add a complete environment variable matrix (`docs/ENV_VARIABLE_MATRIX.md`) covering every env var consumed across the backend and frontend, with defaults, required flags, and production recommendations. Update `README.md` and `ENV_QUICK_REFERENCE.md` to link to the new document.
+<!-- Provide a clear, concise summary of the goal and changes in this PR -->
+
+### Goal
+<!-- What problem does this solve? Reference issue: Closes #123 -->
+
+### Changes
+<!-- Bullet points explaining the key modifications -->
+- 
 
 ## 🔗 Type of Change
 - [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
 - [ ] ✨ New feature (non-breaking change that adds functionality)
 - [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to change)
-- [x] 📚 Documentation update
+- [ ] 🌊 Wave submission (contract migration, architectural wave release, or protocol upgrade)
+- [ ] 📚 Documentation update
 - [ ] 🔒 Security improvement
+- [ ] ⚡ Performance optimization
+
+---
+
+## 🛡️ Risk Assessment
+
+<!-- Mandatory for all PRs to evaluate blast radius, particularly contract migrations & Wave submissions -->
+
+### Risk Level
+- [ ] 🟢 **Low**: Non-breaking change, documentation, style, or isolated helper refactoring
+- [ ] 🟡 **Medium**: API enhancement, frontend workflow update, non-critical dependency upgrade
+- [ ] 🟠 **High**: Core contract logic change, access control modification, financial accounting / share math
+- [ ] 🔴 **Critical**: Wave submission, contract storage migration, protocol upgrade touching vault funds
+
+### Blast Radius & Impact Analysis
+- [ ] Contract storage layout / data key migration involved
+- [ ] Value transfer, deposit/withdraw flow, or vault share calculation affected
+- [ ] External integration (Oracle, Soroban RPC, Bridge, Token contract) affected
+- [ ] Database schema migration or data backfill required
+- [ ] Breaking API or interface change affecting downstream clients
+- [ ] Zero blast radius (isolated tooling / documentation only)
+
+**Detailed Risk & Blast Radius Notes:**
+<!-- Describe specific failure modes, edge cases, affected components, and risk mitigations -->
+```
+```
+
+---
+
+## 🔄 Rollback Plan
+
+<!-- Detail the exact steps and strategy to revert this change if unexpected failures occur in production -->
+
+### Rollback Strategy & Feasibility
+- [ ] **Clean Git Revert**: Revertable with zero persistent state drift
+- [ ] **Contract Upgrade Rollback**: Tested rollback to previous contract WASM hash / implementation
+- [ ] **Database Migration Revert**: Reversible migration down-script tested and verified
+- [ ] **Feature Flag / Circuit Breaker**: Feature can be toggled off instantly without redeployment
+- [ ] **Emergency Pause**: Contract pause / freeze mechanism available to halt affected functions
+- [ ] **Forward-Only / Irreversible**: State migration cannot be cleanly reversed; emergency recovery runbook linked below
+
+### Rollback Trigger Criteria
+<!-- What specific conditions, metrics, or alerts will trigger an immediate rollback? (e.g. error rate > 1%, oracle divergence, tx reverts) -->
+- 
+
+### Step-by-Step Rollback Procedure
+<!-- List the exact operational sequence required to execute a rollback -->
+1. 
+2. 
+3. 
+
+---
+
+## ⚡ Performance Impact
+
+<!-- Evaluate gas usage, execution compute units, latency, throughput, and bundle size impact -->
+
+### Performance & Resource Assessment
+- [ ] Smart contract gas / compute units benchmarked (no regression > 5%, or justified below)
+- [ ] Backend API latency (p95/p99) and database query execution plans verified
+- [ ] Database indexing verified for newly queried columns (no table scans)
+- [ ] Frontend bundle size and Time to Interactive (TTI) verified
+- [ ] Memory allocation and leak checks verified (no memory leaks in long-running services)
+- [ ] No measurable performance impact (documentation, tests, or trivial changes)
+
+**Performance & Gas Profiling Summary:**
+<!-- Include before/after gas consumption numbers, query explain plans, or benchmark output -->
+```
+```
 
 ---
 
@@ -28,7 +105,6 @@ See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md) for detailed gui
 
   **If any checkbox cannot be verified, explain below:**
   ```
-  N/A — this PR contains only documentation changes. No smart contract code was modified.
   ```
 
 ### Slither Static Analysis Results
@@ -41,7 +117,6 @@ See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md) for detailed gui
 
   **If this PR has security findings, document them below:**
   ```
-  N/A — documentation-only PR. No contract or runtime code changed.
   ```
 
 ### Handling Security Findings
@@ -51,7 +126,6 @@ See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md) for detailed gui
 - [ ] Test case added to verify fix
 - [ ] Explain fix below:
   ```
-  N/A
   ```
 
 #### Option B: False Positive 🟡
@@ -62,7 +136,6 @@ See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md) for detailed gui
   - Evidence (code snippet, test case, or reference)
 - [ ] Reference number (e.g., FP-001):
   ```
-  N/A
   ```
 - [ ] Inline suppression added to code:
   ```solidity
@@ -75,53 +148,47 @@ See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md) for detailed gui
 - [ ] Added to Slither exclusions
 - [ ] Explain below:
   ```
-  N/A
   ```
 
 ---
 
 ## 📝 Testing
 
 ### Functional Testing
-- [x] Unit tests added/updated for changes
-- [x] Integration tests passing
-- [x] Manual testing completed and documented below:
+- [ ] Unit tests added/updated for changes
+- [ ] Integration tests passing
+- [ ] End-to-end (E2E) tests passing
+- [ ] Manual testing completed and documented below:
   ```
-  - Verified all variable names, defaults, and required flags against source files:
-    backend/src/index.ts, rateLimiter.ts, auth.ts, tracing.ts
-  - Cross-checked every .env.example, .env.local.example, .env.production.example
-    in both backend/ and frontend/
-  - Confirmed links in README.md and ENV_QUICK_REFERENCE.md resolve correctly
-  - No runtime code changed; no functional regression possible
   ```
 
 ### Security Testing
 - For state-changing functions:
   - [ ] Reentrancy test (if applicable): Verify re-entry is blocked
   - [ ] Access control test: Verify unauthorized access is rejected
-  - [ ] Boundary test: Verify edge cases are handled
+  - [ ] Boundary / Edge-case test: Verify limits, zero-amounts, and rounding behavior
 
 - For external integrations:
   - [ ] Return value verification test
-  - [ ] Failure scenario test
+  - [ ] Failure / timeout scenario test
 
 ### Test Coverage
-- [x] All new code paths have test coverage
-- [x] Security-critical paths have comprehensive test cases
-- [x] Coverage report: `N/A — documentation only, no executable code added`
+- [ ] All new code paths have test coverage
+- [ ] Security-critical paths have comprehensive test cases
+- [ ] Coverage report:
+  ```
+  ```
 
 ---
 
 ## 🚀 Deployment Notes
 
-No deployment steps required. This PR adds a Markdown file and updates two existing Markdown files only.
-
 ### Mainnet Readiness
 - [ ] This code is ready for production deployment
-- [x] All critical tests pass
+- [ ] All critical tests pass
 - [ ] Security review approved
-- [x] No temporary debug code
-- [x] No TODO comments
+- [ ] No temporary debug code
+- [ ] No TODO comments
 
 ### Breaking Changes
 If this PR introduces breaking changes:
@@ -136,10 +203,9 @@ If this PR introduces breaking changes:
 <!-- GitHub Actions will update this section -->
 
 ### Slither Analysis
-- ✓ Status: N/A — no contract code changed
+- ✓ Status:
 - 🔴 High/Medium findings: 0
 - 🟡 Low/Informational findings: 0
-- 🟢 No issues detected: documentation-only PR
 
 ### Related Documentation
 - [Security Checklist](docs/SECURITY_CHECKLIST.md) — Use for code review
@@ -150,17 +216,19 @@ If this PR introduces breaking changes:
 
 ## ✅ Reviewer Checklist
 
-**For code reviewers** (use this to guide your security-focused review):
+**For code reviewers** (use this to guide your review):
 
-- [x] PR author completed security checklist ✓
-- [x] All findings documented and categorized (fixed/false positive/excluded)
-- [x] Inline security comments are clear and justified
+- [ ] PR author completed Risk Assessment and Rollback Plan ✓
+- [ ] Performance and gas impact evaluated and verified ✓
+- [ ] PR author completed security checklist ✓
+- [ ] All findings documented and categorized (fixed/false positive/excluded)
+- [ ] Inline security comments are clear and justified
 - [ ] Tests cover security-critical code paths
 - [ ] No external calls bypass return value checks
 - [ ] Access control is properly enforced
 - [ ] State updates follow CEI pattern
 - [ ] Input validation is comprehensive
-- [x] Follow-up actions (if any) tracked in issues
+- [ ] Follow-up actions (if any) tracked in issues
 
 ---
 
@@ -176,15 +244,18 @@ If this PR introduces breaking changes:
 
 Before marking PR as ready for review:
 
-- [x] Description is clear and concise
-- [x] All security checklist items checked (✅ or explanation provided)
-- [x] All tests passing locally: `npm test`
-- [x] Linter passing: `npm run lint`
+- [ ] Description, Goal, and Changes are clearly stated
+- [ ] Risk Assessment completed with appropriate risk tier and blast radius
+- [ ] Rollback Plan completed with concrete steps and trigger criteria
+- [ ] Performance Impact assessed with gas / compute benchmarks
+- [ ] All security checklist items checked (✅ or explanation provided)
+- [ ] All tests passing locally: `npm test`
+- [ ] Linter passing: `npm run lint`
 - [ ] Slither passing locally OR findings documented: `slither . --config-file slither.config.json`
-- [x] Code follows project style guide
-- [x] No merge conflicts
-- [x] Commits are clean and well-documented
-- [x] Branch is up-to-date with main/develop
+- [ ] Code follows project style guide
+- [ ] No merge conflicts
+- [ ] Commits are clean and well-documented
+- [ ] Branch is up-to-date with main/develop
 - [ ] For **release PRs**: `docs/RELEASE_READINESS_CHECKLIST.md` completed and linked in PR description
 
 ---

.github/SECURITY_REVIEW_CHECKLIST.md

@@ -0,0 +1,44 @@
+# Security Review Checklist — Secrets, PII & Transport
+
+**Use for:** any PR that adds/changes a data store, secret, credential, external integration, or network-facing endpoint.
+**Companion doc:** [`docs/security/encryption-review.md`](../docs/security/encryption-review.md) — full current-state review this checklist enforces going forward.
+**Not this checklist:** smart-contract vulnerability classes (reentrancy, access control, gas/DoS) are covered by [`docs/SECURITY_CHECKLIST.md`](../docs/SECURITY_CHECKLIST.md).
+
+---
+
+## 1. Secrets & Credentials
+
+- [ ] No secret, API key, private key, or credential is hardcoded or committed (checked by `gitleaks` in CI, but review the diff yourself too)
+- [ ] New secrets are read from `process.env` / GitHub Actions `secrets.*`, never from a config file checked into the repo
+- [ ] Any new required secret is documented in [`docs/ENV_VARIABLE_MATRIX.md`](../docs/ENV_VARIABLE_MATRIX.md)
+- [ ] Secrets that must exist in production fail startup loudly if missing or weak (follow the pattern in `backend/src/auth.ts`'s `assertJwtSecretValid()`) rather than silently falling back to a dev default
+- [ ] Tokens/keys are persisted as one-way hashes (SHA-256/HMAC or stronger), never in plaintext
+
+## 2. Data at Rest
+
+- [ ] New sensitive fields (PII, tokens, wallet-linked identifiers) are added to the correct model with the retention category noted in [`docs/DATA_RETENTION_DELETION_POLICY.md`](../docs/DATA_RETENTION_DELETION_POLICY.md)
+- [ ] Any new database, cache, or file-based store this PR introduces is confirmed to write to the *intended* backing store — verify the Prisma datasource / connection string actually points where you think it does (see `docs/security/encryption-review.md` §4 F1 for a real example of this silently going wrong)
+- [ ] No secret or PII value is written to logs, error messages, or audit trails in plaintext — check against `backend/src/auditRedaction.ts`'s redaction patterns
+
+## 3. Data in Transit
+
+- [ ] All new outbound calls (webhooks, RPC, third-party APIs) use `https://` / `wss://`, never plaintext `http://`
+- [ ] New database or cache connection strings enforce TLS (`sslmode=require` for Postgres, `rediss://` for Redis) where the backing service supports it
+- [ ] New cookies (if any) set `Secure`, `HttpOnly`, and an explicit `SameSite` — this repo's auth model currently uses Bearer tokens, not cookies, so introducing a cookie is a deliberate change worth flagging in the PR description
+- [ ] CORS changes stay within an explicit origin allowlist — no `*` or broad regex in `CORS_ALLOWED_ORIGINS`
+
+## 4. PII & Sensitive Data Handling
+
+- [ ] User-identifying data (wallet address, email, IP) is only collected/stored where there's a documented purpose in [`docs/DATA_RETENTION_DELETION_POLICY.md`](../docs/DATA_RETENTION_DELETION_POLICY.md)
+- [ ] Frontend `localStorage`/`sessionStorage` usage stores no private keys, JWTs, or API keys — only public/non-sensitive values (wallet address, UI prefs, session timestamps)
+- [ ] New admin or export endpoints that expose PII/financial data are gated by the correct RBAC role and rate-limited
+
+## 5. If This PR Touches Any of the Findings in `docs/security/encryption-review.md`
+
+- [ ] Confirm which finding (F1–F6) this PR addresses, if any
+- [ ] Update the finding's status in `docs/security/encryption-review.md` in the same PR
+- [ ] If this PR resolves a finding, note it in the PR description so reviewers can verify against the documented evidence
+
+---
+
+**If any box above cannot be checked**, explain why in the PR description rather than leaving it silently unchecked — a documented exception is reviewable; a missing explanation is not.