Skip to content

Commit 451d82c

Browse files
Merge pull request #10 from madijonovsardorbek544-cmyk/conduct-full-technical-audit
Harden controlled beta foundation
2 parents cf5cd20 + 5b7d04d commit 451d82c

20 files changed

Lines changed: 773 additions & 382 deletions

.github/workflows/deploy.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ jobs:
4343
echo "No test files found; skipping tests."
4444
fi
4545
46+
- name: Run E2E-style flow tests
47+
run: npm run test:e2e
48+
4649
- name: Build
4750
run: npm run build
4851

README.md

Lines changed: 52 additions & 172 deletions
Large diffs are not rendered by default.

docs/BETA_QA_CHECKLIST.md

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,37 @@
1-
# Controlled Beta Manual QA Checklist
1+
# Beta QA Checklist
22

3-
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.
3+
Run this before sharing any controlled-beta link. Expected result should be recorded as pass/fail with notes. Do not use raw private messages during QA.
44

5-
| Area | Manual step | Expected result |
5+
| Area | Manual QA step | Expected result |
66
| --- | --- | --- |
7-
| 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. |
8-
| 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. |
9-
| 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. |
10-
| Scholarship scam demo | Select “Scholarship fee scam” and run analysis. | Result shows scholarship/payment/sensitive-data risk indicators and safe verification steps. |
11-
| 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. |
12-
| 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. |
13-
| 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. |
14-
| 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. |
15-
| 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. |
16-
| 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. |
17-
| Dashboard sample mode | Select sample source mode. | Dashboard clearly labels sample/synthetic data and does not imply real institution metrics. |
18-
| Eval dashboard | Open `#eval`. | Evaluation dashboard loads and shows total examples plus guardrails that benchmark results are not real-world accuracy. |
19-
| Case library search | Open `#cases`, search for `visa`, `housing`, or `IELTS`, and use filters. | Results filter without crashing; empty states are understandable. |
20-
| 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. |
21-
| Privacy page | Open `#privacy`. | Page explains local analysis, redacted reports, structured feedback, and limits of local/Firebase storage. |
22-
| Mobile width | Test around 375px width. | Navigation, forms, results, report preview, and dashboard controls remain usable without horizontal scrolling. |
23-
| Browser back/forward | Navigate home → checker → cases → dashboard, then use browser back/forward. | Visible page and URL hash stay consistent. |
24-
| Refresh direct routes | Refresh on `#checker` and `#eval`. | Correct page loads directly after refresh. |
25-
| Invalid route | Open an invalid hash such as `#not-real`. | App falls back safely to home and normal navigation still works. |
26-
| 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. |
27-
| 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. |
28-
| 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. |
7+
| Homepage | Open the deployed site or local preview. | Homepage loads with public MVP/beta status and no production-ready claims. |
8+
| Homepage CTA | Click “Check a suspicious message.” | `#checker` opens the checker. |
9+
| Checker demo | Select “Bank/card phishing” and analyze. | Result is high or critical; account/card/identity/click indicators and verification script appear. |
10+
| Scholarship demo | Select “Scholarship fee scam” and analyze. | Result shows scholarship/payment/guarantee-style risk indicators. |
11+
| Legitimate reminder | Test a normal university portal reminder. | Result remains low/medium, not high/critical. |
12+
| Custom suspicious message | Enter a synthetic suspicious message with context. | Result appears with safe next steps and no certainty claims. |
13+
| Verification script | Click copy script. | Script copies or browser gracefully blocks; text remains visible. |
14+
| Feedback | Save anonymous feedback. | Success message appears; feedback contains structured fields only. |
15+
| Report preview | Open `#report`, enter synthetic/redacted text. | Redacted preview appears and consent is required. |
16+
| Report local save | Submit with Firebase unconfigured. | Report saves locally with localStorage warning and report ID. |
17+
| Dashboard local | Open dashboard and choose local mode. | Saved report appears; local mode warning is visible. |
18+
| Dashboard sample | Choose sample mode. | It is clearly labeled synthetic sample data only. |
19+
| Dashboard Firebase | Choose Firebase mode. | It clearly states Firebase querying is not connected/not decision-ready. |
20+
| Eval dashboard | Open `#eval`. | Evaluation dashboard loads and shows total benchmark examples and limitations. |
21+
| Case search | Open `#cases`, search for IELTS/housing/visa. | Cases filter or clean empty state appears. |
22+
| Resource packs | Review case library/resource cards. | Resource packs display with review/source limitations. |
23+
| Privacy page | Open `#privacy`. | Privacy page explains local analysis, redaction, feedback, and limits in practical language. |
24+
| Mobile width | Test at ~375px wide. | Navigation wraps, forms fit, buttons remain usable, no horizontal content loss. |
25+
| Back/forward | Navigate home → checker → cases → back/forward. | Visible page and hash stay aligned. |
26+
| Refresh hash route | Refresh/open direct `#checker`, `#cases`, `#report`, `#dashboard`, `#eval`. | Correct page remains visible. |
27+
| Invalid hash | Open `#not-real`. | App falls back cleanly to home; no crash. |
28+
| Feedback storage | Inspect `localStorage.crossBorderScamSafety.feedback.v1`. | No raw, redacted, full, or unredacted message appears. |
29+
| Report storage | Inspect `localStorage.crossBorderScamSafety.reports.v1`. | Only redacted report payload is stored; no raw message appears. |
30+
31+
## Release gate
32+
33+
- `npm install` passes for existing dependencies.
34+
- `npm test` passes.
35+
- `npm run build` passes.
36+
- `npm run test:e2e` passes.
37+
- If any privacy/storage test fails, stop the beta.

docs/CONTROLLED_BETA_GUIDE.md

Lines changed: 62 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -2,88 +2,91 @@
22

33
## Current status
44

5-
- **Ready for self-testing and small student/friend testing** with clear disclaimers and privacy instructions.
6-
- **Ready for counselor feedback** on wording, workflows, safe-next-step usefulness, and resource gaps.
7-
- **Not ready for an education-center pilot** until Firebase/rules/security and data governance are validated.
8-
- **Not ready for paid institution use** and must not be marketed as certified fraud detection.
5+
This product is ready for **self-testing**, **5–10 trusted student/friend testers**, and **counselor feedback** after the QA checklist passes. It is **not ready** for full education-center pilots, paid institution use, or production Firebase dashboards.
96

107
## Who can test now
118

12-
- The project owner.
13-
- Trusted friends or students who understand this is an educational MVP under validation.
14-
- Counselors or international-student support staff reviewing content and workflow, not relying on it for operational decisions.
9+
- The project owner/founder.
10+
- Trusted international students or recent applicants who understand this is under validation.
11+
- Parents/friends using synthetic or safely redacted messages.
12+
- Counselors/advisers reviewing language, workflows, and escalation guidance.
1513

1614
## Who should not use it yet
1715

18-
- Students in urgent financial, immigration, housing, safety, or law-enforcement situations without human support.
19-
- Minors unless a trusted adult/counselor is involved.
20-
- Education centers or institutions needing production records, dashboards, retention, deletion, or admin access.
21-
- Paid customers or anyone expecting guaranteed fraud detection.
16+
- Schools or education centers making operational decisions.
17+
- Paid institution customers.
18+
- Minors testing alone without a trusted adult/counselor.
19+
- Anyone facing immediate financial loss, threats, self-harm risk, immigration deadlines, or account compromise without human support.
2220

2321
## What testers must be told
2422

25-
- The checker detects **risk indicators**, not certainty.
26-
- It can miss scams and can over-score legitimate messages.
27-
- It does not replace official university, embassy, bank, police, legal, immigration, or emergency channels.
28-
- The checker runs locally by default, but optional reports are still best-effort redacted and should be reviewed carefully.
29-
- Local reports and feedback in localStorage are browser-only and not encrypted institutional storage.
23+
- The tool detects **risk indicators**, not certainty.
24+
- It is educational and under validation.
25+
- It does not provide legal, immigration, financial, emergency, or law-enforcement advice.
26+
- Checker analysis runs locally by default.
27+
- Redacted reporting is best effort and requires preview review.
28+
- localStorage reports are browser-only, not encrypted, and not institutional records.
29+
- Firebase dashboard mode is not connected unless a secure Firebase implementation and governance review are completed.
3030

31-
## What testers must not paste
31+
## What data testers must not paste
3232

33-
Tell testers not to paste:
33+
Do not paste:
3434

35-
- passport scans or full passport numbers,
36-
- student IDs,
37-
- card or bank-account numbers,
38-
- passwords, OTPs, PINs, recovery codes, or login links,
39-
- exact home addresses,
40-
- private documents or screenshots with personal data,
41-
- names/contact details of real people unless removed first.
35+
- Passport scans or passport numbers.
36+
- Student IDs, national IDs, visa numbers, SEVIS/CAS/I-20 identifiers.
37+
- Card numbers, bank details, CVV, PINs, passwords, OTPs, recovery codes.
38+
- Exact addresses, phone numbers, personal email addresses, names of minors.
39+
- Private documents, screenshots with personal data, or legal/immigration files.
4240

43-
## How to collect feedback safely
41+
## Safe testing with synthetic messages
4442

45-
- Prefer structured observations: “Which warning was confusing?” “Did the script help?” “Was the risk level too high/too low?”
46-
- Do not ask testers to send raw suspicious messages in chat, email, forms, or screenshots.
47-
- If examples are needed, ask testers to paraphrase and remove identifiers.
48-
- Summarize trends by category, channel, country/destination context, and risk indicator—not by raw message text.
43+
- Start with built-in demo messages.
44+
- Create synthetic examples by scenario: scholarship fee, visa threat, fake housing deposit, bank/card phishing, testing score upgrade.
45+
- Do not use real names, exact institutions, or real account numbers.
46+
- Record only category, risk level, whether the explanation made sense, and next-step clarity.
4947

50-
## How to handle suspicious real messages
48+
## Safe testing with real messages after redaction
5149

52-
1. Ask the tester to stop before paying, clicking, replying, or sending documents.
53-
2. Have them verify through a published official channel typed manually or a saved official app/bookmark.
54-
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.
55-
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.
50+
- Remove names, IDs, exact URLs, account numbers, addresses, phone numbers, and institution-specific identifiers before testing.
51+
- Prefer summarizing the scenario instead of pasting full text.
52+
- Use the report page only after reviewing the redacted preview.
53+
- If redaction misses something, stop and clear the form/local data.
5654

57-
## When to stop testing
55+
## How to collect feedback without raw messages
56+
57+
- Use the anonymous feedback controls in the result card.
58+
- Use `docs/FEEDBACK_ANALYSIS_TEMPLATE.md` for sessions.
59+
- Store categories and structured observations only.
60+
- Never paste raw messages into docs, issues, pull requests, emails, spreadsheets, or chat.
5861

59-
Stop the beta session if:
62+
## When to stop testing
6063

61-
- a tester is distressed, pressured, or in immediate danger,
62-
- a tester starts sharing private documents or secrets,
63-
- the app gives confusing guidance for a high-stakes issue,
64-
- Firebase/dashboard behavior appears connected when it is not,
65-
- localStorage contains raw message text unexpectedly,
66-
- a counselor identifies unsafe or misleading wording.
64+
Stop immediately if:
6765

68-
## When counselor review is needed
66+
- A tester pastes highly sensitive data.
67+
- A tester is scared, pressured, or confused about a real deadline.
68+
- A result appears to encourage unsafe action.
69+
- A legitimate message scores high/critical and the user may ignore an important official deadline.
70+
- A high-risk message scores low and the tester might proceed unsafely.
71+
- localStorage or Firebase behavior is unclear.
6972

70-
Counselor/international-office review is needed before using examples or guidance for:
73+
## When to involve a counselor/adult
7174

72-
- visa or immigration deadlines,
73-
- tuition/payment diversion,
74-
- housing deposits,
75-
- scholarship/admission claims,
76-
- minors or vulnerable students,
77-
- country-specific official resources,
78-
- escalation paths after money or documents are shared.
75+
Involve a counselor, trusted adult, bank, official school office, or relevant authority when:
7976

80-
## How to summarize results without raw messages
77+
- Money, deposits, tuition, refunds, cards, bank accounts, passwords, OTPs, or identity documents are involved.
78+
- A student is a minor.
79+
- The message threatens visa cancellation, deportation, admission loss, account closure, or housing loss.
80+
- The student already clicked, paid, or shared data.
81+
- The student feels afraid or pressured.
8182

82-
Use aggregate, non-identifying notes such as:
83+
## How to summarize feedback safely
8384

84-
- “3 testers found the verification script useful.”
85-
- “2 testers were confused by local vs Firebase dashboard mode.”
86-
- “Scholarship-fee examples were understood; housing-deposit examples need clearer next steps.”
87-
- “One custom message triggered high risk due to urgency + payment + sensitive-data requests.”
85+
Use broad categories:
8886

89-
Do not include raw messages, names, exact phone numbers, email addresses, URLs, passport/student IDs, card/bank details, or screenshots in beta summaries.
87+
- Scenario category, not message text.
88+
- Expected/actual risk level.
89+
- Whether next steps were understood.
90+
- Whether wording felt too scary, too certain, or unclear.
91+
- False-positive/missed-risk notes without identifiers.
92+
- Privacy concerns and feature requests.

docs/FEEDBACK_ANALYSIS_TEMPLATE.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Controlled Beta Feedback Analysis Template
2+
3+
## Do not store raw messages in this document
4+
5+
Do **not** paste suspicious messages, screenshots, names, passport/student ID numbers, card/bank details, OTPs, addresses, phone numbers, email addresses, or exact URLs. Summarize only structured, non-identifying observations.
6+
7+
## Session metadata
8+
9+
- Date:
10+
- Tester group:
11+
- Number of testers:
12+
- Number of tests:
13+
- Tester regions/languages, if safe to summarize broadly:
14+
- Facilitator:
15+
16+
## Messages tested
17+
18+
Use categories only. Do not paste raw text.
19+
20+
| Category | Synthetic / redacted real / legitimate | Count | Notes without raw text |
21+
| --- | --- | ---: | --- |
22+
| Bank/card phishing | | | |
23+
| Scholarship | | | |
24+
| Visa/embassy | | | |
25+
| Housing | | | |
26+
| Tuition/payment | | | |
27+
| Testing | | | |
28+
| Education agent | | | |
29+
| Legitimate institution message | | | |
30+
| Borderline unclear | | | |
31+
32+
## User understanding
33+
34+
- Did users understand the result?
35+
- Did users know the next step?
36+
- Did users understand “risk indicators detected” is not certainty?
37+
- Did users understand when to involve a counselor/adult?
38+
- Did users understand not to paste private documents or secrets?
39+
40+
## Emotional/safety response
41+
42+
- Did users feel scared, confused, reassured, or overconfident?
43+
- Did any wording feel accusatory or too certain?
44+
- Did any result encourage unsafe action?
45+
- Did any tester need immediate counselor/adult support?
46+
47+
## Calibration
48+
49+
- False positives:
50+
- Missed risks:
51+
- Unclear language:
52+
- Legitimate messages that scored too high:
53+
- Risky messages that scored too low:
54+
55+
## Privacy concerns
56+
57+
- Any tester hesitated to paste data?
58+
- Any tester pasted data they should not have pasted?
59+
- Did redaction preview help?
60+
- Did localStorage warning make sense?
61+
- Any requested deletion/clear-local-data support?
62+
63+
## Feature requests
64+
65+
- Requested scenarios:
66+
- Requested languages:
67+
- Requested counselor features:
68+
- Requested institution features:
69+
- Requested privacy controls:
70+
71+
## Decision
72+
73+
Choose one and explain why without raw messages.
74+
75+
- Continue controlled beta
76+
- Revise before more testing
77+
- Stop testing and fix safety/privacy issue
78+
79+
## Follow-up tasks
80+
81+
1.
82+
2.
83+
3.
84+
4.
85+
5.

0 commit comments

Comments
 (0)