Merge pull request #9 from madijonovsardorbek544-cmyk/prepare-project-for-controlled-beta-testing

Prepare controlled beta QA readiness

Author: madijonovsardorbek544-cmyk

README.md

@@ -8,11 +8,21 @@ This is a public MVP under validation hosted on GitHub Pages. It is being built
 
 ## Readiness status
 
+### Controlled beta status
+
 - Ready for self-testing and controlled friends/student feedback with clear disclaimers.
-- Partially ready for counselor review of wording, workflows, and resource gaps.
+- Ready for counselor feedback on wording, workflow, safe-next-step usefulness, and resource gaps.
 - Not ready for education-center or institution pilots until Firebase configuration, Firestore rules emulator tests, data retention, admin access, and human validation are completed.
 - Not ready for paid institution use. It is not certified fraud detection and must not be marketed as guaranteed scam detection.
 - Sample dashboard data is synthetic/sample data, not real institution data. Local dashboard data exists only in the user's browser.
+- Firebase dashboard mode is **not connected yet**; it is a labeled placeholder until authenticated Firestore queries, rules tests, retention, deletion, and admin access are implemented.
+- Local reports are browser-only localStorage records. They are not encrypted, not synced, and not institutional storage.
+
+Controlled beta references:
+
+- [Manual beta QA checklist](docs/BETA_QA_CHECKLIST.md)
+- [Controlled beta guide](docs/CONTROLLED_BETA_GUIDE.md)
+- [Firebase rules test plan](docs/FIREBASE_RULES_TEST_PLAN.md)
 
 ## Positioning
 
@@ -55,6 +65,19 @@ React + Vite + TypeScript
 
 Routing remains hash-based and the Vite base path remains `/cross-border-scam-analyzer/` for GitHub Pages.
 
+## Controlled beta testing
+
+Automated coverage includes analyzer/privacy regression tests and jsdom-based controlled-beta flow tests for hash routing, homepage CTAs, the bank/card phishing demo, feedback storage, local redacted reports, dashboard local mode, case search, eval dashboard loading, and invalid-route fallback. Playwright E2E was attempted for this pass, but package installation was blocked by registry policy (`403 Forbidden` for `@playwright/test`), so browser E2E remains a pre-pilot TODO.
+
+Run:
+
+```bash
+npm test
+npm run build
+```
+
+Before any institution pilot, also implement the emulator suite in [Firebase rules test plan](docs/FIREBASE_RULES_TEST_PLAN.md).
+
 ## Evaluation-driven analyzer
 
 The analyzer uses transparent rules and combination boosts rather than fake AI claims. Rules cover urgency, account lock threats, identity verification, click/action pressure, credential/OTP risk, financial account/card risk, authority impersonation, sensitive-data requests, payment pressure, suspicious links/domains, unofficial payment methods, vague institutions, unrealistic guarantees, visa threats, housing scarcity, test-score upgrade claims, personal-account payments, cross-border bureaucracy confusion, language mismatch, and platform risk.

docs/BETA_QA_CHECKLIST.md

@@ -0,0 +1,28 @@
+# Controlled Beta Manual QA Checklist
+
+Use this checklist before sharing a beta link with students, friends, or counselors. Record browser, device, date, build/commit, and whether Firebase environment variables were configured.
+
+| Area | Manual step | Expected result |
+| --- | --- | --- |
+| Live site | Open the live site URL. | Homepage loads without console-breaking errors and clearly says this is an educational MVP that detects risk indicators, not certainty. |
+| Homepage CTAs | Click “Check a suspicious message,” “View case library,” and “Explore institution pilot.” | Each CTA updates the hash route and shows the expected page without a full app failure. |
+| Bank/card phishing demo | Open `#checker`, select “Bank/card phishing,” and run analysis. | Result is high or critical; account/card/identity/click indicators appear in top reasons or analyst view. |
+| Scholarship scam demo | Select “Scholarship fee scam” and run analysis. | Result shows scholarship/payment/sensitive-data risk indicators and safe verification steps. |
+| Legitimate university reminder | Paste a normal university reminder that points to the official portal and does not request unusual payment or secrets. | Result remains low or medium and copy warns that legitimate messages can still be verified. |
+| Custom suspicious message | Paste a short custom suspicious message, then enter a real country/region and destination country. | Analysis button enables only after required fields are present; result avoids fraud-certainty language. |
+| Copy script | In the result page, use the copyable verification script control or confirm the script is visible if clipboard permissions are blocked. | Script is readable, official-channel oriented, and does not tell the student to click suspicious links. |
+| Save feedback | Save anonymous feedback after analysis. | Loading state appears, then success indicates storage mode; local fallback warning appears if Firebase failed; raw message is not included. |
+| Submit local report | Open `#report`, paste text, review redacted preview, enter country/destination, consent, and submit with Firebase unconfigured. | Report saves locally only, shows browser-only warning, and offers dashboard navigation. |
+| Dashboard local mode | Open `#dashboard`, select local report source mode. | Locally saved redacted report appears in metrics/trends; dashboard states local mode is browser-only and no raw messages are included. |
+| Dashboard sample mode | Select sample source mode. | Dashboard clearly labels sample/synthetic data and does not imply real institution metrics. |
+| Eval dashboard | Open `#eval`. | Evaluation dashboard loads and shows total examples plus guardrails that benchmark results are not real-world accuracy. |
+| Case library search | Open `#cases`, search for `visa`, `housing`, or `IELTS`, and use filters. | Results filter without crashing; empty states are understandable. |
+| Report redaction preview | Paste text containing an email, phone, passport-like ID, URL, and card-like number. | Preview replaces sensitive patterns where detected; user is warned redaction is best effort. |
+| Privacy page | Open `#privacy`. | Page explains local analysis, redacted reports, structured feedback, and limits of local/Firebase storage. |
+| Mobile width | Test around 375px width. | Navigation, forms, results, report preview, and dashboard controls remain usable without horizontal scrolling. |
+| Browser back/forward | Navigate home → checker → cases → dashboard, then use browser back/forward. | Visible page and URL hash stay consistent. |
+| Refresh direct routes | Refresh on `#checker` and `#eval`. | Correct page loads directly after refresh. |
+| Invalid route | Open an invalid hash such as `#not-real`. | App falls back safely to home and normal navigation still works. |
+| No raw message in feedback | After saving feedback, inspect localStorage key `crossBorderScamSafety.feedback.v1`. | Stored feedback contains structured score/context/tactic data only; it does not contain raw, redacted, full, or original message text. |
+| No raw message in local reports | After saving a report, inspect localStorage key `crossBorderScamSafety.reports.v1`. | Stored report contains redacted payload only; original raw message is not present. |
+| Clear local reports | Use “Clear saved local reports” on the report page and confirm. | Local reports are removed from browser localStorage; the control warns this is not institutional storage. |

docs/CONTROLLED_BETA_GUIDE.md

@@ -0,0 +1,89 @@
+# Controlled Beta Guide
+
+## Current status
+
+- **Ready for self-testing and small student/friend testing** with clear disclaimers and privacy instructions.
+- **Ready for counselor feedback** on wording, workflows, safe-next-step usefulness, and resource gaps.
+- **Not ready for an education-center pilot** until Firebase/rules/security and data governance are validated.
+- **Not ready for paid institution use** and must not be marketed as certified fraud detection.
+
+## Who can test now
+
+- The project owner.
+- Trusted friends or students who understand this is an educational MVP under validation.
+- Counselors or international-student support staff reviewing content and workflow, not relying on it for operational decisions.
+
+## Who should not use it yet
+
+- Students in urgent financial, immigration, housing, safety, or law-enforcement situations without human support.
+- Minors unless a trusted adult/counselor is involved.
+- Education centers or institutions needing production records, dashboards, retention, deletion, or admin access.
+- Paid customers or anyone expecting guaranteed fraud detection.
+
+## What testers must be told
+
+- The checker detects **risk indicators**, not certainty.
+- It can miss scams and can over-score legitimate messages.
+- It does not replace official university, embassy, bank, police, legal, immigration, or emergency channels.
+- The checker runs locally by default, but optional reports are still best-effort redacted and should be reviewed carefully.
+- Local reports and feedback in localStorage are browser-only and not encrypted institutional storage.
+
+## What testers must not paste
+
+Tell testers not to paste:
+
+- passport scans or full passport numbers,
+- student IDs,
+- card or bank-account numbers,
+- passwords, OTPs, PINs, recovery codes, or login links,
+- exact home addresses,
+- private documents or screenshots with personal data,
+- names/contact details of real people unless removed first.
+
+## How to collect feedback safely
+
+- Prefer structured observations: “Which warning was confusing?” “Did the script help?” “Was the risk level too high/too low?”
+- Do not ask testers to send raw suspicious messages in chat, email, forms, or screenshots.
+- If examples are needed, ask testers to paraphrase and remove identifiers.
+- Summarize trends by category, channel, country/destination context, and risk indicator—not by raw message text.
+
+## How to handle suspicious real messages
+
+1. Ask the tester to stop before paying, clicking, replying, or sending documents.
+2. Have them verify through a published official channel typed manually or a saved official app/bookmark.
+3. If money, credentials, card data, documents, or OTPs were already shared, direct them to the relevant bank/payment provider, real institution, counselor, and appropriate local reporting channel.
+4. If the situation involves immediate danger, coercion, or a minor, stop product testing and involve a trusted adult, counselor, emergency service, or local authority as appropriate.
+
+## When to stop testing
+
+Stop the beta session if:
+
+- a tester is distressed, pressured, or in immediate danger,
+- a tester starts sharing private documents or secrets,
+- the app gives confusing guidance for a high-stakes issue,
+- Firebase/dashboard behavior appears connected when it is not,
+- localStorage contains raw message text unexpectedly,
+- a counselor identifies unsafe or misleading wording.
+
+## When counselor review is needed
+
+Counselor/international-office review is needed before using examples or guidance for:
+
+- visa or immigration deadlines,
+- tuition/payment diversion,
+- housing deposits,
+- scholarship/admission claims,
+- minors or vulnerable students,
+- country-specific official resources,
+- escalation paths after money or documents are shared.
+
+## How to summarize results without raw messages
+
+Use aggregate, non-identifying notes such as:
+
+- “3 testers found the verification script useful.”
+- “2 testers were confused by local vs Firebase dashboard mode.”
+- “Scholarship-fee examples were understood; housing-deposit examples need clearer next steps.”
+- “One custom message triggered high risk due to urgency + payment + sensitive-data requests.”
+
+Do not include raw messages, names, exact phone numbers, email addresses, URLs, passport/student IDs, card/bank details, or screenshots in beta summaries.

docs/FIREBASE_RULES_TEST_PLAN.md

@@ -0,0 +1,115 @@
+# Firebase Rules Test Plan Before Any Institution Pilot
+
+This project is not ready for an education-center or institution pilot until Firestore rules are tested with the Firebase emulator and the resulting checks run in CI.
+
+## Scope
+
+Collections covered by the first rules test suite:
+
+- `reports`
+- `anonymousFeedback`
+- representative public-deny checks for update/delete/read paths
+
+## Required tooling
+
+1. Add dev dependencies:
+   - `firebase-tools`
+   - `@firebase/rules-unit-testing`
+2. Add a script such as:
+   - `"test:rules": "firebase emulators:exec --only firestore \"vitest run firestore.rules.test.ts\""`
+3. Run with an isolated emulator project ID, for example `cross-border-scam-safety-rules-test`.
+
+## Exact tests to implement
+
+### Reports collection
+
+1. **Valid redacted report create is allowed**
+   - Create `/reports/{id}` with only allowed fields from `reportHasOnlyRedactedFields()`.
+   - Include `reportId`, `createdAtIso`, `redactedMessage`, `redactionCounts`, `highRiskMarkers`, `language`, `countryRegion`, `destinationCountry`, `platform`, `context`, `score`, `level`, `scamTypeGuess`, `consentVersion`, and `deletionInstructions`.
+   - Expected: `assertSucceeds`.
+
+2. **Report with `rawMessage` is denied**
+   - Add `rawMessage: "original text"` to an otherwise valid report.
+   - Expected: `assertFails`.
+
+3. **Report with `message` is denied**
+   - Add `message: "original text"`.
+   - Expected: `assertFails`.
+
+4. **Report with `fullMessage` is denied**
+   - Add `fullMessage: "original text"`.
+   - Expected: `assertFails`.
+
+5. **Report with `unredactedMessage` is denied**
+   - Add `unredactedMessage: "original text"`.
+   - Expected: `assertFails`.
+
+6. **Report with `attachments` is denied**
+   - Add `attachments: []` or any attachment-like metadata.
+   - Expected: `assertFails`.
+
+7. **Overlong redacted report is denied**
+   - Set `redactedMessage` to more than 5,000 characters.
+   - Expected: `assertFails`.
+
+8. **Public read of reports is denied**
+   - Try to read `/reports/{id}` as an unauthenticated client.
+   - Expected: `assertFails`.
+
+9. **Public update/delete of reports is denied**
+   - Try update and delete as an unauthenticated client.
+   - Expected: `assertFails`.
+
+### Anonymous feedback collection
+
+1. **Valid anonymous feedback create is allowed**
+   - Create `/anonymousFeedback/{id}` with only allowed structured fields from `feedbackHasOnlyStructuredFields()`.
+   - Include `id`, `createdAtIso`, `helpful`, `verifiedOfficialChannel`, `calibration`, `category`, `score`, `level`, `context`, `platform`, `tacticIds`, `riskAreaLevels`, `storageMode`, and `schemaVersion`.
+   - Expected: `assertSucceeds`.
+
+2. **Feedback with `rawMessage` is denied**
+   - Add `rawMessage`.
+   - Expected: `assertFails`.
+
+3. **Feedback with `message` is denied**
+   - Add `message`.
+   - Expected: `assertFails`.
+
+4. **Feedback with `redactedMessage` is denied**
+   - Add `redactedMessage`.
+   - Expected: `assertFails`.
+
+5. **Feedback with `fullMessage` is denied**
+   - Add `fullMessage`.
+   - Expected: `assertFails`.
+
+6. **Feedback with `unredactedMessage` is denied**
+   - Add `unredactedMessage`.
+   - Expected: `assertFails`.
+
+7. **Feedback with invalid enums is denied**
+   - Try `helpful: "maybe"`, `calibration: "unknown"`, or `level: "certain fraud"`.
+   - Expected: `assertFails`.
+
+8. **Public read of feedback is denied**
+   - Try unauthenticated read of `/anonymousFeedback/{id}`.
+   - Expected: `assertFails`.
+
+9. **Public update/delete of feedback is denied**
+   - Try update and delete as an unauthenticated client.
+   - Expected: `assertFails`.
+
+10. **Admin feedback read is allowed only with admin role claim**
+    - Read with auth token `{ role: "admin" }`.
+    - Expected: `assertSucceeds`.
+    - Read with no token or a non-admin token.
+    - Expected: `assertFails`.
+
+## CI go/no-go rule
+
+An education-center pilot must not start until:
+
+- all tests above pass in CI,
+- Firebase dashboard querying is either implemented behind authenticated role-based access or hidden/disabled,
+- data retention/deletion ownership is documented,
+- admin access and incident response are reviewed by a human privacy/security owner.