From 355f21b2e1de60093945587d65693f6d0f050c57 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:01:24 +0600 Subject: [PATCH 01/44] =?UTF-8?q?Passwords=20also=20refuse=20a=20distincti?= =?UTF-8?q?ve=20word=20of=20an=20institute's=20name,=20not=20only=20the=20?= =?UTF-8?q?whole=20name=20(P1-I,=20the=20owner's=20answer):=20the=20name?= =?UTF-8?q?=20is=20split=20at=20spaces,=20punctuation=20and=20symbols,=20g?= =?UTF-8?q?eneric=20words=20are=20dropped=20(school,=20college,=20madrasa,?= =?UTF-8?q?=20academy,=20coaching,=20high,=20model,=20=E0=A6=AC=E0=A6=BF?= =?UTF-8?q?=E0=A6=A6=E0=A7=8D=E0=A6=AF=E0=A6=BE=E0=A6=B2=E0=A6=AF=E0=A6=BC?= =?UTF-8?q?,=20=E0=A6=89=E0=A6=9A=E0=A7=8D=E0=A6=9A,=20=E0=A6=B8=E0=A7=8D?= =?UTF-8?q?=E0=A6=95=E0=A7=81=E0=A6=B2,=20=E0=A6=AE=E0=A6=BE=E0=A6=A6?= =?UTF-8?q?=E0=A7=8D=E0=A6=B0=E0=A6=BE=E0=A6=B8=E0=A6=BE,=20=E0=A6=95?= =?UTF-8?q?=E0=A6=B2=E0=A7=87=E0=A6=9C,=20=E0=A6=95=E0=A7=8B=E0=A6=9A?= =?UTF-8?q?=E0=A6=BF=E0=A6=82=E2=80=A6=20and=20their=20spellings,=20GENERI?= =?UTF-8?q?C=5FNAME=5FWORDS),=20and=20every=20remaining=20word=20of=204=20?= =?UTF-8?q?or=20more=20code=20points=20is=20refused.=20Generic=20words=20g?= =?UTF-8?q?lued=20to=20the=20end=20of=20a=20word=20count=20without=20them?= =?UTF-8?q?=20too=20(=E0=A6=B6=E0=A6=BE=E0=A6=AA=E0=A6=B2=E0=A6=BE?= =?UTF-8?q?=E0=A6=89=E0=A6=9A=E0=A7=8D=E0=A6=9A=E0=A6=AC=E0=A6=BF=E0=A6=A6?= =?UTF-8?q?=E0=A7=8D=E0=A6=AF=E0=A6=BE=E0=A6=B2=E0=A6=AF=E0=A6=BC=20?= =?UTF-8?q?=E2=86=92=20=E0=A6=B6=E0=A6=BE=E0=A6=AA=E0=A6=B2=E0=A6=BE).=20Z?= =?UTF-8?q?ero-width=20joiners=20are=20ignored=20on=20both=20sides.=20So?= =?UTF-8?q?=20=E0=A6=B6=E0=A6=BE=E0=A6=AA=E0=A6=B2=E0=A6=BE=E0=A7=A8?= =?UTF-8?q?=E0=A7=A6=E0=A7=A8=E0=A7=AC=E0=A7=A7=E0=A7=A8=E0=A7=A9=E0=A7=AA?= =?UTF-8?q?=20is=20refused=20for=20"=E0=A6=B6=E0=A6=BE=E0=A6=AA=E0=A6=B2?= =?UTF-8?q?=E0=A6=BE=20=E0=A6=89=E0=A6=9A=E0=A7=8D=E0=A6=9A=20=E0=A6=AC?= =?UTF-8?q?=E0=A6=BF=E0=A6=A6=E0=A7=8D=E0=A6=AF=E0=A6=BE=E0=A6=B2=E0=A6=AF?= =?UTF-8?q?=E0=A6=BC"=20and=20kodomtola@2026=20for=20"Kodom=20Tola=20Schoo?= =?UTF-8?q?l";=20=E0=A6=AC=E0=A6=BF=E0=A6=A6=E0=A7=8D=E0=A6=AF=E0=A6=BE?= =?UTF-8?q?=E0=A6=B2=E0=A6=AF=E0=A6=BC=E0=A7=A8=E0=A7=A6=E0=A7=A8=E0=A7=AC?= =?UTF-8?q?=E0=A7=A7=E0=A7=A8=20and=20school2026xyz=20are=20not.=20The=20f?= =?UTF-8?q?orm=20and=20its=20messages=20say=20"the=20institute's=20name=20?= =?UTF-8?q?or=20a=20word=20from=20it"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- apps/api/test/password-set.e2e-spec.ts | 3 + apps/web/messages/account/password.bn.json | 4 +- apps/web/messages/account/password.en.json | 4 +- docs/auth.md | 8 ++- docs/demo-accounts.md | 6 +- packages/shared/src/password.test.ts | 62 +++++++++++++++++ packages/shared/src/password.ts | 79 +++++++++++++++++++++- 7 files changed, 155 insertions(+), 11 deletions(-) diff --git a/apps/api/test/password-set.e2e-spec.ts b/apps/api/test/password-set.e2e-spec.ts index 6c9cdff..4faa482 100644 --- a/apps/api/test/password-set.e2e-spec.ts +++ b/apps/api/test/password-set.e2e-spec.ts @@ -390,6 +390,9 @@ describe('staff set their own password', () => { ).body.accessToken as string; expect(await rejected(token, 'my KODOM tola school!')).toEqual(['HAS_INSTITUTE_NAME']); expect(await rejected(token, 'বকুলকোচিংসেন্টার২০২৬')).toEqual(['HAS_INSTITUTE_NAME']); + // A distinctive word of either name is enough (P1-I); generic words alone are not. + expect(await rejected(token, 'kodom@2026 rain')).toEqual(['HAS_INSTITUTE_NAME']); + expect(await rejected(token, 'বকুল২০২৬১২৩৪৫')).toEqual(['HAS_INSTITUTE_NAME']); await passTime(phone, userId); const code = await codeFor(token, phone); await setPassword(token, code, GOOD).expect(204); diff --git a/apps/web/messages/account/password.bn.json b/apps/web/messages/account/password.bn.json index 3f3066c..b26d3bb 100644 --- a/apps/web/messages/account/password.bn.json +++ b/apps/web/messages/account/password.bn.json @@ -21,7 +21,7 @@ "rules": "পাসওয়ার্ডের নিয়ম", "ruleLength": "কমপক্ষে {min}টি অক্ষর (বাংলা, ইংরেজি, সংখ্যা বা চিহ্ন, যেকোনোটি)", "rulePhone": "আপনার মোবাইল নম্বর থাকবে না", - "ruleInstitute": "প্রতিষ্ঠানের নাম থাকবে না", + "ruleInstitute": "প্রতিষ্ঠানের নাম বা নামের কোনো শব্দ থাকবে না", "mismatch": "দুটি পাসওয়ার্ড মিলছে না।", "submit": "পাসওয়ার্ড সেট করুন", "saving": "সেট হচ্ছে…", @@ -33,7 +33,7 @@ "TOO_SHORT": "খুব ছোট: কমপক্ষে {min}টি অক্ষর লাগবে।", "TOO_LONG": "খুব বড়: সর্বোচ্চ {max}টি অক্ষর।", "HAS_PHONE": "এতে আপনার মোবাইল নম্বর আছে।", - "HAS_INSTITUTE_NAME": "এতে প্রতিষ্ঠানের নাম আছে।", + "HAS_INSTITUTE_NAME": "এতে প্রতিষ্ঠানের নাম বা নামের কোনো শব্দ আছে (বিদ্যালয়, কোচিং-এর মতো সাধারণ শব্দ চলবে)।", "TOO_COMMON": "এটি খুব সাধারণ পাসওয়ার্ড, সহজে অনুমান করা যায়। অন্য কিছু দিন।" } } diff --git a/apps/web/messages/account/password.en.json b/apps/web/messages/account/password.en.json index 29e55bf..d331838 100644 --- a/apps/web/messages/account/password.en.json +++ b/apps/web/messages/account/password.en.json @@ -21,7 +21,7 @@ "rules": "Password rules", "ruleLength": "At least {min} characters (Bangla, English, digits or symbols, any of them)", "rulePhone": "Not your mobile number", - "ruleInstitute": "Not the institute's name", + "ruleInstitute": "Not the institute's name or a word from it", "mismatch": "The two passwords do not match.", "submit": "Set password", "saving": "Saving…", @@ -33,7 +33,7 @@ "TOO_SHORT": "Too short: at least {min} characters.", "TOO_LONG": "Too long: at most {max} characters.", "HAS_PHONE": "It contains your mobile number.", - "HAS_INSTITUTE_NAME": "It contains the institute's name.", + "HAS_INSTITUTE_NAME": "It contains the institute's name or a word from it (general words like school or coaching are fine).", "TOO_COMMON": "It is a very common password, easy to guess. Choose something else." } } diff --git a/docs/auth.md b/docs/auth.md index 7c0a45c..f3cbdc1 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -200,7 +200,13 @@ audited in that institute. Someone who is staff elsewhere switches to that insti - `HAS_PHONE`: the person's 10-digit national number, in any form (`01…`, `+880…`, Bangla digits, split by spaces, punctuation or symbols); - `HAS_INSTITUTE_NAME`: the whole name of any institute they are an active member of (as a - guardian too), ignoring case and spaces; names under 4 characters (code points) are skipped; + guardian too), or one of its distinctive words (P1-I), ignoring case, spaces and zero-width + joiners. Distinctive: the name split at spaces, punctuation and symbols, generic words + dropped (`GENERIC_NAME_WORDS` in `packages/shared/src/password.ts`: school, college, madrasa, + academy, coaching, high, model, বিদ্যালয়, উচ্চ, স্কুল, মাদ্রাসা, কলেজ, কোচিং… and their spellings), + and generic words glued to a word's end also counted without them (`শাপলাউচ্চবিদ্যালয়` → + `শাপলা`). Names and words under 4 characters (code points) are skipped. So for "শাপলা উচ্চ + বিদ্যালয়", `শাপলা২০২৬১২৩৪` is refused and `বিদ্যালয়২০২৬১২` is not; - `TOO_COMMON`: on the list in `apps/api/src/auth/common-passwords.txt` (SecLists' 10,000 most common, MIT; plus jantrik, bangladesh and password with digits and years). Server only; 3. the code, else `422 PASSWORD_CODE_INVALID` (wrong, expired or used). Checking the rules first diff --git a/docs/demo-accounts.md b/docs/demo-accounts.md index 48ae7ab..b85d823 100644 --- a/docs/demo-accounts.md +++ b/docs/demo-accounts.md @@ -20,9 +20,9 @@ the API log (`SMS_PROVIDER=console`). **Setting a password (staff only).** Sign in as any staff account above (with the code or the demo password), open the user menu → "পাসওয়ার্ড" / "Password", send the code (it is printed in the API log), then type it and the new password twice. The new password must be 10 to 128 characters -and must not contain the phone number, the institute's name or a common password. Your other -sessions of that account are signed out; this browser stays signed in. Guardians have no such -menu item: they sign in with a code only. +and must not contain the phone number, the institute's name (or a word from it such as শাপলা) or a +common password. Your other sessions of that account are signed out; this browser stays signed +in. Guardians have no such menu item: they sign in with a code only. ## Platform (Jantrik staff, `/platform`) diff --git a/packages/shared/src/password.test.ts b/packages/shared/src/password.test.ts index 8920a1f..5dde652 100644 --- a/packages/shared/src/password.test.ts +++ b/packages/shared/src/password.test.ts @@ -87,6 +87,68 @@ describe('password rules (S26, P1-C, P1-D)', () => { expect(passwordProblems('abcdefghijk', about)).toEqual([]); }); + describe('a distinctive word of an institute name (P1-I)', () => { + const named = (...instituteNames: string[]) => ({ phone: about.phone, instituteNames }); + const refused = (pw: string, ...names: string[]) => + expect(passwordProblems(pw, named(...names))).toContain('HAS_INSTITUTE_NAME'); + const allowed = (pw: string, ...names: string[]) => + expect(passwordProblems(pw, named(...names))).toEqual([]); + + it.each<[string, string]>([ + ['শাপলা২০২৬১২৩৪', 'শাপলা উচ্চ বিদ্যালয়'], + ['kodomtola@2026', 'Kodom Tola School'], + ['Kodom2026!!', 'Kodom Tola School'], + ['my tola 2026 x', 'Kodom Tola School'], + ['HUDA-2026-pass', 'Darul Huda Madrasah'], + ['highland2026', 'Highland Academy'], + ['বকুল২০২৬১২৩৪', 'বকুল কোচিং সেন্টার'], + ['st-joseph-2026', "St. Joseph's High School & College"], + ])('refuses %s for "%s"', (pw, name) => refused(pw, name)); + + it.each<[string, string]>([ + ['school2026xyz', 'Kodom Tola School'], + ['বিদ্যালয়২০২৬১২', 'শাপলা উচ্চ বিদ্যালয়'], + ['উচ্চ মাধ্যমিক ২০২৬', 'শাপলা উচ্চ মাধ্যমিক বিদ্যালয়'], + ['madrasah 2026 x', 'Darul Huda Madrasah'], + ['darul 2026 rain', 'Darul Huda Madrasah'], + ['highschool2026', 'Highland Academy'], + ['কোচিং সেন্টার ২০২৬', 'বকুল কোচিং সেন্টার'], + ['college 2026 x', "St. Joseph's High School & College"], + ])('allows %s for "%s" (generic words only)', (pw, name) => allowed(pw, name)); + + it('ignores words under 4 characters (code points), as for whole names', () => { + // আলো is three code points (আ ল ো), Alo three letters. + allowed('আলো২০২৬১২৩৪৫', 'আলো কোচিং সেন্টার'); + allowed('alo2026xyzw', 'Alo Coaching'); + allowed('abc 2026 rain', 'ABC Tola'); + refused('tola 2026 rain', 'ABC Tola'); + }); + + it('finds the distinctive part of a word glued to generic ones', () => { + refused('শাপলা২০২৬১২৩৪', 'শাপলাউচ্চবিদ্যালয়'); + refused('kodomtola2026', 'Kodomtolaschool'); + allowed('উচ্চবিদ্যালয়২০২৬', 'শাপলা উচ্চবিদ্যালয়'); + allowed('স্কুলঅ্যান্ডকলেজ১২', 'শাপলা স্কুল অ্যান্ড কলেজ'); + }); + + it('drops generic words whichever Unicode form either side was typed in', () => { + // য় as one code point (U+09DF) in the name, as য + nukta in the password, and the reverse. + const nameOne = 'শাপলা উচ্চ বিদ্যালয়'; + const nameTwo = 'শাপলা উচ্চ বিদ্যালয়'; + allowed('বিদ্যালয়২০২৬১২', nameOne); + allowed('বিদ্যালয়২০২৬১২', nameTwo); + refused('শাপলা২০২৬১২৩৪'.normalize('NFD'), nameOne); + // A zero-width joiner or non-joiner (typed in some Bangla words) is ignored on both sides. + allowed('মাদ্‌রাসা২০২৬১২', 'শাপলা মাদ্‌রাসা'); + refused('শা‌পলা২০২৬১২৩৪', 'শাপলা মাদ্রাসা'); + }); + + it('still refuses the whole name, generic words included', () => { + refused('alocoaching!!', 'Alo Coaching'); + refused('উচ্চবিদ্যালয়', 'উচ্চ বিদ্যালয়'); + }); + }); + it('reports every problem at once', () => { expect(passwordProblems('01711000002alocoaching', about).sort()).toEqual( ['HAS_INSTITUTE_NAME', 'HAS_PHONE'].sort(), diff --git a/packages/shared/src/password.ts b/packages/shared/src/password.ts index 24a60ea..5dfd7e4 100644 --- a/packages/shared/src/password.ts +++ b/packages/shared/src/password.ts @@ -23,9 +23,80 @@ export function normalizePassword(pw: string): string { return pw.normalize('NFC'); } -/** NFC, lower-case, without whitespace: how passwords and institute names are compared. */ +/** Zero-width joiner and non-joiner: typed inside some Bangla words (মাদ্‌রাসা), invisible. */ +const ZERO_WIDTH = /[‌‍]/gu; + +/** NFC, lower-case, without whitespace or zero-width joiners: how passwords and names compare. */ function comparable(text: string): string { - return text.normalize('NFC').toLowerCase().replace(/\s+/gu, ''); + return text.normalize('NFC').toLowerCase().replace(/\s+/gu, '').replace(ZERO_WIDTH, ''); +} + +/** + * Words many institutes' names share (P1-I): what kind of institute it is, its level, who it is + * for, its medium. They say nothing about which institute it is, so a password may contain them; + * every other word of 4 or more characters in the name is refused. Spelling variants are listed + * separately; Unicode forms (য় as one code point or two) need not be, `comparable` unifies them. + * English first (with Bangla words as written in English letters), then Bangla. + */ +export const GENERIC_NAME_WORDS: readonly string[] = ` + school schools college collegiate academy academic university madrasa madrasah madrassa + madrassah madrasha high higher secondary primary junior senior preparatory model ideal public + government govt cadet residential girls girl boys boy women womens ladies mohila mahila english + bangla medium version international coaching centre center institute institution kindergarten + kinder technical vocational polytechnic training tutorial laboratory islamia islamiya islamic + alia aliya aliah dakhil alim fazil kamil hafizia hafezia hifz hifzul tahfiz tahfizul quran + qawmi qaumi kawmi nurani noorani darul uloom ulum jamia jamea bidyalaya bidyaloy biddyaloy + vidyalaya bidyapith bidyaniketan niketan pathshala shikkha + বিদ্যালয় মহাবিদ্যালয় উচ্চ মাধ্যমিক নিম্ন প্রাথমিক জুনিয়র সিনিয়র স্কুল হাই কলেজ মাদ্রাসা + মাদরাসা একাডেমি একাডেমী বিশ্ববিদ্যালয় সরকারি সরকারী বেসরকারি বেসরকারী মডেল আদর্শ আইডিয়াল + পাবলিক ক্যাডেট আবাসিক রেসিডেন্সিয়াল বালিকা বালক মহিলা গার্লস বয়েজ ইংলিশ বাংলা মিডিয়াম ভার্সন + ইন্টারন্যাশনাল আন্তর্জাতিক কোচিং সেন্টার কেন্দ্র ইনস্টিটিউট ইন্সটিটিউট ইনস্টিটিউশন প্রতিষ্ঠান + কিন্ডারগার্টেন কিন্ডার টেকনিক্যাল কারিগরি ভোকেশনাল পলিটেকনিক প্রশিক্ষণ আলিয়া দাখিল আলিম ফাজিল + কামিল হাফিজিয়া হাফেজিয়া হিফজ হিফজুল তাহফিজুল কুরআন কোরআন নূরানী নুরানী কওমী কওমি ইসলামিয়া + ইসলামী ইসলামি দারুল উলুম জামিয়া পাঠশালা বিদ্যানিকেতন বিদ্যাপীঠ বিদ্যামন্দির নিকেতন শিক্ষা + শিক্ষালয় অ্যান্ড এন্ড এবং +` + .split(/\s+/u) + .filter((w) => w !== ''); + +const GENERIC = new Set(GENERIC_NAME_WORDS.map(comparable)); +const GENERIC_LIST = [...GENERIC]; + +/** + * Where the generic words glued to the end of a word start (`কোচিংসেন্টার` → 0, + * `শাপলাউচ্চবিদ্যালয়` → the index of উচ্চ), so `শাপলা` is found in a name typed without spaces. + * Only endings: names put the kind of institute last, and a generic word at the start of an + * ordinary word (`highland`) is not stripped. + */ +function genericTailStart(word: string): number { + // tail[i]: word.slice(i) is made of generic words only. + const tail: boolean[] = []; + tail[word.length] = true; + let start = word.length; + for (let i = word.length - 1; i >= 0; i--) { + tail[i] = GENERIC_LIST.some((g) => word.startsWith(g, i) && tail[i + g.length] === true); + if (tail[i]) start = i; + } + return start; +} + +const codePoints = (text: string): number => [...text].length; + +/** + * The words of an institute name that point at that institute (P1-I): split at spaces, + * punctuation and symbols, generic words dropped, 4 characters (code points) or more. A word with + * generic words glued to its end counts twice, whole and without them. + */ +export function distinctiveNameWords(name: string): string[] { + const words = new Set(); + const raw = name.normalize('NFC').toLowerCase().replace(ZERO_WIDTH, ''); + for (const word of raw.split(/[\p{P}\p{S}\s]+/u)) { + if (word === '') continue; + const stem = word.slice(0, genericTailStart(word)); + if (stem === '') continue; // only generic words + for (const w of [word, stem]) if (codePoints(w) >= MIN_NAME_LENGTH) words.add(w); + } + return [...words]; } /** The 10-digit national number (`17XXXXXXXX`) of a Bangladeshi phone, or null if there is none. */ @@ -54,10 +125,12 @@ export function passwordProblems( const passwordDigits = toAsciiDigits(password).replace(/[\p{P}\p{S}\s]/gu, ''); if (national && passwordDigits.includes(national)) problems.push('HAS_PHONE'); + // The whole name (generic words included), or one of its distinctive words (P1-I). const passwordText = comparable(password); const hasName = about.instituteNames.some((name) => { const n = comparable(name); - return [...n].length >= MIN_NAME_LENGTH && passwordText.includes(n); + if (codePoints(n) >= MIN_NAME_LENGTH && passwordText.includes(n)) return true; + return distinctiveNameWords(name).some((w) => passwordText.includes(w)); }); if (hasName) problems.push('HAS_INSTITUTE_NAME'); return problems; From 7016eff74fe0f3cd2e2df3288bc370d1a143db3d Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:03:27 +0600 Subject: [PATCH 02/44] Sprint 1 P1-J plan (docs/plans/sprint-1-p1j-password-hash.md): the app login loses SELECT on users.password_hash, the login lookup returns only the hash's parameters and salt and the database compares, hasPassword comes from a function for the current user, and every Prisma client omits the hash. Written during the unattended day run of 2026-11-16 for the owner's review together with the PR Co-Authored-By: Claude Opus 5.5 --- docs/plans/sprint-1-p1j-password-hash.md | 262 +++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 docs/plans/sprint-1-p1j-password-hash.md diff --git a/docs/plans/sprint-1-p1j-password-hash.md b/docs/plans/sprint-1-p1j-password-hash.md new file mode 100644 index 0000000..d8b3efb --- /dev/null +++ b/docs/plans/sprint-1-p1j-password-hash.md @@ -0,0 +1,262 @@ +# Sprint 1, P1-J: the app login can no longer read password hashes (implementation plan) + +**Status: written and built during the unattended day run of 2026-11-16, for the owner's review +together with the PR** (the owner asked for this: "write the plan, then build it, since I am +away; I will review plan and PR together before merging"). Nothing is merged by Claude. The +follow-up is P1-J in [decisions-pending.md](../decisions-pending.md); the phase is +[sprint-1-p1-staff-password.md](sprint-1-p1-staff-password.md). + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans (one implementer, +> one database-security review subagent at the end). Steps use checkbox (`- [ ]`) syntax. + +**Goal:** an SQL injection in any institute request (which runs as `jantrik_app`) can no longer +read a staff member's argon2 password hash, neither of co-members nor of anyone else. Everything +the app needs keeps working: password login, `GET /me/password` (`hasPassword`), setting a +password, and every read of `users`. + +**Architecture:** `jantrik_app` loses SELECT on `users.password_hash` (it keeps UPDATE, so setting +a password still works). The login lookup stops returning the hash: it returns only the hash's +parameters and salt, the API computes the argon2 hash of the typed password with them, and a +narrow definer function compares the two inside the database and answers yes or no. The hash's +digest never leaves the database. `hasPassword` comes from a second narrow definer function. +Every Prisma client omits `passwordHash` from its reads, so no read or update ever names the +column. + +**Tech stack:** PostgreSQL 16 column privileges and `SECURITY DEFINER` functions (built-in +`sha256()`), Prisma 7 global `omit`, `@node-rs/argon2` (as today). No new dependency. + +## What exists today + +- `users` is granted to `jantrik_app` as `GRANT SELECT, INSERT, UPDATE, DELETE` (init migration), + narrowed later: no INSERT/DELETE, UPDATE only on six columns (P1-B). **SELECT is table-level, + so a column REVOKE alone would do nothing.** +- RLS (`users_visible`): the app sees itself and the members of the current institute. A request + that is injected into can read their `password_hash` (P1-J as recorded). +- **A wider hole than P1-J names:** `auth_find_user_for_login(phone, email)` is a definer function + executable by `jantrik_app`, and it returns `password_hash` of **any** user by phone or email, + whatever the institute. Phones of co-members are readable, and phones are guessable. Hiding the + column without changing this function would close nothing. This plan changes both. +- The API reads the hash in two places: the password login (`AuthService.loginWithPassword` → + `PasswordService.verify`) and `GET /me/password` (`user.passwordHash !== null`). +- Full-row reads or updates of `users` by the app login (each would fail once SELECT on the + column is gone, because Prisma names every column, also in `RETURNING`): + - `AuthService` (`me`: `findUniqueOrThrow` without `select`), `MeModule` (`update` without + `select`), `PasswordSettingsService.set` (`update`); + - the demo seed (`demo.ts`: the staff password and Bangla names are set as each user, through + the app login), the API test harness (`addMember` with a password); + - tests: `users-rls`, `invitations-rls`, `me`, `name-bn`, `no-global-names`, `password`, + `student-imports`. +- The platform admins' login (`platform_find_admin_for_login`) returns `platform_admins` + hashes to `jantrik_platform_app`, a separate login with no tenant traffic. **Out of scope** + (recorded in "Not in this plan"). + +## Design + +### The database (one migration, `20261116000000_users_password_hash_hidden`) + +```sql +-- 1. Column privileges: everything but password_hash (a future column needs its own GRANT). +REVOKE SELECT ON users FROM jantrik_app; +GRANT SELECT (id, phone, email, name, name_bn, password_changed_at, locale, color_scheme, + created_at, updated_at) ON users TO jantrik_app; + +-- 2. The login lookup returns the hash's parameters and salt, never its digest. +DROP FUNCTION auth_find_user_for_login(text, text); +CREATE FUNCTION auth_find_user_for_login(p_phone text, p_email text) + RETURNS TABLE (id uuid, name text, locale locale, password_params text) + ... SECURITY DEFINER SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT u.id, u.name, u.locale, + substring(u.password_hash FROM + '^(\$argon2id\$v=19\$m=[0-9]{1,10},t=[0-9]{1,10},p=[0-9]{1,3}\$[A-Za-z0-9+/]{11,64})\$[A-Za-z0-9+/]{43}$') + FROM users u + WHERE (p_phone IS NOT NULL AND u.phone = p_phone) + OR (p_email IS NOT NULL AND lower(u.email) = lower(p_email)) + LIMIT 1 + $$; + +-- 3. Does the current user's hash equal the one the API computed? (sha256 of both PHC strings) +CREATE FUNCTION auth_my_password_matches(p_digest bytea) RETURNS boolean + ... SECURITY DEFINER SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT EXISTS ( + SELECT 1 FROM users u + WHERE u.id = app_current_user_id() + AND u.password_hash IS NOT NULL + AND sha256(convert_to(u.password_hash, 'UTF8')) = p_digest) + $$; + +-- 4. Has the current user set a password? (GET /me/password) +CREATE FUNCTION auth_my_password_is_set() RETURNS boolean + ... SECURITY DEFINER SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT EXISTS (SELECT 1 FROM users u + WHERE u.id = app_current_user_id() AND u.password_hash IS NOT NULL) + $$; +``` + +Each function: `REVOKE ALL … FROM PUBLIC`, `GRANT EXECUTE … TO jantrik_app`, then +`ALTER FUNCTION … OWNER TO jantrik_auth` (privileges before the owner change, database.md). +`jantrik_auth` already has SELECT on `users` and an `auth_lookup` policy. + +- The pattern accepts only what `@node-rs/argon2` writes today (argon2id, version 19, a 32-byte + digest). Any other stored value returns NULL: that person cannot sign in with a password, as + with a corrupt hash today, and can set a new one after a phone code. +- The two new functions take no id: they are scoped by `app_current_user_id()`, like + `auth_list_my_memberships()`, so they fit the existing schema-safety rules (no uuid parameter, + scoped by context) without a new exception. + +### The password login (API) + +`AuthService.loginWithPassword`: + +1. `auth_find_user_for_login` → `{ id, name, locale, password_params }` (as today, but no hash). +2. `PasswordService.loginDigest(params, password)`: parse `params` (argon2id, v=19, `m`, `t`, `p`, + salt); compute `hash(nfc(password), { memoryCost: m, timeCost: t, parallelism: p, salt })`; + check it starts with `params + '$'`; return `sha256` of the whole PHC string. When the user is + unknown, has no password, or the parameters are missing, malformed or above the cost ceiling + (`m` ≤ 65 536 KiB, `t` ≤ 10, `p` ≤ 4), it computes the same hash with the default parameters + and a fixed dummy salt, so the time does not reveal which case it was. +3. `auth_my_password_matches(digest)` in a transaction with `app.user_id` = the user's id, or the + nil UUID when there is no user (the same number of database round trips either way). +4. Everything after (staff check, limiter reset, session) is unchanged. + +`PasswordService.verify` stays for the platform admins' login. + +### `hasPassword` and the reads of `users` + +- `PasswordSettingsService.status` reads `phone` and `passwordChangedAt` as today, and + `hasPassword` from `SELECT auth_my_password_is_set()` in the request's transaction. +- **Every Prisma client omits `passwordHash`** (`createPrismaClient` passes + `omit: { user: { passwordHash: true } }`). The package's `PrismaClient` type becomes that + client's type and the generated class is no longer exported, so every client is built by the + factory and TypeScript refuses code that reads `user.passwordHash`. A query that really needs + it (the owner login in tests) asks with `omit: { passwordHash: false }`. +- Writes are unchanged: `PasswordSettingsService` still writes the hash (UPDATE privilege kept); + Prisma's `RETURNING` no longer names the column. + +### Guarding it + +- `schema-safety.test.ts`: + - `jantrik_app` has no table-level SELECT on `users`, and exactly these selectable columns + (pinned list: a new column needs a deliberate GRANT and a test change); + - no login role (`jantrik_app`, `jantrik_platform_app`, `jantrik_ingest_app`) and not PUBLIC + may SELECT `password_hash`; + - no definer function executable by `jantrik_app` returns a column named `password_hash` + (`pg_proc.proargnames` of the result columns), so the hole cannot come back through a new + function. +- The two new functions join the "scoped by context" list. + +## Review focus + +1. **The digest never reaches `jantrik_app`:** not through `users`, not through any function, not + in an error message. +2. **No timing difference** between an unknown phone, a user without a password and a wrong + password (one argon2 hash and one transaction each). +3. **The oracle that remains:** `auth_my_password_matches` answers yes/no for a digest. An + injection could ask it for guesses after computing argon2 for each one itself (the cost of an + offline attack, but online, one query per guess, and only while the hole is open). That is + strictly less than reading the hash (P1-J1). +4. **Nothing else broke:** the seed (demo passwords and Bangla names), the API harness, every + `users` read. + +## Decisions taken in this plan (the owner reviews them with the PR) + +| # | Decision | Taken (safest) | +| ----- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| P1-J1 | The login lookup returned any user's hash | Closed too: it returns parameters and salt only; the database compares (otherwise hiding the column achieves nothing) | +| P1-J2 | How `hasPassword` is read | A definer function for the current user only (`auth_my_password_is_set()`), no parameter | +| P1-J3 | Full-row reads of `users` | Every Prisma client omits `passwordHash` (typed), instead of a `select` on each call site; the column is unreadable either way | +| P1-J4 | Argon2 cost ceiling at login (`m` ≤ 64 MiB, `t` ≤ 10, `p` ≤ 4) | Above it the stored hash is treated as unusable; today's are 19 MiB / 2 / 1. It stops a hash someone wrote into their own row from making each login attempt arbitrarily expensive | +| P1-J5 | Hashes in another format (not argon2id v19, 32 bytes) | Cannot sign in with a password until the person sets one again after a phone code; every hash Jantrik writes has this format | +| P1-J6 | Platform admins' hashes (`platform_find_admin_for_login`) | Not in this PR: a separate login with no tenant requests; the same change can follow if wanted | + +## Files + +| File | What | +| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| `packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql` | grants and the three functions | +| `packages/db/src/client.ts` (new), `src/index.ts`, `src/tenancy/context.ts` and others | the factory with `omit`, the `PrismaClient` and `TransactionClient` types | +| `packages/db/test/users-password-hash.test.ts` (new) | the column, the functions, the timing-neutral paths | +| `packages/db/test/schema-safety.test.ts`, `auth-functions.test.ts`, `users-rls.test.ts` | guards; reads through the owner where a test needs the hash | +| `apps/api/src/auth/login-lookup.ts`, `auth.service.ts`, `password.service.ts` | the login | +| `apps/api/src/auth/password-settings.service.ts` | `hasPassword` | +| `apps/api/src/auth/password.service.spec.ts` (new) | parsing the parameters, the ceiling, the dummy path | +| `apps/api/test/*.e2e-spec.ts`, `test/support/harness.ts` | tests that read the hash use the owner login | +| `docs/database.md`, `docs/auth.md`, `docs/decisions-pending.md` | docs | + +## Tasks + +### Task 1: The column and the functions (database) + +- [ ] Test first (`packages/db/test/users-password-hash.test.ts`), as the app login: + - `SELECT password_hash FROM users` (self, in context) fails with "permission denied"; + - `SELECT * FROM users` fails the same way; `SELECT id, phone, name … FROM users` works; + - `auth_find_user_for_login` returns `password_params` equal to the stored hash up to its last + `$`, and NULL for a user without a password or with a malformed hash; + - `auth_my_password_matches(sha256(stored))` is true in the user's context, false in another + user's context, false without context, false for a user without a password; + - `auth_my_password_is_set()` true/false/false-without-context; + - updating the own `password_hash` still works (and the owner, in the user's context, reads it). +- [ ] Run → fails (column readable, functions missing). +- [ ] Migration; then the test passes. +- [ ] `schema-safety.test.ts` and `auth-functions.test.ts` updated (column pins, the function + lists); `users-rls.test.ts` reads the written hash through the owner. +- [ ] Commit. + +### Task 2: Every client omits the hash (packages/db) + +- [ ] `createPrismaClient` with `CLIENT_OMIT`; the `PrismaClient` and `TransactionClient` types; + the generated class no longer exported; the test helper's single-connection client through the + factory (`max` pool option). +- [ ] Test: as the app login, `tx.user.findUnique({ where: { id } })` and `tx.user.update(…)` + work (fail before: permission denied); the owner reads the hash with `omit: { passwordHash: +false }`. +- [ ] Typecheck the workspace; fix the call sites TypeScript reports. Commit. + +### Task 3: The password login (API) + +- [ ] Unit test `password.service.spec.ts`: `loginDigest` equals `sha256(hash)` for a real + `hash()` output; a wrong password gives another digest; malformed, other algorithm, other + version, over-the-ceiling parameters and `null` all give the dummy path (and still hash once). +- [ ] API e2e: password login still works (existing `password-set`/`password` specs); add a + spec that the login's database calls never return a digest (the response of + `auth_find_user_for_login` for a staff user has no 43-character tail). +- [ ] Code: `findUserForLogin` returns `password_params`; `passwordMatches(prisma, userId, digest)` + in `login-lookup.ts`; `AuthService.loginWithPassword` uses both. Commit. + +### Task 4: `hasPassword` (API) + +- [ ] The existing `GET /me/password` tests (before and after setting a password) are the failing + tests once the column is hidden; change `status()` to `auth_my_password_is_set()`. Commit. + +### Task 5: Seed, harness and tests + +- [ ] The demo seed's per-user update (as the app login) works with the omit (checked by + `demo-devices.test.ts`, which runs the seed's code against the test database, and in CI by the + Playwright seed). +- [ ] API tests that read `passwordHash` read it through the owner login. Commit. + +### Task 6: Docs + +- [ ] database.md (users: SELECT by column, the new functions, "a new `users` column needs a + GRANT SELECT"), auth.md (how a password is checked), decisions-pending (P1-J built, P1-J1…). + +### Task 7: Gates, review, PR + +- [ ] lint, typecheck, format:check, tests package by package, build (Playwright in CI). +- [ ] Review subagent (database security). PR. CI green. Not merged. + +## Risks + +- **Merging with P2** (institute profile, files): P2 also adds migrations and touches + `schema-safety.test.ts` and `database.md`. This PR's migration is dated first; merge it first. +- **A missed full-row read** would fail with "permission denied" rather than leak: the omit and + the typed client make that unlikely, and the API suite covers every `users` read. +- **Existing local hashes** keep working (same format). Nothing to migrate. + +## Not in this plan + +- The platform admins' hashes (P1-J6). +- Rate-limiting the remaining yes/no oracle inside the database (P1-J1): the API's login limits + already apply to the real login path. From 25da8a3771c56f23d3e6bad27a1362f33223e554 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:03:45 +0600 Subject: [PATCH 03/44] Sprint 1 P2 plan (docs/plans/sprint-1-p2-files.md): institute profile, file storage in Postgres behind FileStore, student photos; written and built during the unattended day run of 2026-11-16, for the owner's review with the PR (decisions F1-F12) Co-Authored-By: Claude Opus 5.5 --- docs/plans/sprint-1-p2-files.md | 374 ++++++++++++++++++++++++++++++++ 1 file changed, 374 insertions(+) create mode 100644 docs/plans/sprint-1-p2-files.md diff --git a/docs/plans/sprint-1-p2-files.md b/docs/plans/sprint-1-p2-files.md new file mode 100644 index 0000000..4ab869f --- /dev/null +++ b/docs/plans/sprint-1-p2-files.md @@ -0,0 +1,374 @@ +# Sprint 1, P2: institute profile, file storage, student photos (implementation plan) + +**Status: written and built during the unattended day run of 2026-11-16, for the owner's review +together with the PR.** The owner asked for this phase to be planned and built while away; the PR +is the approval step (nothing reaches `main` until the owner merges it). The sprint plan is +[sprint-1.md](sprint-1.md) → P2, with decisions S7 (Postgres storage behind `FileStore`, +server-side resize and compression, caps per file and per institute) and S8 (`sharp`). New +decisions taken during the run are F1–F12 below; each is the safe default and is listed in +`docs/decisions-pending.md` → "Sprint 1, P2". + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans (one implementer, +> one review subagent at the end of the phase). Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** an institute keeps its own profile (names, EIIN, contact, head of institute, logo, +head's signature, seal), and staff can add a student's photo. Files are stored safely: re-encoded +on the server, small, capped per file and per institute, and isolated by RLS like every other +tenant row. + +**Architecture:** + +- Files live in Postgres (`stored_files.bytes`, `bytea`) under forced RLS. Only one class touches + that table: `PostgresFileStore`, behind the `FileStore` interface (`put`, `get`, `meta`, + `delete`). A code-scan test fails the build if anything else does. A later move to R2/S3 is a + new `FileStore` backend plus a copy job; no caller changes. +- Uploads are multipart (`file`, ≤ 5 MB). `ImageService` (sharp) decodes the upload, refuses + anything that is not a JPEG, PNG or WebP image or that has more than 50 megapixels, applies the + EXIF orientation, resizes, and re-encodes. Only the re-encoded bytes are stored; metadata (EXIF, + GPS, ICC, comments) is never copied. +- The per-institute total lives in `stored_file_usage` (one row per institute), changed in the + same transaction as every `put` and `delete`, under a per-institute advisory lock. +- Files are served only through entity routes, never `/files/:id`: a student's photo, a guardian's + own child's photo, and the institute's logo, signature and seal. Each answers with a strong + `ETag` (the SHA-256) and `Cache-Control: private, no-cache`; `If-None-Match` gets 304. +- The web fetches an image with the bearer token (`AuthClient.download`) and shows it through an + object URL, cached per path and file id. No signed URLs, so there is no new auth mechanism. + +**Tech stack:** NestJS (multer through `@nestjs/platform-express`, already used by the device +import), `sharp` 0.35.5 (already in the lockfile through Next.js; now a direct API dependency, +S8), Prisma/PostgreSQL 16, Next.js (v3 kit), next-intl, Vitest, Playwright. + +**Branch:** `feature/sprint-1-p2-files`, from `main` at `7de4f5a`. P1-J +(`feature/sprint-1-p1j-password-hash`) adds migration `20261116000000_*` and should merge first; +this branch's migrations are `20261116100000_*` and later, so the order holds either way. + +## Global constraints + +- **Tables:** the database.md checklist for every new table (ticked below), composite foreign keys + to tenant tables (optional ones too), every new foreign key `ON UPDATE RESTRICT`, an index + leading with `tenant_id`, enabled and forced RLS with `tenant_isolation`, explicit grants. +- **No backfill:** existing institutes have no profile and no usage row; both are created on first + use (the profile on the first save or image upload, the usage row on the first `put`). +- **Caps (S7), in code and by CHECK:** + + | Kind | Output | Max size | Max box | + | ----------------- | ---------------------------------------- | -------- | --------- | + | `STUDENT_PHOTO` | JPEG | 200 KB | 600 × 800 | + | `APPLICANT_PHOTO` | JPEG (P3 uses it) | 200 KB | 600 × 800 | + | `LOGO` | PNG, or WebP when the PNG does not fit | 100 KB | 512 × 512 | + | `SEAL` | PNG, or WebP when the PNG does not fit | 100 KB | 512 × 512 | + | `SIGNATURE` | PNG | 100 KB | 600 × 240 | + | `DOCUMENT_ASSET` | JPEG, PNG or WebP (P8 uses it; no route) | 256 KB | — | + + Per institute: `FILE_STORAGE_PER_TENANT_MB` (default 1024). Over it: 413 `STORAGE_FULL`. + +- **Inputs:** at most 5 MB (multer `fileSize`, one file, no other fields); at most 50 megapixels + (`limitInputPixels`); JPEG, PNG or WebP by content (the declared type and file name are ignored); + only the first frame of an animated image is used. +- **Transactions:** the image work runs before the file is stored, in the request; it takes + ~0.1–0.5 s, well inside the 15 s request transaction. At most two images are processed at once + per API process (a small in-process limiter), so a burst of uploads cannot exhaust memory. +- **Audit:** every profile change (field values), every image set or removed (`{kind, fileId}` + only, never bytes) and every student photo change (`photoFileId` old/new). +- **Strings:** bn and en through translation keys. Bangla digits are accepted in EIIN, phone and + year (`toAsciiDigits`). The v3 kit, light-first; screenshots bn at 1366 and 390 px. +- **Secrets:** none new. `FILE_STORAGE_PER_TENANT_MB` is a setting, not a secret. + +## Review focus + +1. **Another institute's file.** A UUID from institute A used in B: every route answers 404, RLS + hides the row, and a composite foreign key refuses to point B's student or profile at A's + file. Test: Task 1 (database), Task 5 (routes). +2. **A hostile image.** A 50 000 × 50 000 PNG of a few KB (decompression bomb), a text file named + `.jpg`, a truncated JPEG, a GIF, a 6 MB upload. Expected: 413 for the size, 422 for the rest, + nothing stored, the usage unchanged. Test: Tasks 3 and 5. +3. **Location leaks.** A phone photo with EXIF GPS: the stored JPEG has no EXIF at all (and the + orientation is applied first, so the photo is not sideways). Test: Task 3. +4. **The per-institute cap under concurrency.** Two uploads at once when only one fits: exactly + one is stored, the other gets 413 `STORAGE_FULL`, and the usage equals the sum of the stored + files. Test: Task 4. +5. **A guardian reaching another child's photo.** `GET /me/children/:id/photo` answers 404 for any + student not linked to the caller; staff routes answer 403 for guardians. Test: Task 5. + +## Decisions taken during the run (F1–F12, the owner reviews them with the PR) + +- **F1. Who sees what.** Student photo: the roles that may read students (`OWNER`, `ADMIN`, + `TEACHER`), for every student, like name and code (a teacher sees basics of every student). + Guardians: their own children only. Logo: every member of the institute (guardians too). + Head's signature and seal: `OWNER` and `ADMIN` only (they can be misused on forged papers; + printing roles widen in P8/P9). Profile fields: `OWNER` and `ADMIN` (the settings page). +- **F2. Lists keep initials.** The student list, the board and the other lists do not load photos + (50 photos of up to 200 KB each would break the 3 s budget on slow 4G). Photos show on the + student's page, the guardian's child card and the report card. A small thumbnail kind for lists + is a follow-up (backlog). +- **F3. `photoId` replaces `photoUrl`** in every API type (student list, profile, guardian + children, report cards, admit cards): the stored file's id, or null. It doubles as the cache + key, so a replaced photo is fetched again. +- **F4. EIIN is exactly 6 digits** (BANBEIS EIIN), optional. Widening it later is one CHECK. +- **F5. The institute's phone** may be a mobile or a landline: stored as 5–15 ASCII digits with an + optional leading `+` (a Bangladeshi mobile is stored as E.164). +- **F6. At least one name** (Bangla or English) is required in a saved profile. An image uploaded + before the first save creates the profile with the institute's registered name (`tenants.name`) + in the matching script. +- **F7. Formats.** HEIC/HEIF is refused (iPhones send JPEG to browsers for `image/*` inputs; the + prebuilt sharp has no HEVC decoder). Transparent PNG photos are flattened on white. +- **F8. Upload limit:** 60 uploads per person per 10 minutes (`file-upload:`), on top of + the general request limits, because each upload costs CPU. +- **F9. Deactivated students:** their photo can still be viewed by OWNER/ADMIN, but not changed + (409 `DEACTIVATED`, as other student writes). +- **F10. Replacing a file deletes the old one** in the same transaction (no orphans, no history of + images). The audit row keeps the old and new file ids. +- **F11. The usage row is counted, not recomputed:** `bytes_used` and `file_count` move with every + `put`/`delete` under the institute's advisory lock; a test checks they equal the sums of the + rows. +- **F12. No report-card logo or institute header in P2.** The profile and its images exist for P3 + (admission slip), P8 and P9 (documents); the report card gains only the student photo, as the + sprint plan says. + +## Database (migrations `20261116100000_files_and_institute_profile`, `20261116100100_students_photo_file`) + +### `stored_file_kind` (enum) + +`STUDENT_PHOTO`, `APPLICANT_PHOTO`, `LOGO`, `SIGNATURE`, `SEAL`, `DOCUMENT_ASSET` (a new type, so +it is created with the table; no value is added to an existing enum). + +### `stored_files` (S I D, no UPDATE) + +| Column | Type | Rule | +| --------------- | ------------------ | ---------------------------------------------------------------------- | +| `id` | uuid (v7) | primary key | +| `tenant_id` | uuid | NOT NULL, FK `tenants` RESTRICT/RESTRICT | +| `kind` | `stored_file_kind` | NOT NULL | +| `mime` | text | CHECK `image/jpeg`, `image/png`, `image/webp`, and the kind/mime pairs | +| `bytes` | bytea | NOT NULL | +| `size_bytes` | integer | CHECK `= octet_length(bytes)` and ≤ the kind's cap | +| `sha256` | char(64) | CHECK `^[0-9a-f]{64}$` | +| `width` | integer | CHECK 1–4000 | +| `height` | integer | CHECK 1–4000 | +| `created_by_id` | uuid, null | FK `users` (global, cannot be composite; the uploader is the caller) | +| `created_at` | timestamptz(3) | no `updated_at`: rows never change | + +Indexes: `UNIQUE (tenant_id, id)`, `(tenant_id, kind)`. + +### `stored_file_usage` (S I U, no DELETE) + +`id`, `tenant_id` (UNIQUE), `bytes_used bigint` CHECK ≥ 0, `file_count integer` CHECK ≥ 0, +`created_at`, `updated_at`. `UNIQUE (tenant_id, id)`. + +### `institute_profiles` (S I U, no DELETE; ≤ 1 per institute) + +`id`, `tenant_id` (UNIQUE), `name_bn`, `name_en`, `short_name`, `eiin`, `address_bn`, +`address_en`, `phone`, `email`, `website`, `head_title_bn`, `head_title_en`, `head_name_bn`, +`head_name_en`, `established_year smallint`, `logo_file_id`, `head_signature_file_id`, +`seal_file_id`, `created_at`, `updated_at`. + +- CHECKs (each tests `IS NULL` first): at least one name; lengths (names 200, short name 30, + addresses 300, head titles 60, head names 100, email 254, website 200); `eiin ~ '^[0-9]{6}$'`; + `phone ~ '^\+?[0-9]{5,15}$'`; a simple e-mail shape; `website ~ '^https?://\S+$'`; + `established_year BETWEEN 1800 AND 2100`. +- The three file columns: composite FKs `(tenant_id, x) → stored_files (tenant_id, id)` ON DELETE + RESTRICT ON UPDATE RESTRICT, each UNIQUE with `tenant_id` (a file belongs to one place). + +### `students` + +- `photo_file_id uuid` null, composite FK to `stored_files` RESTRICT/RESTRICT, + `UNIQUE (tenant_id, photo_file_id)` (also the FK's index). +- `photo_url` is dropped (never written: always null). + +### RLS checklist (every new table) + +| Step | `stored_files` | `stored_file_usage` | `institute_profiles` | +| --------------------------------------------------------- | -------------- | ------------------- | -------------------- | +| `tenant_id NOT NULL`, tenant relation | ✅ | ✅ | ✅ | +| `@@unique([tenantId, id])` | ✅ | ✅ | ✅ | +| composite FKs to tenant tables (optional ones too) | — (none) | — (none) | ✅ three files | +| every FK `ON UPDATE RESTRICT` | ✅ | ✅ | ✅ | +| index leading with `tenant_id` | ✅ | ✅ (unique) | ✅ (unique) | +| ENABLE + FORCE RLS, `tenant_isolation` USING + WITH CHECK | ✅ | ✅ | ✅ | +| explicit grants, nothing more | S I D | S I U | S I U | +| CHECKs test nullable columns with `IS NULL` first | ✅ | n/a | ✅ | +| no tenant backfill in the migration | ✅ | ✅ | ✅ | +| added to `schema-safety.test.ts` | ✅ | ✅ | ✅ | +| isolation test in `packages/db/test/files-rls.test.ts` | ✅ | ✅ | ✅ | +| drift check (`prisma migrate diff` empty) | ✅ | ✅ | ✅ | + +## API + +| Route | Roles | Answer | +| ------------------------------------------ | ---------------------------- | ------------------------------------ | +| `GET /institute/profile` | OWNER, ADMIN | `InstituteProfile` | +| `PUT /institute/profile` | OWNER, ADMIN | `InstituteProfile` | +| `PUT /institute/profile/:slot` (multipart) | OWNER, ADMIN | `InstituteProfile` | +| `DELETE /institute/profile/:slot` | OWNER, ADMIN | `InstituteProfile` | +| `GET /institute/profile/logo` | every member (guardians too) | the image, 404 if none | +| `GET /institute/profile/signature`, `seal` | OWNER, ADMIN | the image, 404 if none | +| `GET /students/:id/photo` | OWNER, ADMIN, TEACHER | the image, 404 if none | +| `PUT /students/:id/photo` (multipart) | OWNER, ADMIN | `StudentProfile` | +| `DELETE /students/:id/photo` | OWNER, ADMIN | `StudentProfile` | +| `GET /me/children/:id/photo` | GUARDIAN (own children) | the image, 404 if none or not theirs | + +`:slot` is `logo`, `signature` or `seal`. All routes are `@RequireModule('CORE')`. + +Errors: 400 `FILE_REQUIRED`; 413 (multer, over 5 MB); 422 `IMAGE_INVALID` (not a supported +image, corrupt); 422 `IMAGE_TOO_BIG` (over 50 megapixels); 422 `IMAGE_CANNOT_SHRINK` (could not +reach the cap, practically never); 413 `STORAGE_FULL`; 409 `DEACTIVATED`; 429 with +`Retry-After`. + +## Files + +| File | Change | +| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| `packages/db/prisma/schema.prisma` + 2 migrations | tables, enum, students column | +| `packages/db/test/files-rls.test.ts`, `schema-safety.test.ts` | isolation, grants, CHECKs, FKs | +| `packages/shared/src/files.ts`, `files-schema.ts` (+ tests), `index.ts` | caps, types, the profile schema | +| `apps/api/src/files/*` | `FileStore`, `PostgresFileStore`, `ImageService`, the code scan, the upload decorator | +| `apps/api/src/institute/institute-profile.module.ts` | profile routes | +| `apps/api/src/students/student-photo.service.ts`, `students.module.ts` | photo routes | +| `apps/api/src/me/me.module.ts` | the guardian's child photo | +| `apps/api/src/config/env.ts` | `FILE_STORAGE_PER_TENANT_MB` | +| `photoUrl` → `photoId` in the API and shared types | F3 | +| `apps/api/test/files.e2e-spec.ts`, `institute-profile.e2e-spec.ts` | API tests | +| `apps/web/src/lib/authed-image.ts`, `components/student-photo.tsx` | object URLs | +| `apps/web/src/app/(app)/setup/profile/page.tsx`, `components/setup/setup-kit.tsx` | Settings → Institute profile | +| `apps/web/src/app/(app)/students/[id]/page.tsx`, `components/students/photo-dialog.tsx` | the photo on the student page | +| `apps/web/src/components/exams/report-card.tsx`, `dashboard/page.tsx` | the photo on the report card and child card | +| `apps/web/messages/{bn,en}.json` | strings | +| `apps/web/e2e/files.spec.ts` | Playwright | +| `docs/files.md` (new), `database.md`, `deploy.md`, `.env.example`, `decisions-pending.md` | docs | + +--- + +### Task 1: The database + +**Files:** `schema.prisma`; the two migrations (written by hand: Prisma's `--create-only` needs +a development database, and this run uses scratch databases only); `files-rls.test.ts`; +`schema-safety.test.ts`. + +- [ ] **Step 1: Write the failing tests** (`files-rls.test.ts`): + - another institute cannot read, delete, or insert a `stored_files` row with A's `tenant_id`; + nobody may UPDATE a file (permission denied); + - the CHECKs: an unknown mime, a GIF, a 210 KB photo, a 110 KB logo, a PNG photo, a JPEG + signature, `size_bytes` ≠ `octet_length(bytes)`, a bad sha256, width 0 → refused; a 200 KB + photo and a 256 KB document asset → accepted; + - `stored_file_usage`: isolation, no DELETE, `bytes_used` ≥ 0; + - `institute_profiles`: isolation, one per institute, no DELETE, the CHECKs (no name, 5-digit + EIIN, `abc` phone, `x@` e-mail, `ftp://` website, year 1700), pointing the logo at another + institute's file → refused (composite FK), deleting a file a profile uses → refused; + - `students.photo_file_id`: another institute's file → refused; two students cannot share one + file; `photo_url` is gone; + - `schema-safety.test.ts`: the three tables in the tenant table list. +- [ ] **Step 2: Run them and see them fail** (`pnpm --filter @jantrik/db exec vitest run +test/files-rls.test.ts` on the scratch database). +- [ ] **Step 3: Schema and migrations** as in "Database" above; RLS, grants and CHECKs in the + same migration file. Regenerate the client; the test setup applies the migrations. +- [ ] **Step 4: Run them and see them pass;** drift check against the scratch database. +- [ ] **Step 5: Commit.** + +### Task 2: Shared caps, types and the profile schema + +**Files:** `packages/shared/src/files.ts` (no zod: the web imports it), `files-schema.ts`, tests. + +- Produces: `STORED_FILE_KINDS`, `FILE_LIMITS` (per kind: `maxBytes`, `box`, `mimes`), + `UPLOAD_MAX_BYTES = 5 * 1024 * 1024`, `UPLOAD_MAX_PIXELS = 50_000_000`, `INSTITUTE_IMAGE_SLOTS`, + types `FileRef` and `InstituteProfile`, `instituteProfileSchema` (trims; empty → null; + `toAsciiDigits` for EIIN, phone, year; a BD mobile normalised to E.164; at least one name). +- Tests: Bangla digits in EIIN/phone/year; landline and mobile phones; every CHECK of Task 1 has + a matching schema refusal; caps equal the CHECK values. +- Commit. + +### Task 3: Image processing (`ImageService`) + +**Files:** `apps/api/src/files/image.service.ts`, `image.service.spec.ts`, `apps/api/package.json` +(`sharp` 0.35.5). + +- Produces: `ImageService.process(kind, input: Buffer) → { bytes, mime, width, height }`. + - `sharp(input, { limitInputPixels: UPLOAD_MAX_PIXELS, failOn: 'error' })`, metadata first: + format must be `jpeg`, `png` or `webp`, else `IMAGE_INVALID`; over the pixel limit → + `IMAGE_TOO_BIG`. + - `.rotate()` (EXIF orientation), `.resize(box, { fit: 'inside', withoutEnlargement: true })`. + - Photos: flatten on white, JPEG (mozjpeg) at quality 85 → 75 → 65 → 55 → 45, then 80 % + smaller dimensions, until under 200 KB. Logo and seal: palette PNG, else WebP 90 → 50, then + smaller. Signature: palette PNG with 256 → 64 → 16 colours, then smaller. + - Metadata is never kept (no `withMetadata`/`keepMetadata`). + - At most two `process` calls run at once per process. +- Tests (images made with sharp in the test): JPEG/PNG/WebP in → JPEG ≤ 200 KB and ≤ 600 × 800; + a 4000 × 3000 noisy photo fits; EXIF GPS and orientation 6 → no EXIF, rotated size; a + transparent PNG logo keeps its alpha; a signature is PNG; a text file, a GIF, a truncated JPEG → + `IMAGE_INVALID`; a crafted 50 000 × 50 000 PNG header → `IMAGE_TOO_BIG` without decoding. +- Commit. + +### Task 4: `FileStore` and the per-institute cap + +**Files:** `apps/api/src/files/file-store.ts` (interface + token), `postgres-file-store.ts`, +`files.module.ts`, `file-store-access.spec.ts` (code scan), `config/env.ts`. + +- `put({kind, mime, bytes, width, height})`: checks the kind's cap and mime (a programming error + if it fails: 500), takes `pg_advisory_xact_lock(hashtextextended('stored-files:' || +app_current_tenant_id()::text, 0))`, upserts the usage row, refuses with 413 `STORAGE_FULL` + when `bytes_used + size > cap`, inserts the file (sha256 computed here), adds to the usage. +- `get(id)`, `meta(id)` (no bytes), `delete(id)` (lock, delete, subtract). +- Code scan: in `apps/api/src`, only `files/postgres-file-store.ts` mentions `storedFile`, + `storedFileUsage`, `stored_files` or `stored_file_usage`. +- Tests (in `files.e2e-spec.ts`): usage equals the sums after puts, a replace and a delete; a + preset usage near the cap → 413; review focus 4 (two parallel uploads, one fits). +- Commit. + +### Task 5: The routes + +**Files:** `apps/api/src/files/upload.ts` (`ImageUpload()` decorator: `FileInterceptor('file', +{ limits: { fileSize: 5 MB, files: 1, fields: 0 } })`), `files/serve.ts` (headers, 304), +`institute/institute-profile.module.ts`, `students/student-photo.service.ts`, +`students/students.module.ts`, `me/me.module.ts`, `app.module.ts`; `photoUrl` → `photoId` in the +services and shared types (F3). + +- Tests (`files.e2e-spec.ts`, `institute-profile.e2e-spec.ts`): + - admin uploads a photo → profile with `photoId`; `GET` → 200 `image/jpeg`, `ETag`, + `Cache-Control: private, no-cache`; `If-None-Match` → 304; teacher → 200; accountant → 403; + guardian → 403; + - another institute's admin → 404 (`GET`, `PUT`, `DELETE`); + - the guardian of that child → 200 at `/me/children/:id/photo`; another guardian → 404; + - replace → the old file is gone and the usage is the new size; `DELETE` → 404 afterwards; + - 6 MB → 413; a text file → 422 `IMAGE_INVALID`; a bomb → 422 `IMAGE_TOO_BIG`; nothing stored + and the usage unchanged after each; + - a deactivated student → 409 `DEACTIVATED`; + - audit rows (student `photoFileId`; institute profile values; image `{kind, fileId}`); + - the profile: default from `tenants.name`; `PUT` validation (400 for bad EIIN); teacher → 403; + logo `GET` as guardian → 200; signature and seal as teacher → 403; an image before the first + save creates the profile (F6); another institute → 404; + - the upload limit (F8): the 61st upload in 10 minutes → 429. +- Commit (routes), then commit (types). + +### Task 6: The web + +- `lib/authed-image.ts`: `useAuthedImage(path, version)`: `client.download(path)` → object URL, + cached by `path#version` (up to 100, revoked on eviction); null while loading or on 404. +- `StudentPhoto` / `StudentAvatar`: `PersonAvatar` with the object URL; initials meanwhile. +- **Settings → Institute profile** (`/setup/profile`, tab "Institute profile", OWNER/ADMIN): the + form (names, short name, EIIN, addresses, phone, e-mail, website, head's title and name, + established year) and an "Images" card with logo, head's signature and seal: preview, upload or + replace, remove, the size and format hint. Errors by code. +- **Student page:** the avatar shows the photo; OWNER/ADMIN get "Photo" (upload/replace, remove) + in a dialog with a local preview, a client-side 5 MB check and the hint. +- **Report card:** the photo through the hook. **Guardian dashboard:** the child card's avatar. +- Strings bn/en; route messages unchanged (`setup` and `profile` namespaces already sent). +- Playwright (`e2e/files.spec.ts`, CI): the owner fills the profile and uploads a logo (preview + appears); the admin uploads a student photo and sees it on the student page. +- Commit. + +### Task 7: Docs and gates + +- `docs/files.md` (storage, caps, routes, how to move to a bucket, backups), `database.md` + (the tables and the `FileStore` rule), `deploy.md` (backup growth, `FILE_STORAGE_PER_TENANT_MB`), + `.env.example`, `decisions-pending.md` (F1–F12). +- Gates: lint, typecheck, format, tests package by package, build, size budget; Playwright in CI. +- Review subagent (database, uploads), fixes, PR. + +## Risks + +- **Backups grow** (about 100 MB per 2 000 photos). `pg_dump` custom format does not compress + JPEG further. If the backup window suffers, `FileStore` moves to a bucket (S7). +- **sharp is native code.** The Docker image is Alpine (musl): the lockfile already holds + `@img/sharp-linuxmusl-x64`, which `pnpm install` picks there; CI uses linux-x64. A missing + binary fails at start-up (the module is imported), never silently. +- **A hand-written migration** (no development database in this run): the drift check against + the scratch database covers it. From 995e61e56e81c13c9da87aecf45a3105d63da4fc Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:07:15 +0600 Subject: [PATCH 04/44] Test users get phone numbers no other test user of the same database has, in this run or an earlier one (decisions-pending P0-8, the appearance flake). Random numbers repeated now and then (a full run makes thousands of users and the test database keeps them all), and a repeated phone joined an existing user, who then had two memberships (a new owner got 403 on /me/context). Now each database has one counter in a file under the OS temp folder, shared by every test process and run; a process takes 200 numbers at a time under a lock, and the counter never falls behind the clock, so a lost file does not restart at old numbers. The API tests draw from +88013 and the db package's from +88014, 50 000 000 upward: the old random phones used 017/018 and the seeds' fixed numbers sit lower Co-Authored-By: Claude Opus 5.5 --- apps/api/test/support/harness.ts | 9 ++- apps/api/test/support/test-phones.ts | 104 +++++++++++++++++++++++++++ packages/db/test/helpers.ts | 9 ++- packages/db/test/test-phones.test.ts | 77 ++++++++++++++++++++ packages/db/test/test-phones.ts | 104 +++++++++++++++++++++++++++ 5 files changed, 299 insertions(+), 4 deletions(-) create mode 100644 apps/api/test/support/test-phones.ts create mode 100644 packages/db/test/test-phones.test.ts create mode 100644 packages/db/test/test-phones.ts diff --git a/apps/api/test/support/harness.ts b/apps/api/test/support/harness.ts index 03c0d48..8d39e1a 100644 --- a/apps/api/test/support/harness.ts +++ b/apps/api/test/support/harness.ts @@ -33,6 +33,7 @@ import { SMS_PROVIDER, type MemorySmsProvider } from '../../src/sms/sms.provider import { TenantAccessService } from '../../src/tenancy/tenant-access.service.js'; import { Clock } from '../../src/common/clock.js'; import { TestController } from './test.controller.js'; +import { phoneSource } from './test-phones.js'; export interface Harness { app: INestApplication; @@ -76,8 +77,14 @@ export async function createHarness(opts: { clock?: Clock } = {}): Promise string) | undefined; +/** + * A valid Bangladeshi mobile number (E.164) that no other test user of this database has, in this + * run or an earlier one (`test-phones.ts`; the db package's tests draw from +88014, these from + * +88013). + */ export const randomPhone = (): string => - `+88018${String(Math.floor(Math.random() * 1e8)).padStart(8, '0')}`; + (phones ??= phoneSource('+88013', process.env['DATABASE_URL']!))(); /** * A distinct client IP per call (sent as X-Forwarded-For) so per-IP limits don't collide. Fully * random: test files run in parallel workers and share Redis, so a per-worker counter repeats. diff --git a/apps/api/test/support/test-phones.ts b/apps/api/test/support/test-phones.ts new file mode 100644 index 0000000..f03c431 --- /dev/null +++ b/apps/api/test/support/test-phones.ts @@ -0,0 +1,104 @@ +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; + +/** + * Phone numbers for test users that no other test user of the same database has (decisions-pending + * P0-8). Random numbers repeated now and then: a full run makes thousands of users, the test + * database keeps every run's users, and a repeated phone joins an existing user, which then has + * two memberships (a new owner got 403 on /me/context once). + * + * Each database has one counter, in a file under the OS temp folder, shared by every test process + * and every run against it. A process takes a block of numbers under a lock, then hands them out + * one by one. The counter never goes back behind the clock (`floorAt`), so a lost counter file + * does not restart at numbers earlier runs gave out. The numbers sit where nothing else is: + * `` + 50 000 000–98 999 999 (the seeds' fixed numbers are below; the old random phones + * used other operators). + * + * Kept identical in packages/db/test/test-phones.ts and apps/api/test/support/test-phones.ts (a + * test of the db copy pins how it behaves). + */ + +/** Numbers per block a process takes at once. */ +const BLOCK = 200; +const LOW = 50_000_000; +const SPAN = 49_000_000; +/** The counter's floor grows 20 a second from this day, so it is always ahead of older runs. */ +const EPOCH_MS = Date.UTC(2026, 10, 1); +const PER_SECOND = 20; + +export const floorAt = (nowMs: number): number => + Math.max(0, Math.floor(((nowMs - EPOCH_MS) / 1000) * PER_SECOND)); + +const pause = (ms: number): void => { + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); +}; + +/** Runs `fn` while holding a lock directory; a lock older than 10 s is left over and taken. */ +function withLock(lockDir: string, fn: () => T): T { + for (let tries = 0; ; tries++) { + try { + fs.mkdirSync(lockDir); + break; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; + try { + if (Date.now() - fs.statSync(lockDir).mtimeMs > 10_000) { + fs.rmSync(lockDir, { recursive: true, force: true }); + continue; + } + } catch { + continue; // released meanwhile + } + if (tries > 3_000) throw new Error(`test-phones: lock ${lockDir} stays taken`); + pause(10); + } + } + try { + return fn(); + } finally { + fs.rmSync(lockDir, { recursive: true, force: true }); + } +} + +/** + * A source of phones `NNNNNNNN` (prefix e.g. `+88013`) unique among all users of the + * database `databaseUrl` names (server, port and name; never the login). + */ +export function phoneSource( + prefix: string, + databaseUrl: string, + options: { dir?: string; now?: () => number } = {}, +): () => string { + const url = new URL(databaseUrl); + const key = `${url.hostname}_${url.port || '5432'}_${url.pathname.slice(1)}_${prefix}`.replace( + /[^\w.-]/g, + '_', + ); + const dir = options.dir ?? path.join(os.tmpdir(), 'jantrik-test-phones'); + const now = options.now ?? Date.now; + const counterFile = path.join(dir, `${key}.txt`); + let next = 0; + let end = 0; + + const takeBlock = (): void => { + fs.mkdirSync(dir, { recursive: true }); + withLock(`${counterFile}.lock`, () => { + let stored = 0; + try { + stored = Number.parseInt(fs.readFileSync(counterFile, 'utf8'), 10) || 0; + } catch { + // No counter yet: start from the clock. + } + next = Math.max(stored, floorAt(now())); + end = next + BLOCK; + fs.writeFileSync(counterFile, String(end)); + }); + }; + + return () => { + if (next >= end) takeBlock(); + const n = next++; + return `${prefix}${LOW + (n % SPAN)}`; + }; +} diff --git a/packages/db/test/helpers.ts b/packages/db/test/helpers.ts index d5311ca..956fa79 100644 --- a/packages/db/test/helpers.ts +++ b/packages/db/test/helpers.ts @@ -10,12 +10,15 @@ import { type Tenant, } from '../src/index.js'; import { APP_URL, INGEST_URL, OWNER_URL, PLATFORM_URL } from './env.js'; +import { phoneSource } from './test-phones.js'; export const appClient = (): PrismaClient => createPrismaClient(APP_URL); -/** A random valid Bangladeshi mobile number (E.164). */ -export const randomPhone = (): string => - `+88017${String(Math.floor(Math.random() * 1e8)).padStart(8, '0')}`; +/** + * A valid Bangladeshi mobile number (E.164) that no other test user of this database has, in this + * run or an earlier one (`test-phones.ts`; the API tests draw from +88013, these from +88014). + */ +export const randomPhone: () => string = phoneSource('+88014', APP_URL); export const ownerClient = (): PrismaClient => createPrismaClient(OWNER_URL); /** The API platform module's role: the only one that may run the platform_* functions. */ export const platformClient = (): PrismaClient => createPrismaClient(PLATFORM_URL); diff --git a/packages/db/test/test-phones.test.ts b/packages/db/test/test-phones.test.ts new file mode 100644 index 0000000..877a4ec --- /dev/null +++ b/packages/db/test/test-phones.test.ts @@ -0,0 +1,77 @@ +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { BD_PHONE_E164 } from '@jantrik/shared'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { floorAt, phoneSource } from './test-phones.js'; + +describe('test phones (decisions-pending P0-8)', () => { + let dir: string; + const db = 'postgresql://u:p@localhost:5432/jantrik_x_test'; + const t0 = Date.UTC(2026, 10, 16, 9); + + beforeEach(() => { + dir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-phones-')); + }); + afterEach(() => fs.rmSync(dir, { recursive: true, force: true })); + + it('never repeats across processes sharing a database (two sources, interleaved)', () => { + const a = phoneSource('+88013', db, { dir, now: () => t0 }); + const b = phoneSource('+88013', db, { dir, now: () => t0 }); + const seen = new Set(); + for (let i = 0; i < 1_000; i++) { + for (const phone of [a(), b()]) { + expect(seen.has(phone)).toBe(false); + seen.add(phone); + } + } + expect(seen.size).toBe(2_000); + }); + + it('never repeats across runs: a later run continues after the earlier one', () => { + const first = phoneSource('+88013', db, { dir, now: () => t0 }); + const earlier = new Set(Array.from({ length: 500 }, () => first())); + // The next run starts a second later: its clock floor is behind the counter. + const second = phoneSource('+88013', db, { dir, now: () => t0 + 1_000 }); + for (let i = 0; i < 500; i++) expect(earlier.has(second())).toBe(false); + }); + + it('starts from the clock when the counter file is lost, ahead of what earlier runs used', () => { + const first = phoneSource('+88013', db, { dir, now: () => t0 }); + const earlier = new Set(Array.from({ length: 300 }, () => first())); + fs.rmSync(dir, { recursive: true, force: true }); + const later = phoneSource('+88013', db, { dir, now: () => t0 + 60_000 }); + for (let i = 0; i < 300; i++) expect(earlier.has(later())).toBe(false); + expect(floorAt(t0 + 60_000) - floorAt(t0)).toBeGreaterThan(300); + }); + + it('keeps a counter per database: another database starts on its own', () => { + const one = phoneSource('+88013', db, { dir, now: () => t0 }); + const other = phoneSource('+88013', db.replace('jantrik_x_test', 'jantrik_y_test'), { + dir, + now: () => t0, + }); + expect(one()).toBe(other()); + }); + + it('gives valid Bangladeshi mobile numbers, clear of the seeds and the old random ranges', () => { + const next = phoneSource('+88013', db, { dir, now: () => t0 }); + for (let i = 0; i < 50; i++) { + const phone = next(); + expect(phone).toMatch(BD_PHONE_E164); + const n = Number(phone.slice(6)); + expect(n).toBeGreaterThanOrEqual(50_000_000); + expect(n).toBeLessThan(99_000_000); + } + }); + + it('takes over a lock left behind by a process that died', () => { + const counter = path.join(dir, 'localhost_5432_jantrik_x_test__88013.txt'); + fs.mkdirSync(`${counter}.lock`); + const old = new Date(Date.now() - 60_000); + fs.utimesSync(`${counter}.lock`, old, old); + const next = phoneSource('+88013', db, { dir, now: () => t0 }); + expect(next()).toMatch(BD_PHONE_E164); + expect(fs.existsSync(`${counter}.lock`)).toBe(false); + }); +}); diff --git a/packages/db/test/test-phones.ts b/packages/db/test/test-phones.ts new file mode 100644 index 0000000..f03c431 --- /dev/null +++ b/packages/db/test/test-phones.ts @@ -0,0 +1,104 @@ +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; + +/** + * Phone numbers for test users that no other test user of the same database has (decisions-pending + * P0-8). Random numbers repeated now and then: a full run makes thousands of users, the test + * database keeps every run's users, and a repeated phone joins an existing user, which then has + * two memberships (a new owner got 403 on /me/context once). + * + * Each database has one counter, in a file under the OS temp folder, shared by every test process + * and every run against it. A process takes a block of numbers under a lock, then hands them out + * one by one. The counter never goes back behind the clock (`floorAt`), so a lost counter file + * does not restart at numbers earlier runs gave out. The numbers sit where nothing else is: + * `` + 50 000 000–98 999 999 (the seeds' fixed numbers are below; the old random phones + * used other operators). + * + * Kept identical in packages/db/test/test-phones.ts and apps/api/test/support/test-phones.ts (a + * test of the db copy pins how it behaves). + */ + +/** Numbers per block a process takes at once. */ +const BLOCK = 200; +const LOW = 50_000_000; +const SPAN = 49_000_000; +/** The counter's floor grows 20 a second from this day, so it is always ahead of older runs. */ +const EPOCH_MS = Date.UTC(2026, 10, 1); +const PER_SECOND = 20; + +export const floorAt = (nowMs: number): number => + Math.max(0, Math.floor(((nowMs - EPOCH_MS) / 1000) * PER_SECOND)); + +const pause = (ms: number): void => { + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); +}; + +/** Runs `fn` while holding a lock directory; a lock older than 10 s is left over and taken. */ +function withLock(lockDir: string, fn: () => T): T { + for (let tries = 0; ; tries++) { + try { + fs.mkdirSync(lockDir); + break; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; + try { + if (Date.now() - fs.statSync(lockDir).mtimeMs > 10_000) { + fs.rmSync(lockDir, { recursive: true, force: true }); + continue; + } + } catch { + continue; // released meanwhile + } + if (tries > 3_000) throw new Error(`test-phones: lock ${lockDir} stays taken`); + pause(10); + } + } + try { + return fn(); + } finally { + fs.rmSync(lockDir, { recursive: true, force: true }); + } +} + +/** + * A source of phones `NNNNNNNN` (prefix e.g. `+88013`) unique among all users of the + * database `databaseUrl` names (server, port and name; never the login). + */ +export function phoneSource( + prefix: string, + databaseUrl: string, + options: { dir?: string; now?: () => number } = {}, +): () => string { + const url = new URL(databaseUrl); + const key = `${url.hostname}_${url.port || '5432'}_${url.pathname.slice(1)}_${prefix}`.replace( + /[^\w.-]/g, + '_', + ); + const dir = options.dir ?? path.join(os.tmpdir(), 'jantrik-test-phones'); + const now = options.now ?? Date.now; + const counterFile = path.join(dir, `${key}.txt`); + let next = 0; + let end = 0; + + const takeBlock = (): void => { + fs.mkdirSync(dir, { recursive: true }); + withLock(`${counterFile}.lock`, () => { + let stored = 0; + try { + stored = Number.parseInt(fs.readFileSync(counterFile, 'utf8'), 10) || 0; + } catch { + // No counter yet: start from the clock. + } + next = Math.max(stored, floorAt(now())); + end = next + BLOCK; + fs.writeFileSync(counterFile, String(end)); + }); + }; + + return () => { + if (next >= end) takeBlock(); + const n = next++; + return `${prefix}${LOW + (n % SPAN)}`; + }; +} From 356c44827a0f2fefa82a2d01253ef1417a14f98c Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:07:45 +0600 Subject: [PATCH 05/44] The app login can no longer read users.password_hash (P1-J): SELECT on users is granted column by column without it, the login lookup returns only the hash's parameters and salt, and two definer functions for the current user compare a digest inside the database and say whether a password is set. Tests pin the readable columns, that no login but the owner may read the column, and which app-runnable functions touch it Co-Authored-By: Claude Opus 5.5 --- .../migration.sql | 72 ++++++++ packages/db/test/auth-functions.test.ts | 2 + packages/db/test/schema-safety.test.ts | 58 ++++++ packages/db/test/users-password-hash.test.ts | 170 ++++++++++++++++++ packages/db/test/users-rls.test.ts | 14 +- 5 files changed, 314 insertions(+), 2 deletions(-) create mode 100644 packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql create mode 100644 packages/db/test/users-password-hash.test.ts diff --git a/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql new file mode 100644 index 0000000..ec197ea --- /dev/null +++ b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql @@ -0,0 +1,72 @@ +-- P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's, so an SQL +-- injection in a request cannot take staff hashes away to crack offline (docs/database.md → users). + +-- ───────────── users: SELECT by column, every column but password_hash ───────────── +-- A table-level SELECT covers every column (a column REVOKE would change nothing), so the table +-- grant goes and the columns are granted one by one. A new users column needs its own GRANT. +-- UPDATE on password_hash stays (P1-B): setting a password writes it. +REVOKE SELECT ON users FROM jantrik_app; +GRANT SELECT (id, phone, email, name, name_bn, password_changed_at, locale, color_scheme, + created_at, updated_at) + ON users TO jantrik_app; + +-- ───────────── auth_find_user_for_login(): parameters and salt, never the digest ───────────── +-- It returned password_hash of any user by phone or email, which made the column grant above +-- pointless. It now returns the PHC string up to its last `$` (argon2id, version 19, m, t, p and +-- the salt); the API hashes the typed password with them and auth_my_password_matches() compares. +-- Only the format Jantrik writes is accepted (a 32-byte digest); anything else gives NULL, as a +-- corrupt hash would fail today. A changed result type needs DROP + CREATE. Privileges are set +-- BEFORE the ownership change (see fix_definer_function_privileges). +DROP FUNCTION auth_find_user_for_login(text, text); +CREATE FUNCTION auth_find_user_for_login(p_phone text, p_email text) + RETURNS TABLE (id uuid, name text, locale locale, password_params text) + LANGUAGE sql STABLE SECURITY DEFINER + SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT u.id, u.name, u.locale, + substring(u.password_hash FROM + '^(\$argon2id\$v=19\$m=[0-9]{1,10},t=[0-9]{1,10},p=[0-9]{1,3}\$[A-Za-z0-9+/]{11,64})\$[A-Za-z0-9+/]{43}$') + FROM users u + WHERE (p_phone IS NOT NULL AND u.phone = p_phone) + OR (p_email IS NOT NULL AND lower(u.email) = lower(p_email)) + LIMIT 1 + $$; +REVOKE ALL ON FUNCTION auth_find_user_for_login(text, text) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION auth_find_user_for_login(text, text) TO jantrik_app; +ALTER FUNCTION auth_find_user_for_login(text, text) OWNER TO jantrik_auth; + +-- ───────────── auth_my_password_matches(digest): the comparison, inside the database ───────────── +-- True when the current user's (app.user_id) stored hash has this SHA-256. The API sends the +-- SHA-256 of the hash it computed from the typed password, so the digest never leaves the +-- database, and what travels is fixed-size. No user parameter: scoped by context, like +-- auth_list_my_memberships(). +CREATE FUNCTION auth_my_password_matches(p_digest bytea) + RETURNS boolean + LANGUAGE sql STABLE SECURITY DEFINER + SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT EXISTS ( + SELECT 1 FROM users u + WHERE u.id = app_current_user_id() + AND u.password_hash IS NOT NULL + AND sha256(convert_to(u.password_hash, 'UTF8')) = p_digest + ) + $$; +REVOKE ALL ON FUNCTION auth_my_password_matches(bytea) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION auth_my_password_matches(bytea) TO jantrik_app; +ALTER FUNCTION auth_my_password_matches(bytea) OWNER TO jantrik_auth; + +-- ───────────── auth_my_password_is_set(): GET /me/password's hasPassword ───────────── +CREATE FUNCTION auth_my_password_is_set() + RETURNS boolean + LANGUAGE sql STABLE SECURITY DEFINER + SET search_path = pg_catalog, public, pg_temp + AS $$ + SELECT EXISTS ( + SELECT 1 FROM users u + WHERE u.id = app_current_user_id() AND u.password_hash IS NOT NULL + ) + $$; +REVOKE ALL ON FUNCTION auth_my_password_is_set() FROM PUBLIC; +GRANT EXECUTE ON FUNCTION auth_my_password_is_set() TO jantrik_app; +ALTER FUNCTION auth_my_password_is_set() OWNER TO jantrik_auth; diff --git a/packages/db/test/auth-functions.test.ts b/packages/db/test/auth-functions.test.ts index a12c968..6851cc6 100644 --- a/packages/db/test/auth-functions.test.ts +++ b/packages/db/test/auth-functions.test.ts @@ -8,6 +8,8 @@ const FUNCTIONS = [ 'auth_resolve_tenant', 'auth_find_refresh_token', 'app_find_or_create_user', + 'auth_my_password_matches', + 'auth_my_password_is_set', ]; describe('auth SECURITY DEFINER functions', () => { diff --git a/packages/db/test/schema-safety.test.ts b/packages/db/test/schema-safety.test.ts index cca5388..d562c7a 100644 --- a/packages/db/test/schema-safety.test.ts +++ b/packages/db/test/schema-safety.test.ts @@ -182,11 +182,69 @@ describe('schema safety net', () => { expect(scoped.map((r) => r.fn).sort()).toEqual([ 'app_find_or_create_user', 'auth_list_my_memberships', + 'auth_my_password_is_set', + 'auth_my_password_matches', 'search_student_ids', ]); expect(scoped.filter((r) => !r.scoped)).toEqual([]); }); + // P1-J: no login reads a password hash. jantrik_app reads users column by column, and the list + // is pinned here: a new column, or a table-level SELECT coming back, is a deliberate change. + it('the app login reads users by column, never password_hash', async () => { + const [table] = await app.$queryRaw<{ table_select: boolean }[]>` + SELECT has_table_privilege('jantrik_app', 'users', 'SELECT') AS table_select`; + expect(table).toEqual({ table_select: false }); + const columns = await app.$queryRaw<{ col: string }[]>` + SELECT a.attname::text AS col + FROM pg_attribute a + WHERE a.attrelid = 'users'::regclass AND a.attnum > 0 AND NOT a.attisdropped + AND has_column_privilege('jantrik_app', 'users', a.attname, 'SELECT') + ORDER BY a.attname`; + expect(columns.map((c) => c.col)).toEqual([ + 'color_scheme', + 'created_at', + 'email', + 'id', + 'locale', + 'name', + 'name_bn', + 'password_changed_at', + 'phone', + 'updated_at', + ]); + }); + + it('no login role but the owner, and not PUBLIC, may read users.password_hash', async () => { + const readers = await app.$queryRaw<{ name: string }[]>` + SELECT r.rolname::text AS name + FROM pg_roles r + WHERE (r.rolcanlogin OR r.rolname = 'public') AND NOT r.rolsuper + AND r.oid <> (SELECT relowner FROM pg_class WHERE oid = 'users'::regclass) + AND has_column_privilege(r.oid, 'users'::regclass, 'password_hash', 'SELECT') + UNION ALL + SELECT 'PUBLIC' WHERE has_column_privilege('public', 'users', 'password_hash', 'SELECT')`; + expect(readers).toEqual([]); + }); + + // The hash must not come back through a function either: every definer function jantrik_app + // may run that touches password_hash is listed here, and none returns a column of that name. + it('only the three login functions the app may run touch password_hash, and none returns it', async () => { + const rows = await app.$queryRaw<{ fn: string; result: string }[]>` + SELECT p.proname::text AS fn, pg_get_function_result(p.oid) AS result + FROM pg_proc p + WHERE p.pronamespace = 'public'::regnamespace AND p.prosecdef + AND has_function_privilege('jantrik_app', p.oid, 'EXECUTE') + AND p.prosrc ILIKE '%password_hash%' + ORDER BY 1`; + expect(rows.map((r) => r.fn)).toEqual([ + 'auth_find_user_for_login', + 'auth_my_password_is_set', + 'auth_my_password_matches', + ]); + expect(rows.filter((r) => /password_hash/i.test(r.result))).toEqual([]); + }); + // The login steps run before a platform session exists (the API has checked the password and // the second factor). Everything else needs a live session of an active admin. const PRE_SESSION_PLATFORM = [ diff --git a/packages/db/test/users-password-hash.test.ts b/packages/db/test/users-password-hash.test.ts new file mode 100644 index 0000000..e65b4aa --- /dev/null +++ b/packages/db/test/users-password-hash.test.ts @@ -0,0 +1,170 @@ +import { createHash } from 'node:crypto'; +import { hash } from '@node-rs/argon2'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { findOrCreateUser, withContext, withTenant, type PrismaClient } from '../src/index.js'; +import { appClient, createTenant, ownerClient, randomPhone } from './helpers.js'; + +// P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's. The +// login gets the hash's parameters and salt, and the database compares (docs/database.md → users). + +const sha256 = (s: string): Buffer => createHash('sha256').update(s, 'utf8').digest(); +/** The PHC string up to its last `$`: algorithm, version, parameters and salt, no digest. */ +const paramsOf = (phc: string): string => phc.slice(0, phc.lastIndexOf('$')); +const NIL = '00000000-0000-0000-0000-000000000000'; + +describe('users.password_hash is out of the app login’s reach (P1-J)', () => { + let app: PrismaClient; + let owner: PrismaClient; + let tenantId: string; + let staff: { id: string; phone: string; hash: string }; + let coMember: { id: string; phone: string }; + let noPassword: { id: string; phone: string }; + + /** Sets the user's own hash as that user (the app login keeps UPDATE on the column). */ + const setOwnHash = (userId: string, passwordHash: string | null) => + withContext(app, { userId }, (tx) => + tx.user.update({ where: { id: userId }, data: { passwordHash }, select: { id: true } }), + ); + + beforeAll(async () => { + app = appClient(); + owner = ownerClient(); + tenantId = (await createTenant(app)).id; + const make = (role: 'ADMIN' | 'TEACHER') => { + const phone = randomPhone(); + return withTenant(app, tenantId, async (tx) => { + const id = await findOrCreateUser(tx, phone, `Person ${role}`); + await tx.membership.create({ data: { tenantId, userId: id, role } }); + return { id, phone }; + }); + }; + const s = await make('ADMIN'); + staff = { ...s, hash: await hash('a long enough password') }; + await setOwnHash(staff.id, staff.hash); + coMember = await make('TEACHER'); + await setOwnHash(coMember.id, await hash('another long password')); + noPassword = await make('TEACHER'); + }); + + afterAll(async () => { + await app.$disconnect(); + await owner.$disconnect(); + }); + + it('cannot select password_hash: not its own, not a co-member’s, not with SELECT *', async () => { + await expect( + withContext( + app, + { userId: staff.id }, + (tx) => tx.$queryRaw`SELECT password_hash FROM users WHERE id = ${staff.id}::uuid`, + ), + ).rejects.toThrow(/permission denied/i); + await expect( + withContext( + app, + { tenantId, userId: coMember.id }, + (tx) => tx.$queryRaw`SELECT password_hash FROM users WHERE id = ${staff.id}::uuid`, + ), + ).rejects.toThrow(/permission denied/i); + await expect( + withContext(app, { userId: staff.id }, (tx) => tx.$queryRaw`SELECT * FROM users`), + ).rejects.toThrow(/permission denied/i); + // Not in a filter either (a WHERE on the column needs SELECT on it). + await expect( + withContext( + app, + { tenantId, userId: coMember.id }, + (tx) => tx.$queryRaw`SELECT id FROM users WHERE password_hash LIKE '$argon2id$%'`, + ), + ).rejects.toThrow(/permission denied/i); + }); + + it('every other column stays readable', async () => { + const rows = await withContext( + app, + { tenantId, userId: coMember.id }, + (tx) => tx.$queryRaw<{ id: string }[]>` + SELECT id::text, phone, email, name, name_bn, password_changed_at, locale, color_scheme, + created_at, updated_at + FROM users WHERE id = ${staff.id}::uuid`, + ); + expect(rows.map((r) => r.id)).toEqual([staff.id]); + }); + + it('the login lookup returns the parameters and salt, never the digest', async () => { + const rows = await app.$queryRaw[]>` + SELECT * FROM auth_find_user_for_login(${staff.phone}, NULL)`; + expect(rows).toHaveLength(1); + expect(Object.keys(rows[0]!).sort()).toEqual(['id', 'locale', 'name', 'password_params']); + expect(rows[0]!['password_params']).toBe(paramsOf(staff.hash)); + expect(staff.hash.startsWith(`${paramsOf(staff.hash)}$`)).toBe(true); + }); + + it('no parameters for a user without a password or with a hash in another format', async () => { + const paramsFor = async (phone: string) => + ( + await app.$queryRaw<{ password_params: string | null }[]>` + SELECT password_params FROM auth_find_user_for_login(${phone}, NULL)` + )[0]?.password_params; + expect(await paramsFor(noPassword.phone)).toBeNull(); + + const odd = randomPhone(); + const oddId = await withTenant(app, tenantId, async (tx) => { + const id = await findOrCreateUser(tx, odd, 'Odd Hash'); + await tx.membership.create({ data: { tenantId, userId: id, role: 'STAFF' } }); + return id; + }); + const good = await hash('a long enough password'); + for (const stored of [ + 'not-a-real-hash', + good.replace('$argon2id$', '$argon2i$'), + good.replace('$v=19$', '$v=16$'), + `${paramsOf(good)}$AAAA`, // a digest that is not 32 bytes + `${good}$extra`, + ]) { + await setOwnHash(oddId, stored); + expect(await paramsFor(odd), stored).toBeNull(); + } + }); + + it('auth_my_password_matches compares inside the database, for the current user only', async () => { + const matches = (userId: string | null, digest: Buffer) => + withContext( + app, + userId ? { userId } : {}, + async (tx) => + ( + await tx.$queryRaw<{ ok: boolean }[]>` + SELECT auth_my_password_matches(${digest}) AS ok` + )[0]!.ok, + ); + expect(await matches(staff.id, sha256(staff.hash))).toBe(true); + expect(await matches(staff.id, sha256(`${staff.hash}x`))).toBe(false); + expect(await matches(coMember.id, sha256(staff.hash))).toBe(false); + expect(await matches(noPassword.id, sha256(staff.hash))).toBe(false); + expect(await matches(NIL, sha256(staff.hash))).toBe(false); + expect(await matches(null, sha256(staff.hash))).toBe(false); + }); + + it('auth_my_password_is_set says whether the current user has a password', async () => { + const isSet = (userId: string | null) => + withContext( + app, + userId ? { userId } : {}, + async (tx) => + (await tx.$queryRaw<{ set: boolean }[]>`SELECT auth_my_password_is_set() AS set`)[0]!.set, + ); + expect(await isSet(staff.id)).toBe(true); + expect(await isSet(noPassword.id)).toBe(false); + expect(await isSet(null)).toBe(false); + }); + + it('the app login still writes its own hash; the owner reads it as that user', async () => { + const next = await hash('a third long password'); + await setOwnHash(coMember.id, next); + const row = await withContext(owner, { userId: coMember.id }, (tx) => + tx.user.findUniqueOrThrow({ where: { id: coMember.id }, select: { passwordHash: true } }), + ); + expect(row.passwordHash).toBe(next); + }); +}); diff --git a/packages/db/test/users-rls.test.ts b/packages/db/test/users-rls.test.ts index 76d8afd..72bacdc 100644 --- a/packages/db/test/users-rls.test.ts +++ b/packages/db/test/users-rls.test.ts @@ -1,6 +1,6 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { findOrCreateUser, withContext, withTenant, type PrismaClient } from '../src/index.js'; -import { appClient, createTenant, randomPhone } from './helpers.js'; +import { appClient, createTenant, ownerClient, randomPhone } from './helpers.js'; async function addMember(app: PrismaClient, tenantId: string, phone: string, name: string) { return withTenant(app, tenantId, async (tx) => { @@ -102,8 +102,18 @@ describe('RLS on users', () => { const row = await withContext(app, { userId: id }, (tx) => tx.user.findUniqueOrThrow({ where: { id } }), ); - expect(row).toMatchObject({ locale: 'en', nameBn: 'নাম', passwordHash: 'x' }); + expect(row).toMatchObject({ locale: 'en', nameBn: 'নাম' }); expect(row.passwordChangedAt).toEqual(changedAt); + // The app writes the hash but may not read it back (P1-J): the owner checks it, as that user. + const owner = ownerClient(); + try { + const { passwordHash } = await withContext(owner, { userId: id }, (tx) => + tx.user.findUniqueOrThrow({ where: { id }, select: { passwordHash: true } }), + ); + expect(passwordHash).toBe('x'); + } finally { + await owner.$disconnect(); + } }); it.each([ From 3ca69eb346abdfec4e25d7c0795378281eac1426 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:08:25 +0600 Subject: [PATCH 06/44] Every Prisma client leaves users.password_hash out of its reads (P1-J): createPrismaClient passes a global omit, the package's PrismaClient and TransactionClient types are that client's, and the generated class is no longer exported, so every client comes from the factory and TypeScript refuses code that reads the hash. Whole-row reads and updates of users by the app login keep working; a query that needs the hash (the owner, in tests) asks for it Co-Authored-By: Claude Opus 5.5 --- packages/db/src/cli/platform-admin.ts | 2 +- packages/db/src/client.ts | 51 ++++++++++++++++++++ packages/db/src/index.ts | 40 ++++----------- packages/db/src/login-privileges.ts | 2 +- packages/db/src/platform/context.ts | 2 +- packages/db/src/reference-data/templates.ts | 7 ++- packages/db/src/seed/demo.ts | 2 +- packages/db/src/seed/platform.ts | 2 +- packages/db/src/tenancy/context.ts | 4 +- packages/db/src/tenancy/provision.ts | 2 +- packages/db/test/helpers.ts | 5 +- packages/db/test/users-password-hash.test.ts | 18 +++++++ 12 files changed, 92 insertions(+), 45 deletions(-) create mode 100644 packages/db/src/client.ts diff --git a/packages/db/src/cli/platform-admin.ts b/packages/db/src/cli/platform-admin.ts index da311ac..8832fe4 100644 --- a/packages/db/src/cli/platform-admin.ts +++ b/packages/db/src/cli/platform-admin.ts @@ -1,6 +1,6 @@ import os from 'node:os'; import { hash } from '@node-rs/argon2'; -import type { PrismaClient } from '../generated/prisma/client.js'; +import type { PrismaClient } from '../client.js'; // `pnpm platform:admin `: create or manage platform admins (Jantrik's own staff) from // the server shell. Works in production (unlike the seed). Connects as the owner role diff --git a/packages/db/src/client.ts b/packages/db/src/client.ts new file mode 100644 index 0000000..4b27e4c --- /dev/null +++ b/packages/db/src/client.ts @@ -0,0 +1,51 @@ +import { PrismaPg } from '@prisma/adapter-pg'; +import type * as runtime from '@prisma/client/runtime/client'; +import { PrismaClient as GeneratedPrismaClient, type Prisma } from './generated/prisma/client.js'; + +/** + * Columns every client leaves out of its reads unless a query asks for them (P1-J). The app + * login may not SELECT `users.password_hash` (docs/database.md → users), so a read or an update + * that returned the whole row would be refused by the database; with the column omitted, Prisma + * never names it. The owner login can still read it with `omit: { passwordHash: false }` on one + * query (tests only). + */ +export const CLIENT_OMIT = { + user: { passwordHash: true }, +} as const satisfies Prisma.GlobalOmitConfig; + +/** The Prisma client of this package: always built by `createPrismaClient`, so `CLIENT_OMIT` applies. */ +export type PrismaClient = GeneratedPrismaClient; + +/** The client a `$transaction` callback receives. */ +export type TransactionClient = Omit; + +/** Connection pool settings a caller may set (node-postgres; none by default). */ +export interface PoolOptions { + /** + * How long getting a connection may take before it fails (default: no limit): opening a new + * one, and also waiting for a free one while the pool is full (at most 10 connections). + */ + connectionTimeoutMillis?: number; + /** TCP keep-alive on the pool's connections (default: off). */ + keepAlive?: boolean; + /** + * Idle time before the first keep-alive probe. Without it node-postgres passes 0, which keeps + * the operating system's default (about 2 hours on Linux and Windows). + */ + keepAliveInitialDelayMillis?: number; + /** + * Milliseconds a statement may run before the server cancels it (error 57014; default: no + * limit). Sent when each connection opens, so the server enforces it. + */ + statement_timeout?: number; + /** Most connections in the pool (default 10). */ + max?: number; +} + +/** Create a Prisma client bound to the given Postgres connection string. */ +export function createPrismaClient(connectionString: string, pool: PoolOptions = {}): PrismaClient { + return new GeneratedPrismaClient({ + adapter: new PrismaPg({ connectionString, ...pool }), + omit: CLIENT_OMIT, + }); +} diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index 08e0d3c..67e26d9 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -1,7 +1,13 @@ -import { PrismaPg } from '@prisma/adapter-pg'; -import { PrismaClient } from './generated/prisma/client.js'; - -export { PrismaClient }; +// The package's PrismaClient is the type of what `createPrismaClient` returns (users.password_hash +// omitted from reads, P1-J); the generated class itself is not exported, so every client is built +// by the factory. +export { + CLIENT_OMIT, + createPrismaClient, + type PoolOptions, + type PrismaClient, + type TransactionClient, +} from './client.js'; export * from './generated/prisma/client.js'; export * from './login-privileges.js'; export * from './platform/context.js'; @@ -12,29 +18,3 @@ export * from './tenancy/provision.js'; export * from './tenancy/search.js'; export * from './tenancy/users.js'; export { seedTemplates } from './reference-data/templates.js'; - -/** Connection pool settings a caller may set (node-postgres; none by default). */ -export interface PoolOptions { - /** - * How long getting a connection may take before it fails (default: no limit): opening a new - * one, and also waiting for a free one while the pool is full (at most 10 connections). - */ - connectionTimeoutMillis?: number; - /** TCP keep-alive on the pool's connections (default: off). */ - keepAlive?: boolean; - /** - * Idle time before the first keep-alive probe. Without it node-postgres passes 0, which keeps - * the operating system's default (about 2 hours on Linux and Windows). - */ - keepAliveInitialDelayMillis?: number; - /** - * Milliseconds a statement may run before the server cancels it (error 57014; default: no - * limit). Sent when each connection opens, so the server enforces it. - */ - statement_timeout?: number; -} - -/** Create a Prisma client bound to the given Postgres connection string. */ -export function createPrismaClient(connectionString: string, pool: PoolOptions = {}): PrismaClient { - return new PrismaClient({ adapter: new PrismaPg({ connectionString, ...pool }) }); -} diff --git a/packages/db/src/login-privileges.ts b/packages/db/src/login-privileges.ts index 1be77b0..de6ba17 100644 --- a/packages/db/src/login-privileges.ts +++ b/packages/db/src/login-privileges.ts @@ -1,4 +1,4 @@ -import type { PrismaClient } from './generated/prisma/client.js'; +import type { PrismaClient } from './client.js'; /** * Predefined roles that pass the grants this design relies on (the platform tables, the diff --git a/packages/db/src/platform/context.ts b/packages/db/src/platform/context.ts index c3d5991..8a28231 100644 --- a/packages/db/src/platform/context.ts +++ b/packages/db/src/platform/context.ts @@ -1,4 +1,4 @@ -import type { PrismaClient } from '../generated/prisma/client.js'; +import type { PrismaClient } from '../client.js'; import type { TenantTx, TxOptions } from '../tenancy/context.js'; const TOKEN_HASH_RE = /^[0-9a-f]{64}$/; diff --git a/packages/db/src/reference-data/templates.ts b/packages/db/src/reference-data/templates.ts index b7b921b..3bd24ea 100644 --- a/packages/db/src/reference-data/templates.ts +++ b/packages/db/src/reference-data/templates.ts @@ -4,11 +4,10 @@ import type { GpaRounding, Locale, PassRule, - Prisma, - PrismaClient, RoundingMode, ThemePreset, } from '../generated/prisma/client.js'; +import type { PrismaClient, TransactionClient } from '../client.js'; // Global reference data: institute types and the templates copied into each new tenant. // Adding an institute type (QAWMI, ALIYA, ENGLISH_MEDIUM, TECHNICAL, ...) means adding an entry @@ -344,7 +343,7 @@ export async function seedTemplates(client: PrismaClient): Promise { ); } -async function upsertTemplates(owner: Prisma.TransactionClient): Promise { +async function upsertTemplates(owner: TransactionClient): Promise { const schemeIds = new Map(); for (const def of GRADING_SCHEMES) { const schemeData = { @@ -442,7 +441,7 @@ async function upsertTemplates(owner: Prisma.TransactionClient): Promise { /** A template subject's exam parts and combined pass marks, exactly as defined (stale ones go). */ async function upsertMarks( - owner: Prisma.TransactionClient, + owner: TransactionClient, templateSubjectId: string, sub: SubjectDef, ): Promise { diff --git a/packages/db/src/seed/demo.ts b/packages/db/src/seed/demo.ts index dddd407..3463571 100644 --- a/packages/db/src/seed/demo.ts +++ b/packages/db/src/seed/demo.ts @@ -3,9 +3,9 @@ import { Prisma, type GuardianRelation, type ModuleKey, - type PrismaClient, type Role, } from '../generated/prisma/client.js'; +import type { PrismaClient } from '../client.js'; import { hash } from '@node-rs/argon2'; import { withContext, withTenant, type TenantTx } from '../tenancy/context.js'; import { provisionTenant } from '../tenancy/provision.js'; diff --git a/packages/db/src/seed/platform.ts b/packages/db/src/seed/platform.ts index 3b442e4..d517bcf 100644 --- a/packages/db/src/seed/platform.ts +++ b/packages/db/src/seed/platform.ts @@ -1,5 +1,5 @@ import { hash } from '@node-rs/argon2'; -import type { PrismaClient } from '../generated/prisma/client.js'; +import type { PrismaClient } from '../client.js'; import { DEMO_STAFF_PASSWORD } from './demo.js'; /** The development platform admin (docs/demo-accounts.md). Production uses `pnpm platform:admin`. */ diff --git a/packages/db/src/tenancy/context.ts b/packages/db/src/tenancy/context.ts index 9cbe136..fdd334e 100644 --- a/packages/db/src/tenancy/context.ts +++ b/packages/db/src/tenancy/context.ts @@ -1,4 +1,4 @@ -import type { Prisma, PrismaClient } from '../generated/prisma/client.js'; +import type { PrismaClient, TransactionClient } from '../client.js'; const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; @@ -13,7 +13,7 @@ export function assertTenantId(tenantId: string): void { } /** Transaction client handed to `withTenant` / `withContext` callbacks. */ -export type TenantTx = Prisma.TransactionClient; +export type TenantTx = TransactionClient; /** RLS context: `app.tenant_id` and/or `app.user_id`. Unset means "nothing visible". */ export interface DbContext { diff --git a/packages/db/src/tenancy/provision.ts b/packages/db/src/tenancy/provision.ts index 6023dbb..146e76a 100644 --- a/packages/db/src/tenancy/provision.ts +++ b/packages/db/src/tenancy/provision.ts @@ -2,10 +2,10 @@ import { v7 as uuidv7 } from 'uuid'; import { ModuleKey, type Locale, - type PrismaClient, type Tenant, type TenantStatus, } from '../generated/prisma/client.js'; +import type { PrismaClient } from '../client.js'; import { withTenant, type TenantTx } from './context.js'; export interface ProvisionTenantInput { diff --git a/packages/db/test/helpers.ts b/packages/db/test/helpers.ts index d5311ca..74aa217 100644 --- a/packages/db/test/helpers.ts +++ b/packages/db/test/helpers.ts @@ -1,11 +1,10 @@ import { randomBytes, randomUUID } from 'node:crypto'; -import { PrismaPg } from '@prisma/adapter-pg'; import { - PrismaClient, createPrismaClient, hashPlatformToken, provisionTenant, withTenant, + type PrismaClient, type ProvisionTenantInput, type Tenant, } from '../src/index.js'; @@ -52,7 +51,7 @@ export async function newPlatformSession( /** App-role client with a single pooled connection, to test connection reuse. */ export const singleConnectionAppClient = (): PrismaClient => - new PrismaClient({ adapter: new PrismaPg({ connectionString: APP_URL, max: 1 }) }); + createPrismaClient(APP_URL, { max: 1 }); export async function createTenant( app: PrismaClient, diff --git a/packages/db/test/users-password-hash.test.ts b/packages/db/test/users-password-hash.test.ts index e65b4aa..e731f26 100644 --- a/packages/db/test/users-password-hash.test.ts +++ b/packages/db/test/users-password-hash.test.ts @@ -167,4 +167,22 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { ); expect(row.passwordHash).toBe(next); }); + + it('every Prisma client leaves the hash out, so whole-row reads and updates work', async () => { + const read = await withContext(app, { userId: staff.id }, (tx) => + tx.user.findUniqueOrThrow({ where: { id: staff.id } }), + ); + expect(read.id).toBe(staff.id); + expect('passwordHash' in read).toBe(false); + const updated = await withContext(app, { userId: staff.id }, (tx) => + tx.user.update({ where: { id: staff.id }, data: { locale: 'en' } }), + ); + expect(updated.locale).toBe('en'); + expect('passwordHash' in updated).toBe(false); + // The owner asks for it explicitly on one query. + const withHash = await withContext(owner, { userId: staff.id }, (tx) => + tx.user.findUniqueOrThrow({ where: { id: staff.id }, omit: { passwordHash: false } }), + ); + expect(withHash.passwordHash).toBe(staff.hash); + }); }); From 30e85f63f9bc0a6e2e250df20f6ec820bf281509 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:09:03 +0600 Subject: [PATCH 07/44] Files and the institute profile in the database (P2 task 1): stored_files (S I D; per-kind formats and caps by CHECK), stored_file_usage (S I U), institute_profiles (S I U, one per institute, the field CHECKs), students.photo_file_id (composite key, one student per file) replacing the never-written photo_url; forced RLS and isolation tests for each Co-Authored-By: Claude Opus 5.5 --- .../migration.sql | 190 ++++++++++++ .../migration.sql | 13 + packages/db/prisma/schema.prisma | 114 ++++++- packages/db/test/files-rls.test.ts | 282 ++++++++++++++++++ packages/db/test/schema-safety.test.ts | 3 + 5 files changed, 601 insertions(+), 1 deletion(-) create mode 100644 packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql create mode 100644 packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql create mode 100644 packages/db/test/files-rls.test.ts diff --git a/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql b/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql new file mode 100644 index 0000000..096b76c --- /dev/null +++ b/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql @@ -0,0 +1,190 @@ +-- Sprint 1 P2 (docs/plans/sprint-1-p2-files.md, docs/files.md): images stored in the database +-- behind the API's FileStore, the per-institute usage total, and the institute's own profile. + +-- CreateEnum +CREATE TYPE "stored_file_kind" AS ENUM ('STUDENT_PHOTO', 'APPLICANT_PHOTO', 'LOGO', 'SIGNATURE', 'SEAL', 'DOCUMENT_ASSET'); + +-- CreateTable +CREATE TABLE "stored_files" ( + "id" UUID NOT NULL, + "tenant_id" UUID NOT NULL, + "kind" "stored_file_kind" NOT NULL, + "mime" TEXT NOT NULL, + "bytes" BYTEA NOT NULL, + "size_bytes" INTEGER NOT NULL, + "sha256" CHAR(64) NOT NULL, + "width" INTEGER NOT NULL, + "height" INTEGER NOT NULL, + "created_by_id" UUID, + "created_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "stored_files_pkey" PRIMARY KEY ("id") +); + +-- CreateTable +CREATE TABLE "stored_file_usage" ( + "id" UUID NOT NULL, + "tenant_id" UUID NOT NULL, + "bytes_used" BIGINT NOT NULL DEFAULT 0, + "file_count" INTEGER NOT NULL DEFAULT 0, + "created_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updated_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "stored_file_usage_pkey" PRIMARY KEY ("id") +); + +-- CreateTable +CREATE TABLE "institute_profiles" ( + "id" UUID NOT NULL, + "tenant_id" UUID NOT NULL, + "name_bn" TEXT, + "name_en" TEXT, + "short_name" TEXT, + "eiin" TEXT, + "address_bn" TEXT, + "address_en" TEXT, + "phone" TEXT, + "email" TEXT, + "website" TEXT, + "head_title_bn" TEXT, + "head_title_en" TEXT, + "head_name_bn" TEXT, + "head_name_en" TEXT, + "established_year" SMALLINT, + "logo_file_id" UUID, + "head_signature_file_id" UUID, + "seal_file_id" UUID, + "created_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updated_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "institute_profiles_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE INDEX "stored_files_tenant_id_kind_idx" ON "stored_files"("tenant_id", "kind"); + +-- CreateIndex +CREATE UNIQUE INDEX "stored_files_tenant_id_id_key" ON "stored_files"("tenant_id", "id"); + +-- CreateIndex +CREATE UNIQUE INDEX "stored_file_usage_tenant_id_key" ON "stored_file_usage"("tenant_id"); + +-- CreateIndex +CREATE UNIQUE INDEX "stored_file_usage_tenant_id_id_key" ON "stored_file_usage"("tenant_id", "id"); + +-- CreateIndex +CREATE UNIQUE INDEX "institute_profiles_tenant_id_key" ON "institute_profiles"("tenant_id"); + +-- CreateIndex +CREATE UNIQUE INDEX "institute_profiles_tenant_id_id_key" ON "institute_profiles"("tenant_id", "id"); + +-- CreateIndex +CREATE UNIQUE INDEX "institute_profiles_tenant_id_logo_file_id_key" ON "institute_profiles"("tenant_id", "logo_file_id"); + +-- CreateIndex +CREATE UNIQUE INDEX "institute_profiles_tenant_id_head_signature_file_id_key" ON "institute_profiles"("tenant_id", "head_signature_file_id"); + +-- CreateIndex +CREATE UNIQUE INDEX "institute_profiles_tenant_id_seal_file_id_key" ON "institute_profiles"("tenant_id", "seal_file_id"); + +-- AddForeignKey +ALTER TABLE "stored_files" ADD CONSTRAINT "stored_files_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "stored_files" ADD CONSTRAINT "stored_files_created_by_id_fkey" FOREIGN KEY ("created_by_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "stored_file_usage" ADD CONSTRAINT "stored_file_usage_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_logo_file_id_fkey" FOREIGN KEY ("tenant_id", "logo_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_head_signature_file_id_fkey" FOREIGN KEY ("tenant_id", "head_signature_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- AddForeignKey +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_seal_file_id_fkey" FOREIGN KEY ("tenant_id", "seal_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; + +-- Row-Level Security (docs/database.md → Checklist). +ALTER TABLE stored_files ENABLE ROW LEVEL SECURITY; +ALTER TABLE stored_files FORCE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON stored_files + USING (tenant_id = app_current_tenant_id()) + WITH CHECK (tenant_id = app_current_tenant_id()); + +ALTER TABLE stored_file_usage ENABLE ROW LEVEL SECURITY; +ALTER TABLE stored_file_usage FORCE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON stored_file_usage + USING (tenant_id = app_current_tenant_id()) + WITH CHECK (tenant_id = app_current_tenant_id()); + +ALTER TABLE institute_profiles ENABLE ROW LEVEL SECURITY; +ALTER TABLE institute_profiles FORCE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON institute_profiles + USING (tenant_id = app_current_tenant_id()) + WITH CHECK (tenant_id = app_current_tenant_id()); + +-- A file never changes (a replaced image is a new row; the old one is deleted). The usage total +-- and the profile are never deleted. +GRANT SELECT, INSERT, DELETE ON stored_files TO jantrik_app; +GRANT SELECT, INSERT, UPDATE ON stored_file_usage TO jantrik_app; +GRANT SELECT, INSERT, UPDATE ON institute_profiles TO jantrik_app; + +-- The caps of docs/files.md, also checked in code (packages/shared/src/files.ts → FILE_LIMITS): +-- formats per kind, bytes per kind, and the stored size is the bytes' real length. +ALTER TABLE stored_files + ADD CONSTRAINT stored_files_mime CHECK ( + (kind IN ('STUDENT_PHOTO', 'APPLICANT_PHOTO') AND mime = 'image/jpeg') + OR (kind IN ('LOGO', 'SEAL') AND mime IN ('image/png', 'image/webp')) + OR (kind = 'SIGNATURE' AND mime = 'image/png') + OR (kind = 'DOCUMENT_ASSET' AND mime IN ('image/jpeg', 'image/png', 'image/webp')) + ), + ADD CONSTRAINT stored_files_size CHECK ( + size_bytes = octet_length(bytes) + AND size_bytes > 0 + AND size_bytes <= CASE kind + WHEN 'STUDENT_PHOTO' THEN 204800 + WHEN 'APPLICANT_PHOTO' THEN 204800 + WHEN 'DOCUMENT_ASSET' THEN 262144 + ELSE 102400 + END + ), + ADD CONSTRAINT stored_files_sha256 CHECK (sha256 ~ '^[0-9a-f]{64}$'), + ADD CONSTRAINT stored_files_dimensions CHECK (width BETWEEN 1 AND 4000 AND height BETWEEN 1 AND 4000); + +ALTER TABLE stored_file_usage + ADD CONSTRAINT stored_file_usage_non_negative CHECK (bytes_used >= 0 AND file_count >= 0); + +ALTER TABLE institute_profiles + ADD CONSTRAINT institute_profiles_name CHECK (name_bn IS NOT NULL OR name_en IS NOT NULL), + ADD CONSTRAINT institute_profiles_lengths CHECK ( + (name_bn IS NULL OR char_length(name_bn) BETWEEN 1 AND 200) + AND (name_en IS NULL OR char_length(name_en) BETWEEN 1 AND 200) + AND (short_name IS NULL OR char_length(short_name) BETWEEN 1 AND 30) + AND (address_bn IS NULL OR char_length(address_bn) BETWEEN 1 AND 300) + AND (address_en IS NULL OR char_length(address_en) BETWEEN 1 AND 300) + AND (head_title_bn IS NULL OR char_length(head_title_bn) BETWEEN 1 AND 60) + AND (head_title_en IS NULL OR char_length(head_title_en) BETWEEN 1 AND 60) + AND (head_name_bn IS NULL OR char_length(head_name_bn) BETWEEN 1 AND 100) + AND (head_name_en IS NULL OR char_length(head_name_en) BETWEEN 1 AND 100) + ), + ADD CONSTRAINT institute_profiles_eiin CHECK (eiin IS NULL OR eiin ~ '^[0-9]{6}$'), + ADD CONSTRAINT institute_profiles_phone CHECK (phone IS NULL OR phone ~ '^\+?[0-9]{5,15}$'), + ADD CONSTRAINT institute_profiles_email CHECK ( + email IS NULL OR (char_length(email) <= 254 AND email ~ '^[^@\s]+@[^@\s]+\.[^@\s]+$') + ), + ADD CONSTRAINT institute_profiles_website CHECK ( + website IS NULL OR (char_length(website) <= 200 AND website ~ '^https?://\S+$') + ), + ADD CONSTRAINT institute_profiles_established_year CHECK ( + established_year IS NULL OR established_year BETWEEN 1800 AND 2100 + ), + -- One file in one place: the unique indexes cover each column; this covers the row's three. + ADD CONSTRAINT institute_profiles_distinct_files CHECK ( + (logo_file_id IS NULL OR (logo_file_id IS DISTINCT FROM head_signature_file_id + AND logo_file_id IS DISTINCT FROM seal_file_id)) + AND (head_signature_file_id IS NULL OR head_signature_file_id IS DISTINCT FROM seal_file_id) + ); diff --git a/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql b/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql new file mode 100644 index 0000000..f09501a --- /dev/null +++ b/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql @@ -0,0 +1,13 @@ +-- Sprint 1 P2: a student's photo is a stored file (kind STUDENT_PHOTO), referenced by a composite +-- key so it can only be a file of the student's own institute. The old photo_url column was never +-- written (always null) and goes. + +-- AlterTable +ALTER TABLE "students" DROP COLUMN "photo_url", +ADD COLUMN "photo_file_id" UUID; + +-- CreateIndex (also the foreign key's index: a file belongs to one student) +CREATE UNIQUE INDEX "students_tenant_id_photo_file_id_key" ON "students"("tenant_id", "photo_file_id"); + +-- AddForeignKey +ALTER TABLE "students" ADD CONSTRAINT "students_tenant_id_photo_file_id_fkey" FOREIGN KEY ("tenant_id", "photo_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma index 493b264..02dda1e 100644 --- a/packages/db/prisma/schema.prisma +++ b/packages/db/prisma/schema.prisma @@ -592,6 +592,8 @@ model User { deviceSourceIpsTrusted DeviceSourceIp[] @relation("DeviceSourceIpTrustedBy") staffDaysUpdated StaffAttendanceDay[] @relation("StaffAttendanceDayUpdatedBy") + storedFilesCreated StoredFile[] @relation("StoredFileCreatedBy") + @@map("users") } @@ -687,6 +689,10 @@ model Tenant { deviceSourceIps DeviceSourceIp[] staffAttendanceDays StaffAttendanceDay[] + storedFiles StoredFile[] + storedFileUsage StoredFileUsage? + instituteProfile InstituteProfile? + @@index([instituteTypeId]) @@map("tenants") } @@ -1004,7 +1010,8 @@ model Student { nameEn String? @map("name_en") dateOfBirth DateTime? @map("date_of_birth") @db.Date gender Gender? - photoUrl String? @map("photo_url") + /// The student's photo (stored_files, kind STUDENT_PHOTO); replaced files are deleted. + photoFileId String? @map("photo_file_id") @db.Uuid status StudentStatus @default(ACTIVE) // Fields required for Bangladesh education board registration. fatherNameBn String? @map("father_name_bn") @@ -1024,6 +1031,7 @@ model Student { tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict) user User? @relation(fields: [userId], references: [id], onDelete: SetNull) + photoFile StoredFile? @relation("StudentPhoto", fields: [tenantId, photoFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) guardians StudentGuardian[] enrolments Enrolment[] @@ -1042,6 +1050,8 @@ model Student { @@unique([tenantId, id]) @@unique([tenantId, studentCode]) @@unique([tenantId, birthRegistrationNo]) + // A file belongs to one student (also the foreign key's index). + @@unique([tenantId, photoFileId]) @@index([tenantId, status], where: raw("deleted_at IS NULL")) @@index([tenantId, nameEn]) // Trigram indexes for ILIKE '%…%' search (GET /students). @@ -3112,3 +3122,105 @@ model StaffAttendanceDay { @@index([tenantId, date]) @@map("staff_attendance_days") } + +// ───────────────────────────── Files and the institute profile (sprint 1 P2) ───────────────────────────── +// docs/files.md. Only apps/api/src/files/postgres-file-store.ts reads or writes stored_files and +// stored_file_usage (a code scan checks it); callers use the FileStore interface. + +enum StoredFileKind { + STUDENT_PHOTO + APPLICANT_PHOTO + LOGO + SIGNATURE + SEAL + DOCUMENT_ASSET + + @@map("stored_file_kind") +} + +/// An image stored in the database, already re-encoded by the API (never the uploaded bytes). +/// Rows never change (no UPDATE grant): a replaced image is a new row, and the old one is deleted. +model StoredFile { + id String @id @default(uuid(7)) @db.Uuid + tenantId String @map("tenant_id") @db.Uuid + kind StoredFileKind + /// image/jpeg, image/png or image/webp; the CHECK pairs each kind with its formats. + mime String + bytes Bytes + /// = octet_length(bytes); at most the kind's cap (CHECK). + sizeBytes Int @map("size_bytes") + /// Hex SHA-256 of bytes: the ETag. + sha256 String @db.Char(64) + width Int + height Int + createdById String? @map("created_by_id") @db.Uuid + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + + tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict, onUpdate: Restrict) + createdBy User? @relation("StoredFileCreatedBy", fields: [createdById], references: [id], onDelete: SetNull, onUpdate: Restrict) + + student Student? @relation("StudentPhoto") + profileLogo InstituteProfile? @relation("InstituteProfileLogo") + profileSignature InstituteProfile? @relation("InstituteProfileSignature") + profileSeal InstituteProfile? @relation("InstituteProfileSeal") + + @@unique([tenantId, id]) + @@index([tenantId, kind]) + @@map("stored_files") +} + +/// One row per institute once it stores a file: the running total for the per-institute cap +/// (FILE_STORAGE_PER_TENANT_MB), changed with every put and delete under the institute's lock. +model StoredFileUsage { + id String @id @default(uuid(7)) @db.Uuid + tenantId String @unique @map("tenant_id") @db.Uuid + bytesUsed BigInt @default(0) @map("bytes_used") + fileCount Int @default(0) @map("file_count") + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) + + tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict, onUpdate: Restrict) + + @@unique([tenantId, id]) + @@map("stored_file_usage") +} + +/// The institute's own profile (at most one per institute, created on the first save or image). +/// tenants.name stays the name the platform registered; these are the institute's own words. +model InstituteProfile { + id String @id @default(uuid(7)) @db.Uuid + tenantId String @unique @map("tenant_id") @db.Uuid + nameBn String? @map("name_bn") + nameEn String? @map("name_en") + shortName String? @map("short_name") + /// BANBEIS EIIN: 6 ASCII digits. + eiin String? + addressBn String? @map("address_bn") + addressEn String? @map("address_en") + /// 5-15 ASCII digits with an optional leading + (a Bangladeshi mobile is stored as E.164). + phone String? + email String? + website String? + headTitleBn String? @map("head_title_bn") + headTitleEn String? @map("head_title_en") + headNameBn String? @map("head_name_bn") + headNameEn String? @map("head_name_en") + establishedYear Int? @map("established_year") @db.SmallInt + logoFileId String? @map("logo_file_id") @db.Uuid + headSignatureFileId String? @map("head_signature_file_id") @db.Uuid + sealFileId String? @map("seal_file_id") @db.Uuid + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) + + tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict, onUpdate: Restrict) + logoFile StoredFile? @relation("InstituteProfileLogo", fields: [tenantId, logoFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) + signatureFile StoredFile? @relation("InstituteProfileSignature", fields: [tenantId, headSignatureFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) + sealFile StoredFile? @relation("InstituteProfileSeal", fields: [tenantId, sealFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) + + @@unique([tenantId, id]) + // One file is used in one place (also each foreign key's index). + @@unique([tenantId, logoFileId]) + @@unique([tenantId, headSignatureFileId]) + @@unique([tenantId, sealFileId]) + @@map("institute_profiles") +} diff --git a/packages/db/test/files-rls.test.ts b/packages/db/test/files-rls.test.ts new file mode 100644 index 0000000..22487bd --- /dev/null +++ b/packages/db/test/files-rls.test.ts @@ -0,0 +1,282 @@ +import { createHash } from 'node:crypto'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { withTenant, type PrismaClient, type StoredFileKind } from '../src/index.js'; +import { appClient, createStudent, createTenant } from './helpers.js'; + +// Sprint 1 P2 (docs/plans/sprint-1-p2-files.md): stored_files, stored_file_usage, +// institute_profiles and students.photo_file_id. Tenant isolation, the grants (no UPDATE of a +// file, no DELETE of usage or profile), the CHECKs that back the per-kind caps, and the composite +// foreign keys that keep a row from pointing at another institute's file. + +type Mime = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/gif' | 'text/plain'; + +function fileData( + tenantId: string, + kind: StoredFileKind, + mime: Mime, + size: number, + over: Partial<{ sizeBytes: number; sha256: string; width: number; height: number }> = {}, +) { + const bytes = new Uint8Array(size); + bytes.fill(7); + return { + tenantId, + kind, + mime, + bytes, + sizeBytes: over.sizeBytes ?? size, + sha256: over.sha256 ?? createHash('sha256').update(bytes).digest('hex'), + width: over.width ?? 100, + height: over.height ?? 120, + }; +} + +describe('files and the institute profile (P2)', () => { + let app: PrismaClient; + let a: string; + let b: string; + let aFile: string; + + const putFile = ( + tenantId: string, + kind: StoredFileKind = 'STUDENT_PHOTO', + mime: Mime = 'image/jpeg', + size = 1000, + ) => + withTenant(app, tenantId, (tx) => + tx.storedFile.create({ data: fileData(tenantId, kind, mime, size), select: { id: true } }), + ).then((f) => f.id); + + beforeAll(async () => { + app = appClient(); + a = (await createTenant(app)).id; + b = (await createTenant(app)).id; + aFile = await putFile(a); + }); + + afterAll(async () => { + await app.$disconnect(); + }); + + describe('stored_files', () => { + it("another institute cannot read, delete or write A's files", async () => { + await withTenant(app, b, async (tx) => { + expect(await tx.storedFile.findMany({ select: { id: true } })).toEqual([]); + expect((await tx.storedFile.deleteMany({ where: { id: aFile } })).count).toBe(0); + }); + await expect( + withTenant(app, b, (tx) => + tx.storedFile.create({ + data: fileData(a, 'LOGO', 'image/png', 10), + select: { id: true }, + }), + ), + ).rejects.toThrow(); + const mine = await withTenant(app, a, (tx) => + tx.storedFile.findUniqueOrThrow({ where: { id: aFile }, select: { sizeBytes: true } }), + ); + expect(mine.sizeBytes).toBe(1000); + }); + + it('a file never changes: the app has no UPDATE', async () => { + await expect( + withTenant(app, a, (tx) => tx.$executeRaw`UPDATE stored_files SET width = 5`), + ).rejects.toThrow(/permission denied/); + }); + + it.each<[string, StoredFileKind, Mime, number, Parameters[4]]>([ + ['an unknown mime', 'DOCUMENT_ASSET', 'text/plain', 10, {}], + ['a GIF', 'DOCUMENT_ASSET', 'image/gif', 10, {}], + ['a PNG photo', 'STUDENT_PHOTO', 'image/png', 10, {}], + ['a JPEG signature', 'SIGNATURE', 'image/jpeg', 10, {}], + ['a JPEG logo', 'LOGO', 'image/jpeg', 10, {}], + ['a photo over 200 KB', 'STUDENT_PHOTO', 'image/jpeg', 204_801, {}], + ['an applicant photo over 200 KB', 'APPLICANT_PHOTO', 'image/jpeg', 204_801, {}], + ['a logo over 100 KB', 'LOGO', 'image/png', 102_401, {}], + ['a seal over 100 KB', 'SEAL', 'image/webp', 102_401, {}], + ['a signature over 100 KB', 'SIGNATURE', 'image/png', 102_401, {}], + ['a document asset over 256 KB', 'DOCUMENT_ASSET', 'image/png', 262_145, {}], + ['a size that is not the bytes’ length', 'STUDENT_PHOTO', 'image/jpeg', 10, { sizeBytes: 9 }], + ['a malformed sha256', 'STUDENT_PHOTO', 'image/jpeg', 10, { sha256: 'ABC' }], + ['width 0', 'STUDENT_PHOTO', 'image/jpeg', 10, { width: 0 }], + ['height over 4000', 'STUDENT_PHOTO', 'image/jpeg', 10, { height: 4001 }], + ])('refuses %s', async (_name, kind, mime, size, over) => { + await expect( + withTenant(app, a, (tx) => + tx.storedFile.create({ data: fileData(a, kind, mime, size, over), select: { id: true } }), + ), + ).rejects.toThrow(); + }); + + it.each<[StoredFileKind, Mime, number]>([ + ['STUDENT_PHOTO', 'image/jpeg', 204_800], + ['APPLICANT_PHOTO', 'image/jpeg', 204_800], + ['LOGO', 'image/png', 102_400], + ['LOGO', 'image/webp', 102_400], + ['SEAL', 'image/png', 102_400], + ['SIGNATURE', 'image/png', 102_400], + ['DOCUMENT_ASSET', 'image/jpeg', 262_144], + ])('accepts a %s (%s) of exactly its cap', async (kind, mime, size) => { + await expect(putFile(a, kind, mime, size)).resolves.toMatch(/^[0-9a-f-]{36}$/); + }); + }); + + describe('stored_file_usage', () => { + it('isolated per institute, never deleted, never negative', async () => { + await withTenant(app, a, (tx) => + tx.storedFileUsage.create({ data: { tenantId: a, bytesUsed: 1000, fileCount: 1 } }), + ); + await withTenant(app, b, async (tx) => { + expect(await tx.storedFileUsage.findMany()).toEqual([]); + expect((await tx.storedFileUsage.updateMany({ data: { bytesUsed: 0 } })).count).toBe(0); + }); + await expect( + withTenant(app, b, (tx) => tx.storedFileUsage.create({ data: { tenantId: a } })), + ).rejects.toThrow(); + await expect( + withTenant(app, a, (tx) => tx.$executeRaw`DELETE FROM stored_file_usage`), + ).rejects.toThrow(/permission denied/); + await expect( + withTenant(app, a, (tx) => tx.storedFileUsage.updateMany({ data: { bytesUsed: -1 } })), + ).rejects.toThrow(); + await expect( + withTenant(app, a, (tx) => tx.storedFileUsage.updateMany({ data: { fileCount: -1 } })), + ).rejects.toThrow(); + }); + }); + + describe('institute_profiles', () => { + let c: string; + + beforeAll(async () => { + c = (await createTenant(app)).id; + await withTenant(app, a, (tx) => + tx.instituteProfile.create({ data: { tenantId: a, nameBn: 'শাপলা উচ্চ বিদ্যালয়' } }), + ); + }); + + it("another institute cannot read, change or write A's profile", async () => { + await withTenant(app, b, async (tx) => { + expect(await tx.instituteProfile.findMany()).toEqual([]); + expect((await tx.instituteProfile.updateMany({ data: { nameEn: 'X' } })).count).toBe(0); + }); + await expect( + withTenant(app, b, (tx) => + tx.instituteProfile.create({ data: { tenantId: c, nameEn: 'C' } }), + ), + ).rejects.toThrow(); + }); + + it('one per institute, never deleted', async () => { + await expect( + withTenant(app, a, (tx) => + tx.instituteProfile.create({ data: { tenantId: a, nameEn: 'Again' } }), + ), + ).rejects.toThrow(); + await expect( + withTenant(app, a, (tx) => tx.$executeRaw`DELETE FROM institute_profiles`), + ).rejects.toThrow(/permission denied/); + }); + + it.each([ + ['no name', { nameBn: null, nameEn: null }], + ['a 5-digit EIIN', { eiin: '12345' }], + ['letters in the EIIN', { eiin: '12345a' }], + ['letters in the phone', { phone: 'abc12345' }], + ['a 4-digit phone', { phone: '1234' }], + ['an e-mail without a domain', { email: 'x@' }], + ['an ftp website', { website: 'ftp://example.com' }], + ['year 1700', { establishedYear: 1700 }], + ['a 31-character short name', { shortName: 'x'.repeat(31) }], + ])('refuses %s', async (_name, data) => { + await expect( + withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data })), + ).rejects.toThrow(); + }); + + it('accepts a full, valid profile', async () => { + const n = await withTenant(app, a, (tx) => + tx.instituteProfile.updateMany({ + data: { + nameEn: 'Shapla High School', + shortName: 'SHS', + eiin: '108123', + phone: '+8801711000000', + email: 'office@shapla.edu.bd', + website: 'https://shapla.edu.bd', + establishedYear: 1965, + headTitleBn: 'প্রধান শিক্ষক', + headNameEn: 'Md. Rahim', + }, + }), + ); + expect(n.count).toBe(1); + }); + + it("cannot point at another institute's file; a file in use cannot be deleted", async () => { + const bLogo = await putFile(b, 'LOGO', 'image/png', 100); + await expect( + withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { logoFileId: bLogo } })), + ).rejects.toThrow(); + const aLogo = await putFile(a, 'LOGO', 'image/png', 100); + await withTenant(app, a, (tx) => + tx.instituteProfile.updateMany({ data: { logoFileId: aLogo } }), + ); + await expect( + withTenant(app, a, (tx) => + tx.storedFile.delete({ where: { id: aLogo }, select: { id: true } }), + ), + ).rejects.toThrow(); + // One file is used in one place only. + await expect( + withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { sealFileId: aLogo } })), + ).rejects.toThrow(); + }); + }); + + describe('students.photo_file_id', () => { + it("cannot point at another institute's file, and two students cannot share one", async () => { + const { student } = await createStudent(app, a, 'P-1'); + const { student: other } = await createStudent(app, a, 'P-2'); + const bPhoto = await putFile(b); + await expect( + withTenant(app, a, (tx) => + tx.student.update({ + where: { id: student.id }, + data: { photoFileId: bPhoto }, + select: { id: true }, + }), + ), + ).rejects.toThrow(); + const photo = await putFile(a); + await withTenant(app, a, (tx) => + tx.student.update({ + where: { id: student.id }, + data: { photoFileId: photo }, + select: { id: true }, + }), + ); + await expect( + withTenant(app, a, (tx) => + tx.student.update({ + where: { id: other.id }, + data: { photoFileId: photo }, + select: { id: true }, + }), + ), + ).rejects.toThrow(); + await expect( + withTenant(app, a, (tx) => + tx.storedFile.delete({ where: { id: photo }, select: { id: true } }), + ), + ).rejects.toThrow(); + }); + + it('students.photo_url is gone (never written; replaced by photo_file_id)', async () => { + const cols = await app.$queryRaw<{ column_name: string }[]>` + SELECT column_name FROM information_schema.columns + WHERE table_name = 'students' AND column_name LIKE 'photo%' ORDER BY 1`; + expect(cols.map((c) => c.column_name)).toEqual(['photo_file_id']); + }); + }); +}); diff --git a/packages/db/test/schema-safety.test.ts b/packages/db/test/schema-safety.test.ts index cca5388..9465ed0 100644 --- a/packages/db/test/schema-safety.test.ts +++ b/packages/db/test/schema-safety.test.ts @@ -68,6 +68,9 @@ describe('schema safety net', () => { 'device_punches', 'device_source_ips', 'staff_attendance_days', + 'stored_files', + 'stored_file_usage', + 'institute_profiles', ]), ); expect(tables.length).toBeGreaterThanOrEqual(18); From 687a83bb70cfbc2b03029f7f364af2c21ea34f45 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:09:23 +0600 Subject: [PATCH 08/44] CORS_ORIGINS is normalised in env.ts as browsers send Origin (lower-case host, no trailing slash, no default port), as PLATFORM_ORIGINS already was, so the CORS middleware (an exact match) allows what the production check passed. Before, an upper-case or slash-ended entry passed start-up and every preflight from it failed (P0 review leftover). An entry that is not an origin stays as written: it matches nothing and production refuses it, as before Co-Authored-By: Claude Opus 5.5 --- apps/api/src/config/env.ts | 10 ++++++-- apps/api/src/config/production-env.spec.ts | 30 ++++++++++++++++++++++ apps/api/src/config/production-env.ts | 2 +- docs/auth.md | 2 +- 4 files changed, 40 insertions(+), 4 deletions(-) diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts index 7ee964a..a471784 100644 --- a/apps/api/src/config/env.ts +++ b/apps/api/src/config/env.ts @@ -26,7 +26,12 @@ export const envSchema = z .object({ NODE_ENV: z.enum(['development', 'test', 'production']).default('development'), API_PORT: z.coerce.number().int().positive().default(4000), - /** Comma-separated allowlist of browser origins (credentials are allowed). */ + /** + * Comma-separated allowlist of browser origins (credentials are allowed). Normalised as + * browsers send `Origin` (lower-case host, no trailing slash, no default port), so the CORS + * check (an exact match) allows what the production check passed. An entry that is not an + * origin stays as written: it matches nothing, and production refuses it. + */ CORS_ORIGINS: z .string() .default('http://localhost:3000') @@ -34,7 +39,8 @@ export const envSchema = z v .split(',') .map((o) => o.trim()) - .filter(Boolean), + .filter(Boolean) + .map((o) => normaliseOrigin(o) ?? o), ), /** * The platform web app's origins (comma-separated): the only browser origins /platform/* diff --git a/apps/api/src/config/production-env.spec.ts b/apps/api/src/config/production-env.spec.ts index 807884e..ef59ace 100644 --- a/apps/api/src/config/production-env.spec.ts +++ b/apps/api/src/config/production-env.spec.ts @@ -1,6 +1,7 @@ import { readFileSync } from 'node:fs'; import path from 'node:path'; import { envSchema, validateEnv } from './env.js'; +import { isAllowedOrigin } from './dev-lan.js'; import { validateIngestEnv } from './ingest-env.js'; import { API_ONLY_SECRETS, @@ -169,6 +170,35 @@ describe('production env: the API and the worker', () => { expect(apiError({ ...api, PLATFORM_ORIGINS: 'https://PLATFORM.jantrik.com.bd/' })).toBe(''); }); + it('normalises CORS_ORIGINS too, so the CORS middleware allows what the start-up check passed', () => { + const dev = { + DATABASE_URL: 'postgresql://jantrik_app:x@localhost:5432/jantrik', + DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:x@localhost:5432/jantrik', + DATABASE_INGEST_URL: 'postgresql://jantrik_ingest_app:x@localhost:5432/jantrik', + JWT_ACCESS_SECRET: 'x'.repeat(40), + OTP_PEPPER: 'y'.repeat(40), + }; + const parsed = envSchema.parse({ + ...dev, + CORS_ORIGINS: 'HTTPS://App.Jantrik.com.bd/ , http://localhost:3000/,https://a.example.com:443', + }); + expect(parsed.CORS_ORIGINS).toEqual([ + 'https://app.jantrik.com.bd', + 'http://localhost:3000', + 'https://a.example.com', + ]); + // The browser sends the normalised form; the middleware's check is an exact match. + expect(isAllowedOrigin('https://app.jantrik.com.bd', parsed)).toBe(true); + // An entry that is not an origin stays as written (production refuses it, see above). + expect(envSchema.parse({ ...dev, CORS_ORIGINS: '*,app.jantrik.com.bd' }).CORS_ORIGINS).toEqual( + ['*', 'app.jantrik.com.bd'], + ); + // Production: an upper-case, slash-ended entry passes the check and is allowed by the middleware. + const prod = { ...api, CORS_ORIGINS: 'https://APP.jantrik.com.bd/,https://platform.jantrik.com.bd' }; + expect(apiError(prod)).toBe(''); + expect(envSchema.parse(prod).CORS_ORIGINS).toContain('https://app.jantrik.com.bd'); + }); + it('refuses secrets shorter than 32 characters', () => { for (const key of ['JWT_ACCESS_SECRET', 'OTP_PEPPER', 'PLATFORM_TOTP_KEY']) { expect(apiError({ ...api, [key]: 'k'.repeat(31) })).toMatch(new RegExp(key)); diff --git a/apps/api/src/config/production-env.ts b/apps/api/src/config/production-env.ts index 88f98fc..293528e 100644 --- a/apps/api/src/config/production-env.ts +++ b/apps/api/src/config/production-env.ts @@ -237,7 +237,7 @@ export function apiProductionProblems(env: ApiProductionEnv): EnvProblem[] { "PLATFORM_ORIGINS must list the platform's web origin (https://platform.)", ); } - const cors = new Set(env.CORS_ORIGINS.map((o) => normaliseOrigin(o) ?? o)); + const cors = new Set(env.CORS_ORIGINS); // normalised by env.ts, as PLATFORM_ORIGINS for (const origin of env.PLATFORM_ORIGINS) { const why = unsafeOrigin(origin); if (why) { diff --git a/docs/auth.md b/docs/auth.md index f3cbdc1..00b9ff5 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -454,7 +454,7 @@ Code: [`apps/web/src/lib/auth/auth-client.ts`](../apps/web/src/lib/auth/auth-cli | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `JWT_ACCESS_SECRET` | at least 32 characters | | `OTP_PEPPER` | at least 32 characters | -| `CORS_ORIGINS` | comma-separated allowlist; browsers may cache a preflight's answer for 2 h (`maxAge` in `app.setup.ts`), so a narrower list reaches open tabs up to 2 h later | +| `CORS_ORIGINS` | comma-separated allowlist, normalised like `Origin` (lower-case host, no trailing slash or default port); browsers may cache a preflight's answer for 2 h (`maxAge` in `app.setup.ts`), so a narrower list reaches open tabs up to 2 h later | | `PLATFORM_ORIGINS` | the platform web app's origins: the only ones `/platform/*` answers (each also in `CORS_ORIGINS`); default `http://localhost:3000`, required in production | | `COOKIE_SECURE` | Secure flag on the refresh cookie | | `TRUST_PROXY` | Express `trust proxy`; set it behind a load balancer so client IPs are right | From ff8981cb1d1c9e618a72c1c852bca6bf8f9fe088 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:10:30 +0600 Subject: [PATCH 09/44] Shared file caps, types and the institute profile schema (P2 task 2): FILE_LIMITS per kind equal to the database CHECKs, the 5 MB upload and 50 megapixel limits, FileRef and InstituteProfile; the schema accepts Bangla digits (EIIN, phone, year), stores a mobile as E.164 and a landline as digits, and adds https:// to a bare website Co-Authored-By: Claude Opus 5.5 --- packages/shared/src/files-schema.ts | 86 ++++++++++++++++++++ packages/shared/src/files.test.ts | 83 +++++++++++++++++++ packages/shared/src/files.ts | 121 ++++++++++++++++++++++++++++ packages/shared/src/index.ts | 2 + 4 files changed, 292 insertions(+) create mode 100644 packages/shared/src/files-schema.ts create mode 100644 packages/shared/src/files.test.ts create mode 100644 packages/shared/src/files.ts diff --git a/packages/shared/src/files-schema.ts b/packages/shared/src/files-schema.ts new file mode 100644 index 0000000..e84fd84 --- /dev/null +++ b/packages/shared/src/files-schema.ts @@ -0,0 +1,86 @@ +import { z } from 'zod'; +import { toAsciiDigits } from './digits.js'; +import { INSTITUTE_PROFILE_LIMITS as L } from './files.js'; +import { normalizeBdPhone } from './phone.js'; + +// PUT /institute/profile (sprint 1 P2). Each rule matches a CHECK on institute_profiles, so a +// value the schema accepts is never refused by the database. + +const text = (max: number) => + z + .string() + .trim() + .max(max) + .nullish() + .transform((v) => v || null); + +/** Bangla digits and spaces accepted; empty → null. */ +const digitsText = z + .string() + .nullish() + .transform((v) => (v ? toAsciiDigits(v).replace(/\s/g, '') : '') || null); + +/** A mobile is stored as E.164; anything else as its digits (a landline), with an optional +. */ +export function normalizeInstitutePhone(input: string): string { + return ( + normalizeBdPhone(input) ?? + toAsciiDigits(input) + .trim() + .replace(/[\s\-().]/g, '') + ); +} + +/** `shapla.edu.bd` → `https://shapla.edu.bd`; a given http(s) scheme is kept. */ +export function normalizeWebsite(input: string): string { + const v = input.trim(); + return /^[a-z][a-z0-9+.-]*:/i.test(v) ? v : `https://${v}`; +} + +export const instituteProfileSchema = z + .object({ + nameBn: text(L.name), + nameEn: text(L.name), + shortName: text(L.shortName), + eiin: digitsText.refine((v) => v === null || /^\d{6}$/.test(v), 'EIIN is 6 digits'), + addressBn: text(L.address), + addressEn: text(L.address), + phone: z + .string() + .nullish() + .transform((v) => (v?.trim() ? normalizeInstitutePhone(v) : null)) + .refine((v) => v === null || /^\+?\d{5,15}$/.test(v), 'A phone number of 5-15 digits'), + email: text(L.email).refine( + (v) => v === null || /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v), + 'An e-mail address', + ), + website: z + .string() + .nullish() + .transform((v) => (v?.trim() ? normalizeWebsite(v) : null)) + .refine( + (v) => v === null || (v.length <= L.website && /^https?:\/\/\S+$/i.test(v)), + 'A web address (http or https)', + ), + headTitleBn: text(L.headTitle), + headTitleEn: text(L.headTitle), + headNameBn: text(L.headName), + headNameEn: text(L.headName), + establishedYear: z + .union([z.number(), z.string()]) + .nullish() + .transform((v) => { + if (v === null || v === undefined) return null; + const s = toAsciiDigits(String(v)).trim(); + return s === '' ? null : Number(s); + }) + .refine( + (v) => v === null || (Number.isInteger(v) && v >= L.yearMin && v <= L.yearMax), + 'A year between 1800 and 2100', + ), + }) + .refine((p) => p.nameBn !== null || p.nameEn !== null, { + message: 'A name in Bangla or English is required', + path: ['nameBn'], + }); + +export type InstituteProfileInput = z.input; diff --git a/packages/shared/src/files.test.ts b/packages/shared/src/files.test.ts new file mode 100644 index 0000000..ac58259 --- /dev/null +++ b/packages/shared/src/files.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it } from 'vitest'; +import { FILE_LIMITS, STORED_FILE_KINDS, UPLOAD_MAX_BYTES } from './files.js'; +import { + instituteProfileSchema, + normalizeInstitutePhone, + normalizeWebsite, +} from './files-schema.js'; + +describe('file limits (docs/files.md, the stored_files CHECKs)', () => { + it('has a limit for every kind, equal to the database caps', () => { + expect(Object.keys(FILE_LIMITS).sort()).toEqual([...STORED_FILE_KINDS].sort()); + expect(FILE_LIMITS.STUDENT_PHOTO.maxBytes).toBe(204_800); + expect(FILE_LIMITS.APPLICANT_PHOTO.maxBytes).toBe(204_800); + expect(FILE_LIMITS.LOGO.maxBytes).toBe(102_400); + expect(FILE_LIMITS.SEAL.maxBytes).toBe(102_400); + expect(FILE_LIMITS.SIGNATURE.maxBytes).toBe(102_400); + expect(FILE_LIMITS.DOCUMENT_ASSET.maxBytes).toBe(262_144); + expect(FILE_LIMITS.STUDENT_PHOTO.mimes).toEqual(['image/jpeg']); + expect(FILE_LIMITS.SIGNATURE.mimes).toEqual(['image/png']); + expect(UPLOAD_MAX_BYTES).toBe(5 * 1024 * 1024); + }); +}); + +describe('instituteProfileSchema', () => { + const parse = (v: Record) => + instituteProfileSchema.safeParse({ nameBn: 'শাপলা', ...v }); + + it('trims, turns empty strings into null, and needs one name', () => { + const r = instituteProfileSchema.parse({ + nameBn: ' শাপলা উচ্চ বিদ্যালয় ', + nameEn: '', + eiin: '', + }); + expect(r).toMatchObject({ + nameBn: 'শাপলা উচ্চ বিদ্যালয়', + nameEn: null, + eiin: null, + phone: null, + }); + expect(instituteProfileSchema.safeParse({ nameBn: ' ', nameEn: '' }).success).toBe(false); + }); + + it('accepts Bangla digits in the EIIN, the phone and the year', () => { + const r = instituteProfileSchema.parse({ + nameEn: 'Shapla', + eiin: '১০৮ ১২৩', + phone: '০১৭১১-০০০০০০', + establishedYear: '১৯৬৫', + }); + expect(r).toMatchObject({ eiin: '108123', phone: '+8801711000000', establishedYear: 1965 }); + }); + + it.each([ + ['01711000000', '+8801711000000'], + ['+880 1711-000000', '+8801711000000'], + ['02-9123456', '029123456'], + ['(031) 712 345', '031712345'], + ])('stores the phone %s as %s', (typed, stored) => { + expect(normalizeInstitutePhone(typed)).toBe(stored); + expect(parse({ phone: typed }).success).toBe(true); + }); + + it.each([ + ['a 5-digit EIIN', { eiin: '12345' }], + ['letters in the EIIN', { eiin: '1081a3' }], + ['a 4-digit phone', { phone: '1234' }], + ['letters in the phone', { phone: 'call me' }], + ['an e-mail without a domain', { email: 'office@' }], + ['an ftp website', { website: 'ftp://shapla.edu.bd' }], + ['year 1700', { establishedYear: 1700 }], + ['year 2101', { establishedYear: '2101' }], + ['a 31-character short name', { shortName: 'x'.repeat(31) }], + ['a 201-character name', { nameBn: 'ক'.repeat(201) }], + ])('refuses %s (as the database CHECK would)', (_name, v) => { + expect(parse(v).success).toBe(false); + }); + + it('adds https:// to a bare website and keeps a given scheme', () => { + expect(normalizeWebsite('shapla.edu.bd')).toBe('https://shapla.edu.bd'); + expect(normalizeWebsite('http://shapla.edu.bd')).toBe('http://shapla.edu.bd'); + expect(parse({ website: 'shapla.edu.bd' }).data?.website).toBe('https://shapla.edu.bd'); + }); +}); diff --git a/packages/shared/src/files.ts b/packages/shared/src/files.ts new file mode 100644 index 0000000..3a8dd4e --- /dev/null +++ b/packages/shared/src/files.ts @@ -0,0 +1,121 @@ +// Stored images (sprint 1 P2, docs/files.md): the kinds, their caps and the API's shapes. No zod +// here: the web imports these; the input schema is in files-schema.ts. + +export const STORED_FILE_KINDS = [ + 'STUDENT_PHOTO', + 'APPLICANT_PHOTO', + 'LOGO', + 'SIGNATURE', + 'SEAL', + 'DOCUMENT_ASSET', +] as const; +export type StoredFileKind = (typeof STORED_FILE_KINDS)[number]; + +export type StoredMime = 'image/jpeg' | 'image/png' | 'image/webp'; + +export interface FileLimit { + /** Stored size cap in bytes (the database CHECK stored_files_size has the same numbers). */ + maxBytes: number; + /** The box the image is shrunk to fit (never enlarged); null: no resize (P8's assets). */ + box: { width: number; height: number } | null; + /** Formats stored for this kind, preferred first (CHECK stored_files_mime). */ + mimes: readonly StoredMime[]; +} + +/** Per kind, what the server stores after re-encoding the upload (decision S7). */ +export const FILE_LIMITS: Record = { + STUDENT_PHOTO: { maxBytes: 200 * 1024, box: { width: 600, height: 800 }, mimes: ['image/jpeg'] }, + APPLICANT_PHOTO: { + maxBytes: 200 * 1024, + box: { width: 600, height: 800 }, + mimes: ['image/jpeg'], + }, + LOGO: { + maxBytes: 100 * 1024, + box: { width: 512, height: 512 }, + mimes: ['image/png', 'image/webp'], + }, + SEAL: { + maxBytes: 100 * 1024, + box: { width: 512, height: 512 }, + mimes: ['image/png', 'image/webp'], + }, + SIGNATURE: { maxBytes: 100 * 1024, box: { width: 600, height: 240 }, mimes: ['image/png'] }, + DOCUMENT_ASSET: { + maxBytes: 256 * 1024, + box: null, + mimes: ['image/jpeg', 'image/png', 'image/webp'], + }, +}; + +/** The largest upload the API reads (multer `fileSize`); the web checks it before sending. */ +export const UPLOAD_MAX_BYTES = 5 * 1024 * 1024; +/** Decoded pixels allowed (sharp `limitInputPixels`): a 48 MP phone photo fits, a bomb does not. */ +export const UPLOAD_MAX_PIXELS = 50_000_000; +/** What the file picker offers (the server decides by content, not by this). */ +export const UPLOAD_ACCEPT = 'image/jpeg,image/png,image/webp'; + +/** The institute profile's three images, by their route name. */ +export const INSTITUTE_IMAGE_SLOTS = ['logo', 'signature', 'seal'] as const; +export type InstituteImageSlot = (typeof INSTITUTE_IMAGE_SLOTS)[number]; +export const INSTITUTE_IMAGE_KIND: Record = { + logo: 'LOGO', + signature: 'SIGNATURE', + seal: 'SEAL', +}; + +/** A stored image as the API describes it (never its bytes; those come from an entity route). */ +export interface FileRef { + /** The stored file's id: also the web's cache key (a replaced image has a new id). */ + id: string; + mime: StoredMime; + sizeBytes: number; + width: number; + height: number; +} + +/** The text fields of the institute profile (PUT /institute/profile). */ +export interface InstituteProfileFields { + nameBn: string | null; + nameEn: string | null; + shortName: string | null; + /** BANBEIS EIIN: 6 ASCII digits. */ + eiin: string | null; + addressBn: string | null; + addressEn: string | null; + /** A mobile as E.164, or a landline as ASCII digits (optional leading +). */ + phone: string | null; + email: string | null; + website: string | null; + headTitleBn: string | null; + headTitleEn: string | null; + headNameBn: string | null; + headNameEn: string | null; + establishedYear: number | null; +} + +/** GET /institute/profile. */ +export interface InstituteProfile extends InstituteProfileFields { + /** False until the first save or image: the fields are then empty. */ + saved: boolean; + /** The name the platform registered (tenants.name), to pre-fill a new profile. */ + registeredName: string; + logo: FileRef | null; + signature: FileRef | null; + seal: FileRef | null; + /** This institute's stored images in total, and its cap (FILE_STORAGE_PER_TENANT_MB). */ + storage: { bytesUsed: number; capBytes: number }; +} + +/** Field limits shared by the schema and the form (the CHECKs on institute_profiles). */ +export const INSTITUTE_PROFILE_LIMITS = { + name: 200, + shortName: 30, + address: 300, + headTitle: 60, + headName: 100, + email: 254, + website: 200, + yearMin: 1800, + yearMax: 2100, +} as const; diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 9a4559f..0a004c9 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -47,3 +47,5 @@ export * from './staff-attendance-api.js'; export * from './staff-attendance-schema.js'; export * from './password.js'; export * from './password-schema.js'; +export * from './files.js'; +export * from './files-schema.js'; From 917d5ebe2d51a455bc97c1a28134fb5a20a1d54d Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:14:18 +0600 Subject: [PATCH 10/44] The start-up login check also refuses a login with REPLICATION (a replication connection streams every row, whatever RLS says) or CREATEROLE (no runtime login needs it; create-roles.sh already refuses both for the roles it makes), and a login that can become a role with either (P0 review leftover). Tested against real roles made by the superuser, and in the API, platform and receiver services' start-up Co-Authored-By: Claude Opus 5.5 --- .../src/ingest/ingest-prisma.service.spec.ts | 4 +++ .../platform/platform-prisma.service.spec.ts | 4 +++ apps/api/src/prisma/prisma.service.spec.ts | 13 +++++++ docs/database.md | 7 ++-- docs/deploy.md | 4 +-- docs/devices.md | 3 +- packages/db/src/login-privileges.ts | 31 ++++++++++++++--- packages/db/test/login-privileges.test.ts | 34 +++++++++++++++++-- 8 files changed, 87 insertions(+), 13 deletions(-) diff --git a/apps/api/src/ingest/ingest-prisma.service.spec.ts b/apps/api/src/ingest/ingest-prisma.service.spec.ts index 38b3685..e7a0d4e 100644 --- a/apps/api/src/ingest/ingest-prisma.service.spec.ts +++ b/apps/api/src/ingest/ingest-prisma.service.spec.ts @@ -29,6 +29,8 @@ const SAFE: LoginPrivileges = { login: 'jantrik_ingest_app', superuser: false, bypassRls: false, + replication: false, + createRole: false, canBecome: [], }; @@ -60,6 +62,8 @@ function serviceWith(privileges: LoginPrivileges, ...answers: (Check | Error | t login: privileges.login, superuser: privileges.superuser, bypass_rls: privileges.bypassRls, + replication: privileges.replication, + create_role: privileges.createRole, can_become: privileges.canBecome, }, ]), diff --git a/apps/api/src/platform/platform-prisma.service.spec.ts b/apps/api/src/platform/platform-prisma.service.spec.ts index 9497812..7540799 100644 --- a/apps/api/src/platform/platform-prisma.service.spec.ts +++ b/apps/api/src/platform/platform-prisma.service.spec.ts @@ -5,6 +5,8 @@ const SAFE: LoginPrivileges = { login: 'jantrik_platform_app', superuser: false, bypassRls: false, + replication: false, + createRole: false, canBecome: [], }; @@ -13,6 +15,8 @@ const privilegeRow = (p: LoginPrivileges) => ({ login: p.login, superuser: p.superuser, bypass_rls: p.bypassRls, + replication: p.replication, + create_role: p.createRole, can_become: p.canBecome, }); diff --git a/apps/api/src/prisma/prisma.service.spec.ts b/apps/api/src/prisma/prisma.service.spec.ts index c3fdb98..80fb6a6 100644 --- a/apps/api/src/prisma/prisma.service.spec.ts +++ b/apps/api/src/prisma/prisma.service.spec.ts @@ -8,6 +8,8 @@ const SAFE: LoginPrivileges = { login: 'jantrik_app', superuser: false, bypassRls: false, + replication: false, + createRole: false, canBecome: [], }; @@ -31,6 +33,8 @@ function service(...answers: (LoginPrivileges | Error)[]) { login: a.login, superuser: a.superuser, bypass_rls: a.bypassRls, + replication: a.replication, + create_role: a.createRole, can_become: a.canBecome, }, ]), @@ -63,6 +67,15 @@ describe('PrismaService startup check', () => { ); }); + it('refuses a login with REPLICATION or CREATEROLE', async () => { + await expect(service({ ...SAFE, replication: true }).s.onModuleInit()).rejects.toThrow( + /DATABASE_URL.*has REPLICATION/, + ); + await expect(service({ ...SAFE, createRole: true }).s.onModuleInit()).rejects.toThrow( + /DATABASE_URL.*has CREATEROLE/, + ); + }); + it('refuses a login that can become a BYPASSRLS role', async () => { await expect( service({ ...SAFE, canBecome: ['admin_bypass'] }).s.onModuleInit(), diff --git a/docs/database.md b/docs/database.md index 936ba88..d56a87c 100644 --- a/docs/database.md +++ b/docs/database.md @@ -39,9 +39,10 @@ the template. **Every running service checks its login at start-up** (`readLoginPrivileges` in [`packages/db/src/login-privileges.ts`](../packages/db/src/login-privileges.ts)): the API and the worker (`jantrik_app`), the platform module (`jantrik_platform_app`) and the receiver -(`jantrik_ingest_app`) refuse to start when their login is a superuser, has BYPASSRLS, or can -become (`pg_has_role(…, 'MEMBER')`) a role that is either, or `pg_read_all_data`, -`pg_write_all_data` or one of the server file and program roles. The check fails closed: while the +(`jantrik_ingest_app`) refuse to start when their login is a superuser, has BYPASSRLS, +REPLICATION (a replication connection streams every row, whatever RLS says) or CREATEROLE (no +runtime login needs it), or can become (`pg_has_role(…, 'MEMBER')`) a role that has any of these, +or `pg_read_all_data`, `pg_write_all_data` or one of the server file and program roles. The check fails closed: while the database does not answer, it is asked again for about 3 minutes, then the service exits. The roles and databases (`jantrik`, `jantrik_test`) are created by diff --git a/docs/deploy.md b/docs/deploy.md index e4744f3..71e9a89 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -172,8 +172,8 @@ The device receiver refuses: Beyond these, every service checks its database login at start-up, against the database itself: -- **No login may be a superuser, have BYPASSRLS, or be able to become such a role** (nor - `pg_read_all_data`, `pg_write_all_data` or the server file and program roles): the API and the +- **No login may be a superuser, have BYPASSRLS, REPLICATION or CREATEROLE, or be able to become + such a role** (nor `pg_read_all_data`, `pg_write_all_data` or the server file and program roles): the API and the worker (`DATABASE_URL`), the platform module (`DATABASE_PLATFORM_URL`) and the receiver (`DATABASE_INGEST_URL`). Fail closed: while the database does not answer, the check is asked again for about 3 minutes, then the service exits ([database.md](database.md) → Database roles). diff --git a/docs/devices.md b/docs/devices.md index 1381efe..7a8cb46 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -169,7 +169,8 @@ screen. Devices that support HTTPS can use a TLS proxy in front of the receiver' ([deploy.md](deploy.md) → Redis users). - **Startup check.** The receiver refuses to start unless its login can run `ingest_resolve`, cannot read `students` or `device_punches` (so `DATABASE_URL` pasted by mistake fails), runs - with the 5 s statement limit, and is not a superuser, BYPASSRLS or able to become such a role + with the 5 s statement limit, and is not a superuser, BYPASSRLS, REPLICATION or CREATEROLE, nor + able to become such a role (the same check as the API's logins, [database.md](database.md) → Database roles): a check that answers otherwise stops the start at once. A check that fails (the database not reachable yet, or not migrated yet, e.g. 42501: the e2e run starts the API before its global setup diff --git a/packages/db/src/login-privileges.ts b/packages/db/src/login-privileges.ts index 1be77b0..e1ae81d 100644 --- a/packages/db/src/login-privileges.ts +++ b/packages/db/src/login-privileges.ts @@ -19,9 +19,14 @@ export interface LoginPrivileges { login: string; superuser: boolean; bypassRls: boolean; + /** It may open replication connections, which stream every row whatever RLS says. */ + replication: boolean; + /** It may create roles; no runtime login needs that (create-roles.sh refuses it too). */ + createRole: boolean; /** * Other roles the login is a member of (it can SET ROLE to them, or inherits them) that are - * superusers, bypass RLS, or are one of PRIVILEGED_PREDEFINED_ROLES. + * superusers, bypass RLS, have REPLICATION or CREATEROLE, or are one of + * PRIVILEGED_PREDEFINED_ROLES. */ canBecome: string[]; } @@ -35,23 +40,34 @@ export interface LoginPrivileges { export async function readLoginPrivileges(client: PrismaClient): Promise { const roles = [...PRIVILEGED_PREDEFINED_ROLES]; const [row] = await client.$queryRaw< - { login: string; superuser: boolean; bypass_rls: boolean; can_become: string[] }[] + { + login: string; + superuser: boolean; + bypass_rls: boolean; + replication: boolean; + create_role: boolean; + can_become: string[]; + }[] >` SELECT session_user::text AS login, r.rolsuper AS superuser, r.rolbypassrls AS bypass_rls, + r.rolreplication AS replication, r.rolcreaterole AS create_role, COALESCE(array_agg(o.rolname::text ORDER BY o.rolname) FILTER (WHERE o.rolname IS NOT NULL), '{}') AS can_become FROM pg_roles r LEFT JOIN pg_roles o ON o.rolname <> session_user - AND (o.rolsuper OR o.rolbypassrls OR o.rolname::text = ANY (${roles}::text[])) + AND (o.rolsuper OR o.rolbypassrls OR o.rolreplication OR o.rolcreaterole + OR o.rolname::text = ANY (${roles}::text[])) AND pg_has_role(session_user, o.oid, 'MEMBER') WHERE r.rolname = session_user - GROUP BY r.rolsuper, r.rolbypassrls`; + GROUP BY r.rolsuper, r.rolbypassrls, r.rolreplication, r.rolcreaterole`; if (!row) throw new Error('The login has no pg_roles row'); return { login: row.login, superuser: row.superuser, bypassRls: row.bypass_rls, + replication: row.replication, + createRole: row.create_role, canBecome: row.can_become, }; } @@ -62,5 +78,10 @@ export async function readLoginPrivileges(client: PrismaClient): Promise `can become ${r}`)]; + return [ + ...(p.bypassRls ? ['has BYPASSRLS'] : []), + ...(p.replication ? ['has REPLICATION'] : []), + ...(p.createRole ? ['has CREATEROLE'] : []), + ...p.canBecome.map((r) => `can become ${r}`), + ]; } diff --git a/packages/db/test/login-privileges.test.ts b/packages/db/test/login-privileges.test.ts index 5080c07..b12b65b 100644 --- a/packages/db/test/login-privileges.test.ts +++ b/packages/db/test/login-privileges.test.ts @@ -10,8 +10,8 @@ import { import { APP_URL, INGEST_URL, OWNER_URL, PLATFORM_URL, superuserUrl } from './env.js'; // Every running service checks its database login at start-up and refuses one that is a -// superuser, bypasses RLS, or can become a role that does (or one of the pg_* roles that pass -// every grant). These tests make such roles as the superuser and drop them afterwards. +// superuser, bypasses RLS, has REPLICATION or CREATEROLE, or can become a role that does (or one +// of the pg_* roles that pass every grant). These tests make such roles as the superuser and drop them afterwards. async function withClient(url: string, fn: (c: PrismaClient) => Promise): Promise { const client = createPrismaClient(url); @@ -111,6 +111,26 @@ describe('login privileges', () => { expect(loginPrivilegeProblems(p)).toEqual(['is a superuser']); }); + it('refuses a login with REPLICATION (it can stream every row, RLS or not)', async () => { + const p = await withClient(await tempLogin('REPLICATION'), readLoginPrivileges); + expect(p.replication).toBe(true); + expect(loginPrivilegeProblems(p)).toEqual(['has REPLICATION']); + }); + + it('refuses a login with CREATEROLE (no runtime login needs it)', async () => { + const p = await withClient(await tempLogin('CREATEROLE'), readLoginPrivileges); + expect(p.createRole).toBe(true); + expect(loginPrivilegeProblems(p)).toEqual(['has CREATEROLE']); + }); + + it('refuses a login that can become a REPLICATION or CREATEROLE role', async () => { + for (const attribute of ['REPLICATION', 'CREATEROLE']) { + const role = await tempRole(`NOLOGIN ${attribute}`); + const p = await withClient(await tempLogin('', { member: role }), readLoginPrivileges); + expect(loginPrivilegeProblems(p)).toEqual([`can become ${role}`]); + } + }); + it('refuses a login that can become pg_read_all_data', async () => { const url = await tempLogin('', { member: 'pg_read_all_data' }); const p = await withClient(url, readLoginPrivileges); @@ -123,6 +143,8 @@ describe('loginPrivilegeProblems', () => { login: 'jantrik_app', superuser: false, bypassRls: false, + replication: false, + createRole: false, canBecome: [], }; @@ -138,6 +160,14 @@ describe('loginPrivilegeProblems', () => { ]); }); + it('lists REPLICATION and CREATEROLE', () => { + expect(loginPrivilegeProblems({ ...safe, replication: true })).toEqual(['has REPLICATION']); + expect(loginPrivilegeProblems({ ...safe, createRole: true })).toEqual(['has CREATEROLE']); + expect( + loginPrivilegeProblems({ ...safe, bypassRls: true, replication: true, createRole: true }), + ).toEqual(['has BYPASSRLS', 'has REPLICATION', 'has CREATEROLE']); + }); + it('says only "is a superuser" for a superuser (it can become every role anyway)', () => { expect( loginPrivilegeProblems({ ...safe, superuser: true, bypassRls: true, canBecome: ['x'] }), From bc6644be9213847180899148a4647201f8a19dde Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:15:24 +0600 Subject: [PATCH 11/44] Password login without the hash (P1-J): the API hashes the typed password with the stored hash's parameters and salt and the database compares the SHA-256 (auth_my_password_matches, as the user). Always one argon2 hash at today's cost and one comparison, with a dummy salt and the nil user when there is no account, no password or unusable parameters (argon2id v19 only; at most 64 MiB, 10 passes, 4 lanes), so timing still reveals nothing Co-Authored-By: Claude Opus 5.5 --- apps/api/src/auth/auth.service.ts | 8 +- apps/api/src/auth/login-lookup.ts | 29 ++++++- apps/api/src/auth/password.service.spec.ts | 88 ++++++++++++++++++++++ apps/api/src/auth/password.service.ts | 63 +++++++++++++++- 4 files changed, 181 insertions(+), 7 deletions(-) create mode 100644 apps/api/src/auth/password.service.spec.ts diff --git a/apps/api/src/auth/auth.service.ts b/apps/api/src/auth/auth.service.ts index ec75be8..d21e5c7 100644 --- a/apps/api/src/auth/auth.service.ts +++ b/apps/api/src/auth/auth.service.ts @@ -19,6 +19,7 @@ import { findUserForLogin, listMemberships, listMembershipsFor, + passwordMatches, type LoginUser, } from './login-lookup.js'; import { OtpService } from './otp.service.js'; @@ -80,8 +81,11 @@ export class AuthService { ); const user = await findUserForLogin(this.prisma.client, { phone, email }); - // Always verify (against a dummy hash if needed) so timing doesn't reveal unknown accounts. - const ok = await this.passwords.verify(user?.password_hash, password); + // One argon2 hash and one comparison in the database whatever the account (a dummy hash and + // the nil user when needed), so timing doesn't reveal unknown accounts. The stored hash never + // leaves the database (P1-J). + const digest = await this.passwords.loginDigest(user?.password_params, password); + const ok = await passwordMatches(this.prisma.client, user?.id, digest); if (!user || !ok) throw invalidCredentials(); // Passwords are for staff (sprint 1 P1): an active staff membership in an open institute. // Anyone else gets the same answer as a wrong password, and it counts as a failed attempt. diff --git a/apps/api/src/auth/login-lookup.ts b/apps/api/src/auth/login-lookup.ts index 5a89856..b7bc1cb 100644 --- a/apps/api/src/auth/login-lookup.ts +++ b/apps/api/src/auth/login-lookup.ts @@ -5,7 +5,11 @@ export interface LoginUser { id: string; name: string; locale: 'bn' | 'en'; - password_hash: string | null; + /** + * The stored password hash up to its last `$` (argon2id, version, cost, salt), never its digest + * (P1-J); null without a usable password. + */ + password_params: string | null; } /** Login lookup through the SECURITY DEFINER function (users RLS hides everyone otherwise). */ @@ -14,11 +18,32 @@ export async function findUserForLogin( by: { phone?: string | null; email?: string | null }, ): Promise { const rows = await prisma.$queryRaw` - SELECT id::text, name, locale::text AS locale, password_hash + SELECT id::text, name, locale::text AS locale, password_params FROM auth_find_user_for_login(${by.phone ?? null}, ${by.email ?? null})`; return rows[0]; } +/** Stands in for "no such user", so a failed lookup runs the same queries as a real account. */ +const NO_USER = '00000000-0000-0000-0000-000000000000'; + +/** + * Whether `digest` (`PasswordService.loginDigest`) is the SHA-256 of the user's stored password + * hash. The database compares (`auth_my_password_matches`, scoped by `app.user_id`): the hash + * never reaches the API (P1-J). + */ +export async function passwordMatches( + prisma: PrismaClient, + userId: string | undefined, + digest: Buffer, +): Promise { + const rows = await withContext( + prisma, + { userId: userId ?? NO_USER }, + (tx) => tx.$queryRaw<{ ok: boolean }[]>`SELECT auth_my_password_matches(${digest}) AS ok`, + ); + return rows[0]?.ok === true; +} + interface MembershipRow { tenant_id: string; tenant_slug: string; diff --git a/apps/api/src/auth/password.service.spec.ts b/apps/api/src/auth/password.service.spec.ts new file mode 100644 index 0000000..83bffb2 --- /dev/null +++ b/apps/api/src/auth/password.service.spec.ts @@ -0,0 +1,88 @@ +import { createHash } from 'node:crypto'; +import { hash } from '@node-rs/argon2'; +import { PasswordService } from './password.service.js'; + +// Wrapped so the tests can count the hashes a login computes; the real library does the work. +vi.mock('@node-rs/argon2', async (importOriginal) => { + const real = await importOriginal(); + return { ...real, hash: vi.fn(real.hash) }; +}); + +const sha256 = (s: string): Buffer => createHash('sha256').update(s, 'utf8').digest(); +/** What the login lookup returns: the PHC string up to its last `$` (no digest). */ +const paramsOf = (phc: string): string => phc.slice(0, phc.lastIndexOf('$')); +const NO_MATCH = Buffer.alloc(32); + +describe('PasswordService.loginDigest (P1-J: the database compares, the hash never leaves it)', () => { + const service = new PasswordService(); + const password = 'correct horse battery staple'; + let stored: string; + + beforeAll(async () => { + stored = await service.hash(password); + }); + + it('is the SHA-256 of the hash that the stored parameters and salt give the password', async () => { + expect(await service.loginDigest(paramsOf(stored), password)).toEqual(sha256(stored)); + }); + + it('hashes the password NFC-normalised, as setting it did (P1-C)', async () => { + const composed = 'পাসওয়ার্ড-café-2026'; + const decomposed = composed.normalize('NFD'); + expect(decomposed).not.toBe(composed); + const storedNfc = await service.hash(composed); + expect(await service.loginDigest(paramsOf(storedNfc), decomposed)).toEqual(sha256(storedNfc)); + }); + + it('gives another digest for a wrong password', async () => { + const digest = await service.loginDigest(paramsOf(stored), `${password}!`); + expect(digest).not.toEqual(sha256(stored)); + expect(digest).toHaveLength(32); + }); + + it('follows stored parameters other than today’s, up to the ceiling', async () => { + const costly = await hash(password, { memoryCost: 65_536, timeCost: 3, parallelism: 2 }); + expect(await service.loginDigest(paramsOf(costly), password)).toEqual(sha256(costly)); + }); + + it.each([ + ['no user', undefined], + ['no password', null], + ['empty', ''], + ['not a hash', 'not-a-real-hash'], + ['argon2i', 'ALGO'], + ['version 16', 'V16'], + ['memory above 64 MiB', 'M_HIGH'], + ['more than 10 passes', 'T_HIGH'], + ['more than 4 lanes', 'P_HIGH'], + ['memory below 8 × lanes', 'M_LOW'], + ['a digest left on', 'WITH_DIGEST'], + ])('%s: hashes once with the defaults and matches nothing', async (_, kind) => { + const p = paramsOf(stored); + const params = + { + ALGO: p.replace('$argon2id$', '$argon2i$'), + V16: p.replace('$v=19$', '$v=16$'), + M_HIGH: p.replace('m=19456', 'm=65537'), + T_HIGH: p.replace('t=2', 't=11'), + P_HIGH: p.replace('p=1', 'p=5'), + M_LOW: p.replace('m=19456,t=2,p=1', 'm=15,t=2,p=2'), + WITH_DIGEST: stored, + }[kind as string] ?? kind; + vi.mocked(hash).mockClear(); + expect(await service.loginDigest(params, password)).toEqual(NO_MATCH); + // One hash at today's cost, as for a real account: the time does not tell the cases apart. + expect(vi.mocked(hash)).toHaveBeenCalledTimes(1); + expect(vi.mocked(hash).mock.calls[0]![1]).toMatchObject({ + memoryCost: 19_456, + timeCost: 2, + parallelism: 1, + }); + }); + + it('a real account also hashes exactly once', async () => { + vi.mocked(hash).mockClear(); + await service.loginDigest(paramsOf(stored), 'wrong but long password'); + expect(vi.mocked(hash)).toHaveBeenCalledTimes(1); + }); +}); diff --git a/apps/api/src/auth/password.service.ts b/apps/api/src/auth/password.service.ts index bd95223..a4ff020 100644 --- a/apps/api/src/auth/password.service.ts +++ b/apps/api/src/auth/password.service.ts @@ -1,3 +1,4 @@ +import { createHash } from 'node:crypto'; import { Injectable } from '@nestjs/common'; import { normalizePassword } from '@jantrik/shared'; import { hash, verify } from '@node-rs/argon2'; @@ -5,6 +6,42 @@ import { hash, verify } from '@node-rs/argon2'; // Argon2id (the library default) with OWASP-recommended parameters: 19 MiB, 2 iterations. const OPTIONS = { memoryCost: 19_456, timeCost: 2, parallelism: 1 }; +/** + * The most a stored hash may make one staff login spend (P1-J4): 64 MiB, 10 passes, 4 lanes. + * Hashes Jantrik writes use OPTIONS; above this a stored hash is treated as unusable. + */ +const LOGIN_COST_CEILING = { memoryCost: 65_536, timeCost: 10, parallelism: 4 }; + +/** The login lookup's `password_params`: argon2id, version 19, m, t, p and the salt (no digest). */ +const PARAMS = /^\$argon2id\$v=19\$m=(\d{1,10}),t=(\d{1,10}),p=(\d{1,3})\$([A-Za-z0-9+/]{11,64})$/; + +/** The salt of the login's dummy hash (unknown user, no password, unusable parameters). */ +const DUMMY_SALT = Buffer.from('jantrik-dummy-salt-16b').subarray(0, 16); + +/** A digest no stored hash has: what the dummy path returns. */ +const NO_MATCH = Buffer.alloc(32); + +const sha256 = (value: string): Buffer => createHash('sha256').update(value, 'utf8').digest(); + +/** argon2 options from the login lookup's parameters, or null when they are missing or unusable. */ +function loginOptions(params: string | null | undefined) { + const m = params ? PARAMS.exec(params) : null; + if (!m) return null; + const [memoryCost, timeCost, parallelism] = [m[1], m[2], m[3]].map(Number) as [ + number, + number, + number, + ]; + const usable = + timeCost >= 1 && + parallelism >= 1 && + memoryCost >= 8 * parallelism && + memoryCost <= LOGIN_COST_CEILING.memoryCost && + timeCost <= LOGIN_COST_CEILING.timeCost && + parallelism <= LOGIN_COST_CEILING.parallelism; + return usable ? { memoryCost, timeCost, parallelism, salt: Buffer.from(m[4]!, 'base64') } : null; +} + /** * Password hashing and checking, for staff and platform admins. A staff member's password is set * only by PasswordSettingsService (PUT /me/password); a platform admin's by the CLI. @@ -19,9 +56,9 @@ export class PasswordService { } /** - * Verify a password. With no stored hash (unknown user, or OTP-only account) it still runs a - * full argon2 verification against a dummy hash, so response time does not reveal whether the - * account exists. + * Verify a password against a stored hash (platform admins). With no stored hash it still runs + * a full argon2 verification against a dummy hash, so response time does not reveal whether the + * account exists. Staff logins use `loginDigest` instead: their hashes never leave the database. */ async verify(storedHash: string | null | undefined, password: string): Promise { if (!storedHash) { @@ -31,4 +68,24 @@ export class PasswordService { } return verify(storedHash, normalizePassword(password)).catch(() => false); } + + /** + * A staff login's half of the password check (P1-J): the argon2 hash of `password` under the + * stored hash's parameters and salt (the login lookup's `password_params`), as the SHA-256 the + * database compares with `auth_my_password_matches`. The stored hash never reaches the API. + * + * Always exactly one hash: with no parameters (unknown user, no password) or unusable ones, it + * hashes with today's cost and a dummy salt and returns a digest that matches nothing, so the + * time does not tell the cases apart. + */ + async loginDigest(params: string | null | undefined, password: string): Promise { + const options = loginOptions(params); + const candidate = await hash( + normalizePassword(password), + options ?? { ...OPTIONS, salt: DUMMY_SALT }, + ).catch(() => null); + // The salt must come back exactly as stored (it does for every hash this library wrote). + if (!options || !candidate?.startsWith(`${params}$`)) return NO_MATCH; + return sha256(candidate); + } } From b0e631530560dc8708d7d516a40ac73668bfadd9 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:15:24 +0600 Subject: [PATCH 12/44] GET /me/password reads hasPassword from auth_my_password_is_set() (P1-J), and the password login test reads the stored hash through the owner login Co-Authored-By: Claude Opus 5.5 --- apps/api/src/auth/password-settings.service.ts | 7 +++++-- apps/api/test/password.e2e-spec.ts | 15 +++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/apps/api/src/auth/password-settings.service.ts b/apps/api/src/auth/password-settings.service.ts index faadf2a..4a8469b 100644 --- a/apps/api/src/auth/password-settings.service.ts +++ b/apps/api/src/auth/password-settings.service.ts @@ -56,10 +56,13 @@ export class PasswordSettingsService implements OnModuleInit { async status(principal: Principal): Promise { const user = await this.db.tx.user.findUniqueOrThrow({ where: { id: principal.userId }, - select: { passwordHash: true, passwordChangedAt: true, phone: true }, + select: { passwordChangedAt: true, phone: true }, }); + // The app login may not read password_hash (P1-J): a function says whether it is set. + const [set] = await this.db.tx.$queryRaw<{ value: boolean }[]>` + SELECT auth_my_password_is_set() AS value`; return { - hasPassword: user.passwordHash !== null, + hasPassword: set?.value === true, changedAt: user.passwordChangedAt?.toISOString() ?? null, phone: user.phone, }; diff --git a/apps/api/test/password.e2e-spec.ts b/apps/api/test/password.e2e-spec.ts index 6ba9c30..f762047 100644 --- a/apps/api/test/password.e2e-spec.ts +++ b/apps/api/test/password.e2e-spec.ts @@ -11,6 +11,7 @@ import { waitForOtp, type Harness, } from './support/harness.js'; +import { ownerClient } from './support/platform.js'; const PASSWORD = 'correct horse battery staple'; @@ -45,10 +46,16 @@ describe('password login', () => { roles: ['ADMIN'], }); - const user = await withContext(h.prisma, { userId }, (tx) => - tx.user.findUniqueOrThrow({ where: { id: userId } }), - ); - expect(user.passwordHash).toMatch(/^\$argon2id\$/); + // The app login may not read the hash (P1-J): the owner reads it, as that user. + const owner = ownerClient(); + try { + const user = await withContext(owner, { userId }, (tx) => + tx.user.findUniqueOrThrow({ where: { id: userId }, select: { passwordHash: true } }), + ); + expect(user.passwordHash).toMatch(/^\$argon2id\$/); + } finally { + await owner.$disconnect(); + } }); it('wrong password, unknown user and OTP-only user get the identical response', async () => { From 47fb35764bb32778e812d890ddfd1a31cb6963a9 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:16:13 +0600 Subject: [PATCH 13/44] Docs for P1-J: database.md (password_hash not readable by the app, a new users column needs its own GRANT SELECT, the client omit, the two new functions), auth.md (how a staff password is checked without the hash leaving the database, what is left), decisions-pending (P1-J built, P1-J1 to P1-J6) Co-Authored-By: Claude Opus 5.5 --- docs/auth.md | 25 +++++++++++++++++++++++-- docs/database.md | 17 ++++++++++++++++- docs/decisions-pending.md | 14 +++++++++++++- 3 files changed, 52 insertions(+), 4 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index 7c0a45c..01c05b8 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -30,8 +30,8 @@ Code lives in [`apps/api/src/auth`](../apps/api/src/auth) and the user lookup. An SMS is sent only if the phone belongs to a user. - Every failure of `otp/verify` and `login` (unknown user, wrong code or password, expired or burned code, OTP-only account) returns the same `401 Invalid credentials`. -- Password checks always run argon2, against a dummy hash if needed, so timing doesn't leak - either. +- Password checks always run one argon2 hash and one database comparison, with a dummy salt + and the nil user if needed, so timing doesn't leak either. **OTP storage.** Codes are never stored in plain text. Redis holds `HMAC-SHA256(OTP_PEPPER, phone:code)` with a 5-minute TTL, plus an attempt counter. The 5th wrong @@ -222,6 +222,27 @@ Password login accepts up to 512 code points, as many as a settable password can decomposed. `PasswordSettingsService` is the only code that writes `users.password_hash` (`password-writes.spec.ts` checks it). +**The API never reads a staff password hash (P1-J).** `jantrik_app` may write +`users.password_hash` but not read it, so an SQL injection in a request cannot take hashes away +to crack offline ([database.md](database.md) → users). Checking a password at login: + +1. `auth_find_user_for_login(phone, email)` returns the stored hash up to its last `$` + (`password_params`: argon2id, version 19, `m`, `t`, `p`, the salt), never the digest; NULL for + no password or any other format; +2. `PasswordService.loginDigest` hashes the typed password (NFC) with those parameters and that + salt, and takes the SHA-256 of the result. Parameters above 64 MiB, 10 passes or 4 lanes are + treated as unusable (a hash written into someone's own row cannot make each attempt + arbitrarily expensive); +3. `auth_my_password_matches(digest)`, run with `app.user_id` set to that user, compares it with + the SHA-256 of the stored hash and answers yes or no. + +With no user, no password or unusable parameters, step 2 hashes once at today's cost with a dummy +salt and step 3 runs for the nil user, so every case costs the same. `GET /me/password` reads +`hasPassword` from `auth_my_password_is_set()`. What is left: an injection can still ask step 3 +about guesses it hashed itself, one query per guess and only while the hole is open, which is less +than reading the hash. The platform admins' login is separate and unchanged +([platform.md](platform.md)). + ## Tenants - `GET /auth/memberships` lists the user's tenants with their roles. `selectable` means the diff --git a/docs/database.md b/docs/database.md index 936ba88..60a7287 100644 --- a/docs/database.md +++ b/docs/database.md @@ -167,6 +167,16 @@ references such as `sections.shift_id`. A row can only point at rows of its own - **`password_changed_at`:** when the person last set their password themselves (null: never, or only by the seed). Written only by `PasswordSettingsService`, with `password_hash` ([auth.md](auth.md) → Setting a password). + - **`password_hash` is not readable by the app (P1-J).** `jantrik_app` has SELECT on every + other column, granted column by column (a table-level SELECT would cover the hash again), and + UPDATE on it (setting a password). **A new `users` column needs its own + `GRANT SELECT (column) ON users TO jantrik_app`**, or the app cannot read it; + `schema-safety.test.ts` pins the readable columns, checks that no login but the owner may read + the hash, and lists the app-runnable functions that touch it. Every Prisma client omits + `passwordHash` (`createPrismaClient`, `CLIENT_OMIT` in `packages/db/src/client.ts`), so + whole-row reads and updates never name the column; the package's `PrismaClient` type is that + client's, and the generated class is not exported. A test that needs the hash reads it through + the owner, in the user's context, with `select` or `omit: { passwordHash: false }`. - **No INSERT or DELETE for the app.** Create people with `findOrCreateUser(tx, phone, name)`, which needs a tenant context. It returns only the id, so a person from another tenant stays hidden until they get a membership here. @@ -176,7 +186,12 @@ references such as `sections.shift_id`. A row can only point at rows of its own - Each is owned by `jantrik_auth`, pins `search_path = pg_catalog, public, pg_temp` (`pg_temp` last, so a temporary table cannot stand in for a real one), and is executable only by `jantrik_app`. - - `auth_find_user_for_login(phone, email)` + - `auth_find_user_for_login(phone, email)`: the user's id, name, locale and + `password_params` (the stored hash up to its last `$`: parameters and salt, never the + digest; P1-J) + - `auth_my_password_matches(digest)`: whether the SHA-256 of the current user's stored hash + (`app.user_id`) is `digest`; the login's comparison ([auth.md](auth.md) → Setting a password) + - `auth_my_password_is_set()`: whether the current user has a password (`GET /me/password`) - `auth_list_my_memberships()`: uses `app.user_id`, with no user parameter. It also returns `invited_at`, so the login flow can show pending invitations. - `auth_resolve_tenant(slug)` diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index 453bd24..c054efa 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -653,6 +653,18 @@ P1-I. **Open, for the owner: catch part of an institute's name too?** The rule r - To change: `passwordProblems` in `packages/shared/src/password.ts` (the server and the form share it). -P1-J. **Follow-up, for the owner: hide `users.password_hash` from the app login.** Real staff hashes now exist, and `jantrik_app` may still SELECT every column of the users it can see (itself, and the members of the current institute, through `users_visible`). An injection in a request could read co-members' hashes (argon2id, so slow to attack, but still). The fix: revoke SELECT on that column from `jantrik_app` and read `hasPassword` through a definer function, as the login already does; every full-row read of `users` in the app and the tests must then name its columns. A database and security change, so it needs a plan and your approval first. +P1-J. **Built (day run 2026-11-16), for the owner's review with its PR: the app login can no longer read password hashes.** Plan: [plans/sprint-1-p1j-password-hash.md](plans/sprint-1-p1j-password-hash.md), written and built while the owner was away, as asked. `jantrik_app` lost SELECT on `users.password_hash` (granted column by column; UPDATE kept), the login lookup returns only the hash's parameters and salt and the database compares, `hasPassword` comes from `auth_my_password_is_set()`, and every Prisma client omits the hash. Decisions taken alone, each the safest option (P1-J1 to P1-J6): + +P1-J1. **The login lookup returned any user's hash, so it changed too.** `auth_find_user_for_login`, which `jantrik_app` may run, returned `password_hash` for any phone or email, whatever the institute: hiding the column alone would have closed nothing. It now returns `password_params` (the hash up to its last `$`); the API hashes the typed password with them and `auth_my_password_matches(digest)` compares inside the database. What is left: an injection could ask that function about guesses it hashed itself (the cost of an offline attack, but one query per guess and only while the hole is open), which is less than reading the hash. Not rate-limited inside the database. + +P1-J2. **`hasPassword` comes from a definer function for the current user only** (`auth_my_password_is_set()`, no parameter, scoped by `app.user_id`), like `auth_list_my_memberships()`. The two new functions take no id, so the schema-safety rules (no uuid parameter, scoped by context) needed no new exception. + +P1-J3. **Every Prisma client omits `passwordHash`** (a global `omit` in `createPrismaClient`), instead of a `select` at each call site. The package's `PrismaClient` type is now that client's type and the generated class is no longer exported, so TypeScript refuses code that reads the hash and every client comes from the factory (the test helper's one-connection client too, with a new `max` pool option). The seed's and the harness's whole-row updates of users keep working unchanged. + +P1-J4. **A cost ceiling for stored hashes at login:** at most 64 MiB, 10 passes, 4 lanes (today's hashes: 19 MiB, 2, 1). Above it the stored hash is treated as unusable. Before, argon2 verified whatever parameters a stored hash named, so someone who wrote a huge-cost hash into their own row could make each of their login attempts arbitrarily expensive. + +P1-J5. **Only argon2id version 19 with a 32-byte digest** (what `@node-rs/argon2` writes) can sign in. Any other stored value gives no parameters, as a corrupt hash fails today; the person sets a new password after a phone code. Every hash Jantrik has written has this format; nothing to migrate. + +P1-J6. **Not changed: the platform admins' login** (`platform_find_admin_for_login` returns `platform_admins` hashes and TOTP secrets to `jantrik_platform_app`). It is a separate login with no tenant traffic; the same change can follow if you want it. P1-K. **Fixed from the review** (each with a test that failed first): a code is single use even when two requests race with it (login codes too); the phone rule ignores every punctuation mark and symbol between the digits; the other sessions are revoked in one statement; the common-password list is read at start-up; password login accepts up to 512 code points (a 128-character password typed decomposed); the wrong-code message asks to check the code before sending a new one. Kept as they are: the staff check after a correct password costs one extra query (it only confirms a password the caller already has); the login page's hint sits under the password tab, which guardians do not use. From 20b29e912cb41a62796e27b6e060031e5801ef7b Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:15 +0600 Subject: [PATCH 14/44] =?UTF-8?q?Redis=20is=20pinned=20to=20one=20exact=20?= =?UTF-8?q?version,=20redis:7.4.11-alpine=20(the=20version=20of=20the=20im?= =?UTF-8?q?age=20in=20use=20here),=20in=20the=20production=20compose,=20th?= =?UTF-8?q?e=20development=20compose=20and=20both=20CI=20jobs,=20and=20a?= =?UTF-8?q?=20test=20checks=20the=20four=20agree=20and=20are=20exact=20(P0?= =?UTF-8?q?=20review=20leftover:=20the=20image=20floated=20and=20the=20upg?= =?UTF-8?q?rade=20steps=20never=20pulled=20it).=20deploy.md=20=C2=A7=2011?= =?UTF-8?q?=20says=20how=20a=20new=20version=20is=20taken:=20a=20release?= =?UTF-8?q?=20changes=20the=20three=20together=20and=20`up=20-d`=20pulls?= =?UTF-8?q?=20it;=20a=20patched=20rebuild=20of=20the=20same=20tag=20with?= =?UTF-8?q?=20`compose.sh=20pull=20redis`.=20The=20deploy=20checklist=20me?= =?UTF-8?q?ntions=20the=20login=20check's=20new=20refusals.=20How=20Redis?= =?UTF-8?q?=20starts=20is=20unchanged=20(it=20still=20runs=20as=20root)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 4 +-- apps/api/src/config/production-env.spec.ts | 35 ++++++++++++++++++---- deploy/docker-compose.prod.yml | 2 +- docker-compose.yml | 2 +- docs/deploy.md | 9 +++++- 5 files changed, 42 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d3f60e..e1d0971 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,7 +71,7 @@ jobs: --health-timeout 5s --health-retries 10 redis: - image: redis:7-alpine + image: redis:7.4.11-alpine ports: - 6379:6379 options: >- @@ -156,7 +156,7 @@ jobs: --health-timeout 5s --health-retries 10 redis: - image: redis:7-alpine + image: redis:7.4.11-alpine ports: - 6379:6379 options: >- diff --git a/apps/api/src/config/production-env.spec.ts b/apps/api/src/config/production-env.spec.ts index ef59ace..91d5de7 100644 --- a/apps/api/src/config/production-env.spec.ts +++ b/apps/api/src/config/production-env.spec.ts @@ -170,6 +170,26 @@ describe('production env: the API and the worker', () => { expect(apiError({ ...api, PLATFORM_ORIGINS: 'https://PLATFORM.jantrik.com.bd/' })).toBe(''); }); + it('pins Redis to one exact version in the production compose, the development compose and CI', () => { + const images = [ + 'deploy/docker-compose.prod.yml', + 'docker-compose.yml', + '.github/workflows/ci.yml', + ].flatMap((file) => + [ + ...readFileSync(path.resolve(import.meta.dirname, '../../../..', file), 'utf8').matchAll( + /image:\s*(redis:\S+)/g, + ), + ].map((m) => ({ file, image: m[1]! })), + ); + // The production compose and the development one once each, CI's two jobs. + expect(images).toHaveLength(4); + for (const { file, image } of images) { + expect(image, file).toMatch(/^redis:\d+\.\d+\.\d+-alpine$/); + } + expect(new Set(images.map((i) => i.image)).size).toBe(1); + }); + it('normalises CORS_ORIGINS too, so the CORS middleware allows what the start-up check passed', () => { const dev = { DATABASE_URL: 'postgresql://jantrik_app:x@localhost:5432/jantrik', @@ -180,7 +200,8 @@ describe('production env: the API and the worker', () => { }; const parsed = envSchema.parse({ ...dev, - CORS_ORIGINS: 'HTTPS://App.Jantrik.com.bd/ , http://localhost:3000/,https://a.example.com:443', + CORS_ORIGINS: + 'HTTPS://App.Jantrik.com.bd/ , http://localhost:3000/,https://a.example.com:443', }); expect(parsed.CORS_ORIGINS).toEqual([ 'https://app.jantrik.com.bd', @@ -190,11 +211,15 @@ describe('production env: the API and the worker', () => { // The browser sends the normalised form; the middleware's check is an exact match. expect(isAllowedOrigin('https://app.jantrik.com.bd', parsed)).toBe(true); // An entry that is not an origin stays as written (production refuses it, see above). - expect(envSchema.parse({ ...dev, CORS_ORIGINS: '*,app.jantrik.com.bd' }).CORS_ORIGINS).toEqual( - ['*', 'app.jantrik.com.bd'], - ); + expect(envSchema.parse({ ...dev, CORS_ORIGINS: '*,app.jantrik.com.bd' }).CORS_ORIGINS).toEqual([ + '*', + 'app.jantrik.com.bd', + ]); // Production: an upper-case, slash-ended entry passes the check and is allowed by the middleware. - const prod = { ...api, CORS_ORIGINS: 'https://APP.jantrik.com.bd/,https://platform.jantrik.com.bd' }; + const prod = { + ...api, + CORS_ORIGINS: 'https://APP.jantrik.com.bd/,https://platform.jantrik.com.bd', + }; expect(apiError(prod)).toBe(''); expect(envSchema.parse(prod).CORS_ORIGINS).toContain('https://app.jantrik.com.bd'); }); diff --git a/deploy/docker-compose.prod.yml b/deploy/docker-compose.prod.yml index e8d4f56..e60c014 100644 --- a/deploy/docker-compose.prod.yml +++ b/deploy/docker-compose.prod.yml @@ -88,7 +88,7 @@ services: logging: *logging redis: - image: redis:7-alpine + image: redis:7.4.11-alpine restart: unless-stopped # Deployment requirement 2: never evict a key, and keep every write (AOF, fsync each second). # At REDIS_MAXMEMORY, writes fail loudly (noeviction) instead of Redis growing until the diff --git a/docker-compose.yml b/docker-compose.yml index 57dfe9b..0666e05 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -27,7 +27,7 @@ services: retries: 10 redis: - image: redis:7-alpine + image: redis:7.4.11-alpine restart: unless-stopped command: ['redis-server', '--appendonly', 'yes'] ports: diff --git a/docs/deploy.md b/docs/deploy.md index 71e9a89..096b574 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -340,6 +340,12 @@ deploy/compose.sh ps - **Rollback:** migrations only go forward. If a release must be undone after its migrations ran, restore the backup you took (below) and start the previous version's images. +- **Redis is pinned to one exact version** (`redis:7.4.11-alpine`, the same in this compose file, + the development `docker-compose.yml` and CI; a test checks they agree). A newer Redis comes + with a release that changes the three tags together, after reading Redis's release notes; at + the upgrade, `up -d` pulls the new tag and restarts Redis on the same volume (AOF: no data is + lost; queued jobs wait a few seconds). Between releases, a patched rebuild of the same tag is + taken with `deploy/compose.sh pull redis && deploy/compose.sh up -d redis`. - `NEXT_PUBLIC_API_URL` is baked into the web image: changing `API_DOMAIN` needs a rebuild. - `JANTRIK_BOOT_REFRESH=off` in the settings file switches the boot refresh off (docs/auth.md → Web client) without a rebuild: `deploy/compose.sh up -d web`. @@ -533,7 +539,8 @@ To use a provider's Postgres 16 instead of the `postgres` service: - **Off-site backup storage** and **an uptime monitor** of your choice. - **Done in sprint 1, P0:** the `Origin` check in `PlatformAuthGuard` (Caddy's rule stays as a second layer), the receiver's own Redis user, the start-up check that refuses a database login - that is a superuser or bypasses RLS, and the receiver's 5 s query limit. + that is a superuser or bypasses RLS (since 2026-11-16 also REPLICATION and CREATEROLE), and the + receiver's 5 s query limit. - **Recorded, not built** (decisions-pending.md → Deployment readiness): - CI does not cover the compose Postgres's first start (initdb), the non-superuser branch of `create-roles.sh` or the image builds (all checked by hand for this release); From 81bfc26cd1acacbf9e532bb0a38a9ee95cd80b54 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:15 +0600 Subject: [PATCH 15/44] Docs for the follow-ups: decisions-pending gets the section "Small follow-ups (day run 2026-11-16)" (F-1 to F-6: the generic words and the choices around them, CORS_ORIGINS kept lenient for non-origins, the Redis pin, CREATEROLE refused too, how test phones stay unique) and marks the three P0 leftovers built; auth.md says CORS_ORIGINS and PLATFORM_ORIGINS are normalised Co-Authored-By: Claude Opus 5.5 --- docs/auth.md | 5 ++- docs/decisions-pending.md | 64 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 65 insertions(+), 4 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index 00b9ff5..9e5ac5d 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -454,7 +454,7 @@ Code: [`apps/web/src/lib/auth/auth-client.ts`](../apps/web/src/lib/auth/auth-cli | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `JWT_ACCESS_SECRET` | at least 32 characters | | `OTP_PEPPER` | at least 32 characters | -| `CORS_ORIGINS` | comma-separated allowlist, normalised like `Origin` (lower-case host, no trailing slash or default port); browsers may cache a preflight's answer for 2 h (`maxAge` in `app.setup.ts`), so a narrower list reaches open tabs up to 2 h later | +| `CORS_ORIGINS` | comma-separated allowlist; browsers may cache a preflight's answer for 2 h (`maxAge` in `app.setup.ts`), so a narrower list reaches open tabs up to 2 h later | | `PLATFORM_ORIGINS` | the platform web app's origins: the only ones `/platform/*` answers (each also in `CORS_ORIGINS`); default `http://localhost:3000`, required in production | | `COOKIE_SECURE` | Secure flag on the refresh cookie | | `TRUST_PROXY` | Express `trust proxy`; set it behind a load balancer so client IPs are right | @@ -462,6 +462,9 @@ Code: [`apps/web/src/lib/auth/auth-client.ts`](../apps/web/src/lib/auth/auth-cli | `SMS_PROVIDER` | `console` in development, `memory` in API tests, `outbox` (Redis list `sms:outbox:`) for Playwright; all refused in production | | rate-limit variables | see `.env.example` | +`CORS_ORIGINS` and `PLATFORM_ORIGINS` are normalised as browsers send `Origin` (lower-case host, +no trailing slash or default port), so an entry written `https://App.example.com/` still matches. + In production `SMS_PROVIDER=none` stands in until a gateway is built: every SMS fails and is recorded as failed. What else production refuses: [deploy.md](deploy.md) → Environment checks. diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index 453bd24..9619c05 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -593,12 +593,70 @@ P0-9. **The login check reads `session_user`** (the login), never `current_user` Left by the final review for later (not built, each small): -- **Redis runs as root and its image floats.** `start-redis.sh` is started with `sh`, which skips the image's entrypoint (it drops to the `redis` user), as the earlier `sh -c` command did; `redis:7-alpine` is never pulled by the upgrade steps. The receiver can run Lua (`eval`), as it could before P0 with all of Redis. To do: end the script with `exec docker-entrypoint.sh redis-server …`, and pin a patched image or add `compose.sh pull redis` to the upgrade. -- **`CORS_ORIGINS` is compared normalised by the start-up check but raw by the CORS middleware:** an upper-case or slash-ended `CORS_ORIGINS` entry passes start-up while the browser's preflight fails. The compose file derives both lists from `PLATFORM_DOMAIN`, so only a hand-written setting can hit it. To do: normalise `CORS_ORIGINS` in `env.ts` too. +- **Redis runs as root ~~and its image floats~~** (the image is pinned since the follow-ups of 2026-11-16, F-4 below; running as root is still open). `start-redis.sh` is started with `sh`, which skips the image's entrypoint (it drops to the `redis` user), as the earlier `sh -c` command did; `redis:7-alpine` is never pulled by the upgrade steps. The receiver can run Lua (`eval`), as it could before P0 with all of Redis. To do: end the script with `exec docker-entrypoint.sh redis-server …`, and pin a patched image or add `compose.sh pull redis` to the upgrade. +- **Done 2026-11-16 (F-3 below).** **`CORS_ORIGINS` is compared normalised by the start-up check but raw by the CORS middleware:** an upper-case or slash-ended `CORS_ORIGINS` entry passes start-up while the browser's preflight fails. The compose file derives both lists from `PLATFORM_DOMAIN`, so only a hand-written setting can hit it. To do: normalise `CORS_ORIGINS` in `env.ts` too. - **The receiver's key scope `~:devices:*` includes the worker's job schedulers** (the devices tick, expire-punches): code run in the receiver could delete them until the worker restarts and recreates them. Accepted for now (the scope the plan set); narrower read/write key selectors are possible at some cost across BullMQ upgrades. -- **Refuse REPLICATION logins too** (`rolreplication`, and possibly `rolcreaterole`) in the login check; every production role is already created without them. +- **Done 2026-11-16 (F-5 below).** **Refuse REPLICATION logins too** (`rolreplication`, and possibly `rolcreaterole`) in the login check; every production role is already created without them. - **Local Playwright configs** that are not in git (`playwright.alt*.config.ts`, `dbg`, `shots`) set `CORS_ORIGINS` but not `PLATFORM_ORIGINS`: their platform specs now get 403 until they set it. +## Small follow-ups (day run 2026-11-16) + +Branch `chore/small-followups`, one PR. Decided by the agent alone (the owner was away); each can +be changed in review. + +F-1. **P1-I is built as the owner answered:** a password is also refused when it contains a +distinctive word of an institute's name. The name is split at spaces, punctuation and symbols; +generic words are dropped; every remaining word of 4 or more code points (the whole-name rule's +counting) is refused. The whole-name rule stays. The error code stays `HAS_INSTITUTE_NAME` (its +message now says "the name or a word from it"), so the web and the API did not change shape. + +F-2. **The generic words** (`GENERIC_NAME_WORDS` in `packages/shared/src/password.ts`), chosen +from the owner's examples "and similar": the kind of institute (school, college, madrasa, academy, +coaching, centre, institute, kindergarten, polytechnic, pathshala…), its level (high, secondary, +primary, junior, dakhil, alim, fazil, kamil…), who it is for (girls, boys, mohila…), its medium and +standing (english, bangla, version, international, model, ideal, public, government/govt, cadet, +residential…), madrasa name words (darul, uloom, jamia, hafizia, nurani, qawmi, islamia, quran…), +`and` written in Bangla, each in Bangla and in English letters with common spellings (madrasah, +madrassa, মাদরাসা, সরকারী, একাডেমী…). Not generic: place names and people's names (`Dhaka`, +`Motijheel`, `Salim`): they point at the institute, so they are refused. Choices beyond the +owner's words: + +- **Generic words glued to the end of a word** are cut off too (`শাপলাউচ্চবিদ্যালয়` → `শাপলা`, + `Kodomtolaschool` → `kodomtola`), and the whole glued word is still refused as well, so the rule + never refuses less than splitting at spaces alone. Only endings: a generic word at the start of + an ordinary word is not cut (`Highland` stays `highland`, so `highschool2026` is allowed). +- **Zero-width joiners** (U+200C, U+200D: typed inside some Bangla words) are ignored on both + sides, for whole names too. Unicode forms (য় as one code point or two) were already unified. +- **The slug is not checked** (the decision mentioned it as a "perhaps"; the owner's answer did not + ask for it). + +F-3. **`CORS_ORIGINS` is normalised in `env.ts`** like `PLATFORM_ORIGINS` (lower-case host, no +trailing slash or default port). An entry that is not an origin (`*`, a bare host) is kept as +written instead of stopping the start: it matches nothing, production refuses it as before, and a +developer's existing `.env` keeps working. + +F-4. **Redis is pinned to `redis:7.4.11-alpine`**, the version of the image this PC had (built +2026-09-17; the tag exists on Docker Hub), in the production compose, the development compose and +both CI jobs; a test checks the four agree and are exact. The exact tag, not a digest: Docker's +patched rebuilds of the same version can still be taken (`compose.sh pull redis`, deploy.md § +11). Your local Redis container keeps running `redis:7-alpine` until the next +`docker compose up -d`, which pulls 7.4.11 and restarts it on the same volume. Postgres +(`postgres:16-alpine`) and Caddy (`caddy:2-alpine`) still float: not asked, same fix if wanted. + +F-5. **The login check refuses REPLICATION and CREATEROLE** for the runtime logins, and a login +that can become a role with either. CREATEROLE is refused too (the decision said "possibly"): no +runtime login has or needs it, the local init script creates none with it, and `create-roles.sh` +already refuses both for every role it makes, so no correct setup stops starting. + +F-6. **Test users' phones are unique per database, across runs too** (the appearance flake, +P0-8). A per-run counter is not enough: the test database keeps every run's users, and Vitest +gives each test file its own module (no shared memory). So one counter per database lives in a +file in the OS temp folder (`jantrik-test-phones/`), taken 200 numbers at a time under a lock, and +never behind a clock that moves 20 numbers a second (a deleted file restarts ahead of older runs). +New phones use operators no test used before (API +88013, db package +88014, from 50 000 000; the +seeds' fixed numbers are lower and the old random phones were 017/018), so they cannot meet old +test users either. `randomPhone` kept its name (about 40 files call it). + ## The refresh race fix (2026-11-15) Plan: [plans/fix-refresh-race.md](plans/fix-refresh-race.md), approved by the owner with conditions. From 9cc9d5415da112687d386bfac60db5a2bc82660c Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:42 +0600 Subject: [PATCH 16/44] Image processing for uploads (P2 task 3): sharp 0.35.5 (already in the lockfile through Next.js) checks the magic bytes (JPEG, PNG, WebP only), refuses more than 50 megapixels from the header alone, turns the image upright, shrinks it into its kind's box and re-encodes it under the kind's cap; metadata (EXIF GPS, ICC, XMP) is never kept; at most two images at once per process Co-Authored-By: Claude Opus 5.5 --- apps/api/package.json | 1 + apps/api/src/files/image.service.spec.ts | 177 ++++++++++++++++++++++ apps/api/src/files/image.service.ts | 179 +++++++++++++++++++++++ pnpm-lock.yaml | 7 +- 4 files changed, 361 insertions(+), 3 deletions(-) create mode 100644 apps/api/src/files/image.service.spec.ts create mode 100644 apps/api/src/files/image.service.ts diff --git a/apps/api/package.json b/apps/api/package.json index 1cc212f..c4baa45 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -32,6 +32,7 @@ "read-excel-file": "9.3.10", "reflect-metadata": "0.2.2", "rxjs": "7.8.2", + "sharp": "0.35.5", "write-excel-file": "4.1.1", "zod": "4.6.7" }, diff --git a/apps/api/src/files/image.service.spec.ts b/apps/api/src/files/image.service.spec.ts new file mode 100644 index 0000000..5402d68 --- /dev/null +++ b/apps/api/src/files/image.service.spec.ts @@ -0,0 +1,177 @@ +import { randomBytes } from 'node:crypto'; +import { crc32, deflateSync } from 'node:zlib'; +import sharp from 'sharp'; +import { ImageService, processImage, sniffImage } from './image.service.js'; + +// docs/files.md: what an upload becomes before it is stored. Test images are made with sharp. + +const noise = (width: number, height: number, channels: 3 | 4 = 3) => + sharp(randomBytes(width * height * channels), { raw: { width, height, channels } }); + +const code = async (p: Promise) => { + try { + await p; + } catch (e) { + return (e as { getResponse?: () => { code?: string } }).getResponse?.().code ?? String(e); + } + return 'resolved'; +}; + +/** A valid PNG header (IHDR) declaring width × height, with a tiny IDAT: a decompression bomb. */ +function pngClaiming(width: number, height: number): Buffer { + const chunk = (type: string, data: Buffer) => { + const len = Buffer.alloc(4); + len.writeUInt32BE(data.length); + const body = Buffer.concat([Buffer.from(type, 'latin1'), data]); + const crc = Buffer.alloc(4); + crc.writeUInt32BE(crc32(body)); + return Buffer.concat([len, body, crc]); + }; + const ihdr = Buffer.alloc(13); + ihdr.writeUInt32BE(width, 0); + ihdr.writeUInt32BE(height, 4); + ihdr[8] = 8; // bit depth + ihdr[9] = 0; // greyscale + return Buffer.concat([ + Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), + chunk('IHDR', ihdr), + chunk('IDAT', deflateSync(Buffer.alloc(width + 1))), + chunk('IEND', Buffer.alloc(0)), + ]); +} + +describe('processImage', () => { + it.each(['jpeg', 'png', 'webp'] as const)( + 'a %s photo becomes a JPEG within 600 × 800 and 200 KB', + async (format) => { + const input = await noise(1200, 1600).toFormat(format).toBuffer(); + const out = await processImage('STUDENT_PHOTO', input); + expect(out.mime).toBe('image/jpeg'); + expect(out.bytes.length).toBeLessThanOrEqual(200 * 1024); + expect(out.width).toBeLessThanOrEqual(600); + expect(out.height).toBeLessThanOrEqual(800); + const meta = await sharp(out.bytes).metadata(); + expect([meta.format, meta.width, meta.height]).toEqual(['jpeg', out.width, out.height]); + }, + ); + + it('a large, detailed photo (3000 × 2000 of noise) still fits the cap', async () => { + const input = await noise(3000, 2000).jpeg({ quality: 95 }).toBuffer(); + const out = await processImage('STUDENT_PHOTO', input); + expect(out.bytes.length).toBeLessThanOrEqual(200 * 1024); + expect(Math.max(out.width, out.height)).toBeLessThanOrEqual(800); + }); + + it('a small photo is not enlarged', async () => { + const out = await processImage('STUDENT_PHOTO', await noise(120, 160).png().toBuffer()); + expect([out.width, out.height]).toEqual([120, 160]); + }); + + it('strips EXIF (GPS included) after turning the photo upright', async () => { + const input = await noise(400, 200) + .jpeg() + .withMetadata({ orientation: 6 }) + .withExif({ + IFD0: { Make: 'PhoneCo', Model: 'X1' }, + IFD3: { GPSLatitudeRef: 'N', GPSLatitude: '23/1 48/1 0/1' }, + }) + .toBuffer(); + const before = await sharp(input).metadata(); + expect(before.exif).toBeDefined(); + expect(before.orientation).toBe(6); + expect(input.includes(Buffer.from('PhoneCo'))).toBe(true); + const out = await processImage('STUDENT_PHOTO', input); + const after = await sharp(out.bytes).metadata(); + expect(after.exif).toBeUndefined(); + expect(after.icc).toBeUndefined(); + expect(after.xmp).toBeUndefined(); + expect(after.orientation).toBeUndefined(); + expect(out.bytes.includes(Buffer.from('PhoneCo'))).toBe(false); + // Rotated a quarter turn: 400 × 200 becomes 200 × 400. + expect([out.width, out.height]).toEqual([200, 400]); + }); + + it('a transparent logo stays transparent (PNG), within 512 × 512 and 100 KB', async () => { + const pixels = Buffer.alloc(800 * 800 * 4); // fully transparent… + for (let i = 0; i < 200 * 800 * 4; i += 4) pixels.set([20, 90, 60, 255], i); // …but a band + const input = await sharp(pixels, { raw: { width: 800, height: 800, channels: 4 } }) + .png() + .toBuffer(); + const out = await processImage('LOGO', input); + expect(out.mime).toBe('image/png'); + expect(out.bytes.length).toBeLessThanOrEqual(100 * 1024); + expect([out.width, out.height]).toEqual([512, 512]); + expect((await sharp(out.bytes).metadata()).hasAlpha).toBe(true); + }); + + it('a seal too detailed for a PNG under 100 KB is stored as WebP', async () => { + const out = await processImage('SEAL', await noise(512, 512).png().toBuffer()); + expect(out.bytes.length).toBeLessThanOrEqual(100 * 1024); + expect(out.mime).toBe('image/webp'); + }); + + it.each(['STUDENT_PHOTO', 'LOGO', 'SEAL', 'SIGNATURE'] as const)( + 'even pure noise (the worst case) is done well inside the request time: %s', + async (kind) => { + const input = await noise(2400, 2400, 4).png({ compressionLevel: 1 }).toBuffer(); + const started = Date.now(); + const out = await processImage(kind, input); + expect(out.bytes.length).toBeLessThanOrEqual( + kind === 'STUDENT_PHOTO' ? 200 * 1024 : 100 * 1024, + ); + expect(Date.now() - started).toBeLessThan(8_000); + }, + ); + + it('a signature is a PNG within 600 × 240', async () => { + const out = await processImage('SIGNATURE', await noise(1200, 400).jpeg().toBuffer()); + expect(out.mime).toBe('image/png'); + expect(out.bytes.length).toBeLessThanOrEqual(100 * 1024); + expect(out.width).toBeLessThanOrEqual(600); + expect(out.height).toBeLessThanOrEqual(240); + }); + + it('refuses a text file, a GIF, an SVG and a truncated JPEG', async () => { + const jpg = await noise(300, 300).jpeg().toBuffer(); + const gif = await noise(20, 20).gif().toBuffer(); + const svg = Buffer.from(''); + for (const input of [Buffer.from('hello, not an image'), gif, svg, jpg.subarray(0, 600)]) { + expect(await code(processImage('STUDENT_PHOTO', input))).toBe('IMAGE_INVALID'); + } + }); + + it('refuses a decompression bomb by its header, without decoding it', async () => { + const bomb = pngClaiming(50_000, 50_000); + expect(bomb.length).toBeLessThan(60_000); + const started = Date.now(); + expect(await code(processImage('STUDENT_PHOTO', bomb))).toBe('IMAGE_TOO_BIG'); + expect(Date.now() - started).toBeLessThan(2_000); + }); + + it('sniffs only JPEG, PNG and WebP', async () => { + expect(sniffImage(await noise(4, 4).jpeg().toBuffer())).toBe('jpeg'); + expect(sniffImage(await noise(4, 4).png().toBuffer())).toBe('png'); + expect(sniffImage(await noise(4, 4).webp().toBuffer())).toBe('webp'); + expect(sniffImage(await noise(4, 4).gif().toBuffer())).toBeNull(); + expect(sniffImage(Buffer.alloc(0))).toBeNull(); + }); +}); + +describe('ImageService', () => { + it('runs at most two images at once', async () => { + const service = new ImageService(); + const input = await noise(1600, 1200).jpeg().toBuffer(); + let peak = 0; + // Watch the service's own counter while five run. + const watch = setInterval(() => { + peak = Math.max(peak, (service as unknown as { running: number }).running); + }, 1); + const results = await Promise.all( + Array.from({ length: 5 }, () => service.process('STUDENT_PHOTO', input)), + ); + clearInterval(watch); + expect(results).toHaveLength(5); + expect(peak).toBeGreaterThan(0); + expect(peak).toBeLessThanOrEqual(2); + }); +}); diff --git a/apps/api/src/files/image.service.ts b/apps/api/src/files/image.service.ts new file mode 100644 index 0000000..73c4c9f --- /dev/null +++ b/apps/api/src/files/image.service.ts @@ -0,0 +1,179 @@ +import { Injectable } from '@nestjs/common'; +import { + FILE_LIMITS, + UPLOAD_MAX_PIXELS, + type StoredFileKind, + type StoredMime, +} from '@jantrik/shared'; +import sharp from 'sharp'; +import { apiError } from '../common/api-error.js'; + +// libvips' operation cache keeps recent images in memory; uploads are one-off, so it only costs RAM. +sharp.cache(false); + +export interface ProcessedImage { + bytes: Buffer; + mime: StoredMime; + width: number; + height: number; +} + +/** At most this many images are decoded at once per process (memory: a 48 MP photo is ~150 MB). */ +const MAX_PARALLEL = 2; + +/** + * Turns an upload into what is stored (docs/files.md, decision S7): only JPEG, PNG or WebP by + * content, at most UPLOAD_MAX_PIXELS, EXIF orientation applied, shrunk into the kind's box and + * re-encoded until it fits the kind's cap. Nothing of the upload is kept but its pixels: EXIF + * (GPS), ICC, XMP and comments are never copied. + */ +@Injectable() +export class ImageService { + private running = 0; + private readonly queue: (() => void)[] = []; + + async process(kind: StoredFileKind, input: Buffer): Promise { + if (this.running >= MAX_PARALLEL) await new Promise((go) => this.queue.push(go)); + this.running++; + try { + return await processImage(kind, input); + } finally { + this.running--; + this.queue.shift()?.(); + } + } +} + +type Sniffed = 'jpeg' | 'png' | 'webp'; + +/** The format by its magic bytes, before any decoder sees the data (no SVG, GIF, HEIC, PDF…). */ +export function sniffImage(input: Buffer): Sniffed | null { + if (input.length >= 3 && input[0] === 0xff && input[1] === 0xd8 && input[2] === 0xff) { + return 'jpeg'; + } + if ( + input.length >= 8 && + input.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) + ) { + return 'png'; + } + if ( + input.length >= 12 && + input.toString('latin1', 0, 4) === 'RIFF' && + input.toString('latin1', 8, 12) === 'WEBP' + ) { + return 'webp'; + } + return null; +} + +const invalid = () => + apiError(422, 'IMAGE_INVALID', 'The file is not a JPEG, PNG or WebP image, or it is damaged'); + +/** sharp's types are an `export =` namespace; these are the shapes used here. */ +type Sharp = ReturnType; +type Metadata = Awaited>; +interface RawImage { + data: Buffer; + info: { width: number; height: number; channels: number }; +} + +interface Encoder { + mime: StoredMime; + apply(image: Sharp): Sharp; +} + +const jpeg = (quality: number): Encoder => ({ + mime: 'image/jpeg', + apply: (i) => i.jpeg({ quality, mozjpeg: true }), +}); +const png = (colours: number): Encoder => ({ + mime: 'image/png', + apply: (i) => i.png({ palette: true, colours, quality: 90, compressionLevel: 9, effort: 4 }), +}); +const webp = (quality: number): Encoder => ({ + mime: 'image/webp', + apply: (i) => i.webp({ quality, alphaQuality: 90, effort: 4 }), +}); + +/** Encoders per kind, best first; the first result under the cap wins. */ +function encodersFor(kind: StoredFileKind): { flatten: boolean; encoders: Encoder[] } { + switch (kind) { + case 'STUDENT_PHOTO': + case 'APPLICANT_PHOTO': + return { flatten: true, encoders: [85, 75, 65, 55, 45].map(jpeg) }; + case 'LOGO': + case 'SEAL': + return { flatten: false, encoders: [png(256), ...[90, 75, 60, 50].map(webp)] }; + case 'SIGNATURE': + return { flatten: false, encoders: [256, 64, 16].map(png) }; + case 'DOCUMENT_ASSET': + // P8 (the document designer) decides how its assets are processed; nothing uploads one yet. + throw new Error('DOCUMENT_ASSET uploads are not supported yet'); + } +} + +export async function processImage(kind: StoredFileKind, input: Buffer): Promise { + const limit = FILE_LIMITS[kind]; + const { flatten, encoders } = encodersFor(kind); + if (!sniffImage(input)) throw invalid(); + + // The pixel count is checked before anything is decoded. + let meta: Metadata; + try { + // The header only (no pixel limit here, so a bomb is reported as too big, not as damaged). + meta = await sharp(input, { limitInputPixels: false }).metadata(); + } catch { + throw invalid(); + } + if (!meta.width || !meta.height || !['jpeg', 'png', 'webp'].includes(meta.format ?? '')) { + throw invalid(); + } + if (meta.width * meta.height > UPLOAD_MAX_PIXELS) { + throw apiError( + 422, + 'IMAGE_TOO_BIG', + `The image has too many pixels (at most ${UPLOAD_MAX_PIXELS / 1_000_000} megapixels)`, + ); + } + + // Decode once (first frame of an animation), upright, shrunk into the box, as raw pixels. + const box = limit.box!; + let raw: RawImage; + try { + let pipeline = sharp(input, { limitInputPixels: UPLOAD_MAX_PIXELS, failOn: 'truncated' }) + .rotate() + .resize(box.width, box.height, { fit: 'inside', withoutEnlargement: true }); + if (flatten) pipeline = pipeline.flatten({ background: '#ffffff' }); + raw = await pipeline.raw().toBuffer({ resolveWithObject: true }); + } catch { + throw invalid(); + } + + const fromRaw = () => + sharp(raw.data, { + raw: { + width: raw.info.width, + height: raw.info.height, + channels: raw.info.channels as 1 | 2 | 3 | 4, + }, + }); + + // Smaller dimensions only when no encoder fits at this size (a very detailed image). + for (const scale of [1, 0.8, 0.64, 0.5]) { + const width = Math.max(1, Math.round(raw.info.width * scale)); + const height = Math.max(1, Math.round(raw.info.height * scale)); + for (const encoder of encoders) { + const sized = scale === 1 ? fromRaw() : fromRaw().resize(width, height, { fit: 'fill' }); + const { data, info } = await encoder.apply(sized).toBuffer({ resolveWithObject: true }); + if (data.length <= limit.maxBytes) { + return { bytes: data, mime: encoder.mime, width: info.width, height: info.height }; + } + } + } + throw apiError( + 422, + 'IMAGE_CANNOT_SHRINK', + 'The image could not be made small enough; try another', + ); +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b6e984a..6459ade 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -235,6 +235,9 @@ importers: rxjs: specifier: 7.8.2 version: 7.8.2 + sharp: + specifier: 0.35.5 + version: 0.35.5(@types/node@24.19.2) write-excel-file: specifier: 4.1.1 version: 4.1.1 @@ -6222,8 +6225,7 @@ snapshots: '@humanwhocodes/retry@0.4.3': {} - '@img/colour@1.1.0': - optional: true + '@img/colour@1.1.0': {} '@img/sharp-darwin-arm64@0.35.5': optionalDependencies: @@ -10327,7 +10329,6 @@ snapshots: '@img/sharp-win32-ia32': 0.35.5 '@img/sharp-win32-x64': 0.35.5 '@types/node': 24.19.2 - optional: true shebang-command@2.0.0: dependencies: From b0e010b9feeff1bcaf7162be2ffa726976095a83 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:42 +0600 Subject: [PATCH 17/44] FileStore and the per-institute cap (P2 task 4): PostgresFileStore is the only code that touches the files' tables (a code scan checks it); put and delete hold the institute's advisory lock and move the total in the same transaction, 413 STORAGE_FULL past FILE_STORAGE_PER_TENANT_MB (default 1024); ImageUpload (multipart, 5 MB, one file), 60 uploads per person per 10 minutes, and entity-route serving with a strong ETag, Cache-Control private, 304 without reading the bytes Co-Authored-By: Claude Opus 5.5 --- apps/api/src/config/env.ts | 2 + apps/api/src/files/file-store-access.spec.ts | 48 +++++++ apps/api/src/files/file-store.ts | 49 +++++++ apps/api/src/files/files.module.ts | 92 +++++++++++++ apps/api/src/files/postgres-file-store.ts | 136 +++++++++++++++++++ 5 files changed, 327 insertions(+) create mode 100644 apps/api/src/files/file-store-access.spec.ts create mode 100644 apps/api/src/files/file-store.ts create mode 100644 apps/api/src/files/files.module.ts create mode 100644 apps/api/src/files/postgres-file-store.ts diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts index 7ee964a..3bf6f5d 100644 --- a/apps/api/src/config/env.ts +++ b/apps/api/src/config/env.ts @@ -140,6 +140,8 @@ export const envSchema = z LOGIN_PER_IDENTIFIER_PER_15MIN: positiveInt(5), // Staff invitations (POST /staff and re-invites) per institute and hour. STAFF_INVITES_PER_TENANT_PER_HOUR: positiveInt(30), + // Stored images per institute, in MB (docs/files.md): over it, uploads get 413 STORAGE_FULL. + FILE_STORAGE_PER_TENANT_MB: positiveInt(1024), }) .superRefine((env, ctx) => { // Loosened settings must never leave a developer's machine. diff --git a/apps/api/src/files/file-store-access.spec.ts b/apps/api/src/files/file-store-access.spec.ts new file mode 100644 index 0000000..bb07317 --- /dev/null +++ b/apps/api/src/files/file-store-access.spec.ts @@ -0,0 +1,48 @@ +import { readdirSync, readFileSync } from 'node:fs'; +import path from 'node:path'; + +// Sprint 1 P2 (decision S7): files are reached only through the FileStore interface, so storage can +// move to a bucket without touching callers. This scan keeps any other code from reading or +// writing stored_files and stored_file_usage directly (Prisma or raw SQL). +const SRC = path.resolve(import.meta.dirname, '..'); +const THE_STORE = 'files/postgres-file-store.ts'; + +export function touchesFileTables(code: string): boolean { + return /\.storedFile(Usage)?\b|\bstored_file(s|_usage)\b/.test(code); +} + +function sources(dir: string): string[] { + return readdirSync(dir, { withFileTypes: true }).flatMap((e) => { + const full = path.join(dir, e.name); + if (e.isDirectory()) return sources(full); + return e.name.endsWith('.ts') && !e.name.endsWith('.spec.ts') ? [full] : []; + }); +} + +describe('who touches stored_files', () => { + it(`only ${THE_STORE}`, () => { + const touching = sources(SRC) + .filter((file) => touchesFileTables(readFileSync(file, 'utf8'))) + .map((file) => path.relative(SRC, file).replaceAll('\\', '/')); + expect(touching).toEqual([THE_STORE]); + }); + + it('the scan finds what it looks for', () => { + const caught = [ + 'await tx.storedFile.findUnique({ where: { id } })', + 'this.db.tx.storedFile.create({ data })', + 'tx.storedFileUsage.update({ where: { tenantId } })', + 'SELECT bytes FROM stored_files WHERE id = $1', + 'DELETE FROM stored_files', + 'UPDATE stored_file_usage SET bytes_used = 0', + ]; + for (const sample of caught) expect(touchesFileTables(sample), sample).toBe(true); + const fine = [ + 'await this.files.get(id)', + 'tx.student.update({ data: { photoFileId } })', + 'const storedFiles = 3;', + "'stored-files:' advisory lock name", + ]; + for (const sample of fine) expect(touchesFileTables(sample), sample).toBe(false); + }); +}); diff --git a/apps/api/src/files/file-store.ts b/apps/api/src/files/file-store.ts new file mode 100644 index 0000000..ccae1e3 --- /dev/null +++ b/apps/api/src/files/file-store.ts @@ -0,0 +1,49 @@ +import type { StoredFileKind, StoredMime } from '@jantrik/shared'; + +/** What a stored file is, without its bytes. */ +export interface StoredFileMeta { + id: string; + kind: StoredFileKind; + mime: StoredMime; + sizeBytes: number; + /** Hex SHA-256 of the bytes: the ETag. */ + sha256: string; + width: number; + height: number; +} + +export interface PutFile { + kind: StoredFileKind; + mime: StoredMime; + /** Already re-encoded by ImageService: never the uploaded bytes. */ + bytes: Buffer; + width: number; + height: number; +} + +/** + * Where images live (docs/files.md, decision S7). Callers use only this interface, never the + * files' tables (file-store-access.spec.ts checks it), so moving to R2/S3 later is a new + * implementation and a copy job, with no caller changes. Every method works in the current request's institute and + * transaction: a file another institute stored does not exist here. + */ +export interface FileStore { + /** + * Holds the institute's file lock until the transaction ends (put and delete take it too). + * Take it before reading which file a row points at and replacing or clearing it, so two + * changes of one image cannot both see the same old file (one would be left behind). + */ + lock(): Promise; + /** Stores a file; 413 STORAGE_FULL when the institute's total would pass its cap. */ + put(file: PutFile): Promise; + /** The file with its bytes, or null (unknown here). */ + get(id: string): Promise<(StoredFileMeta & { bytes: Buffer }) | null>; + /** The file without its bytes, or null. */ + meta(id: string): Promise; + /** Deletes a file (nothing may still point at it) and gives its size back to the total. */ + delete(id: string): Promise; + /** The institute's total and cap, in bytes. */ + usage(): Promise<{ bytesUsed: number; capBytes: number }>; +} + +export const FILE_STORE = Symbol('FILE_STORE'); diff --git a/apps/api/src/files/files.module.ts b/apps/api/src/files/files.module.ts new file mode 100644 index 0000000..9665f16 --- /dev/null +++ b/apps/api/src/files/files.module.ts @@ -0,0 +1,92 @@ +import { + Global, + Inject, + Injectable, + Module, + UseInterceptors, + applyDecorators, +} from '@nestjs/common'; +import { FileInterceptor } from '@nestjs/platform-express'; +import { UPLOAD_MAX_BYTES, type StoredFileKind } from '@jantrik/shared'; +import type { Request, Response } from 'express'; +import { apiError } from '../common/api-error.js'; +import { RequestContext } from '../common/request-context.js'; +import { RateLimiter } from '../redis/rate-limiter.service.js'; +import { FILE_STORE, type FileStore, type StoredFileMeta } from './file-store.js'; +import { ImageService } from './image.service.js'; +import { PostgresFileStore } from './postgres-file-store.js'; + +/** What multer hands over for the `file` field (memory storage). */ +export interface UploadedImage { + buffer: Buffer; +} + +/** Uploads per person per 10 minutes (decision F8): each one costs CPU to re-encode. */ +export const UPLOADS_PER_USER = 60; + +/** + * A multipart route with one image in the field `file`: at most UPLOAD_MAX_BYTES (bigger: 413), + * one file and no other fields. The type and name the browser sends are never trusted. + */ +export const ImageUpload = () => + applyDecorators( + UseInterceptors( + FileInterceptor('file', { limits: { fileSize: UPLOAD_MAX_BYTES, files: 1, fields: 0 } }), + ), + ); + +/** Upload → ImageService → FileStore, with the per-person limit. */ +@Injectable() +export class ImageUploads { + constructor( + @Inject(FILE_STORE) private readonly files: FileStore, + private readonly images: ImageService, + private readonly limiter: RateLimiter, + private readonly context: RequestContext, + ) {} + + async store(kind: StoredFileKind, upload: UploadedImage | undefined): Promise { + if (!upload?.buffer?.length) { + throw apiError(400, 'FILE_REQUIRED', 'Choose an image to upload', { field: 'file' }); + } + await this.limiter.consume({ + key: `file-upload:${this.context.requirePrincipal().userId}`, + limit: UPLOADS_PER_USER, + windowSec: 600, + }); + const image = await this.images.process(kind, upload.buffer); + return this.files.put({ kind, ...image }); + } +} + +/** + * Sends a stored image from an entity route (never /files/:id): a strong ETag (its SHA-256), + * `Cache-Control: private, no-cache`, and 304 for a matching If-None-Match without reading the + * bytes. 404 when there is no file. + */ +export async function sendStoredImage( + files: FileStore, + id: string | null, + req: Request, + res: Response, +): Promise { + const meta = id ? await files.meta(id) : null; + if (!meta) throw apiError(404, 'NOT_FOUND', 'No image'); + res.setHeader('ETag', `"${meta.sha256}"`); + res.setHeader('Cache-Control', 'private, no-cache'); + if (req.fresh) { + res.status(304).end(); + return; + } + const file = await files.get(meta.id); + if (!file) throw apiError(404, 'NOT_FOUND', 'No image'); + res.type(file.mime); + res.send(file.bytes); +} + +@Global() +@Module({ + providers: [ImageService, ImageUploads, { provide: FILE_STORE, useClass: PostgresFileStore }], + exports: [ImageService, ImageUploads, FILE_STORE], +}) +export class FilesModule {} diff --git a/apps/api/src/files/postgres-file-store.ts b/apps/api/src/files/postgres-file-store.ts new file mode 100644 index 0000000..724cd53 --- /dev/null +++ b/apps/api/src/files/postgres-file-store.ts @@ -0,0 +1,136 @@ +import { createHash } from 'node:crypto'; +import { Injectable, InternalServerErrorException } from '@nestjs/common'; +import { ConfigService } from '@nestjs/config'; +import { FILE_LIMITS, type StoredMime } from '@jantrik/shared'; +import { apiError } from '../common/api-error.js'; +import { RequestContext } from '../common/request-context.js'; +import type { Env } from '../config/env.js'; +import { Db } from '../tenancy/db.service.js'; +import type { FileStore, PutFile, StoredFileMeta } from './file-store.js'; + +const META = { + id: true, + kind: true, + mime: true, + sizeBytes: true, + sha256: true, + width: true, + height: true, +} as const; + +/** + * FileStore in Postgres (decision S7): stored_files under the same RLS as every tenant row, so the + * existing backups cover the files. The only code that touches stored_files and + * stored_file_usage (file-store-access.spec.ts). Works in the request's transaction: a file and + * the row that points at it commit or roll back together. + */ +@Injectable() +export class PostgresFileStore implements FileStore { + constructor( + private readonly db: Db, + private readonly context: RequestContext, + private readonly config: ConfigService, + ) {} + + private get capBytes(): number { + return this.config.get('FILE_STORAGE_PER_TENANT_MB', { infer: true }) * 1024 * 1024; + } + + /** + * The institute's lock: every put and delete holds it until commit, so two uploads at once + * cannot both pass the cap, and the total always equals the sum of the rows. + */ + async lock(): Promise { + await this.db.tx + .$executeRaw`SELECT pg_advisory_xact_lock(hashtextextended('stored-files:' || app_current_tenant_id()::text, 0))`; + } + + async put(file: PutFile): Promise { + const limit = FILE_LIMITS[file.kind]; + const size = file.bytes.length; + // ImageService guarantees these; reaching here otherwise is a bug, not a user error. + if (size === 0 || size > limit.maxBytes || !limit.mimes.includes(file.mime)) { + throw new InternalServerErrorException(`A ${file.kind} of ${size} bytes (${file.mime})`); + } + const tx = this.db.tx; + const tenantId = this.context.requireTenantId(); + await this.lock(); + const usage = await tx.storedFileUsage.upsert({ + where: { tenantId }, + create: { tenantId }, + update: {}, + select: { bytesUsed: true }, + }); + const capBytes = this.capBytes; + const bytesUsed = Number(usage.bytesUsed); + if (bytesUsed + size > capBytes) { + throw apiError(413, 'STORAGE_FULL', "The institute's storage for images is full", { + bytesUsed, + capBytes, + }); + } + const row = await tx.storedFile.create({ + data: { + tenantId, + kind: file.kind, + mime: file.mime, + bytes: new Uint8Array(file.bytes), + sizeBytes: size, + sha256: createHash('sha256').update(file.bytes).digest('hex'), + width: file.width, + height: file.height, + createdById: this.context.principal?.userId ?? null, + }, + select: META, + }); + await tx.storedFileUsage.update({ + where: { tenantId }, + data: { bytesUsed: { increment: size }, fileCount: { increment: 1 } }, + select: { id: true }, + }); + return toMeta(row); + } + + async get(id: string): Promise<(StoredFileMeta & { bytes: Buffer }) | null> { + const row = await this.db.tx.storedFile.findUnique({ + where: { id }, + select: { ...META, bytes: true }, + }); + if (!row) return null; + const { bytes, ...meta } = row; + return { ...toMeta(meta), bytes: Buffer.from(bytes) }; + } + + async meta(id: string): Promise { + const row = await this.db.tx.storedFile.findUnique({ where: { id }, select: META }); + return row ? toMeta(row) : null; + } + + async delete(id: string): Promise { + const tx = this.db.tx; + await this.lock(); + const row = await tx.storedFile.findUnique({ where: { id }, select: { sizeBytes: true } }); + if (!row) return; + await tx.storedFile.delete({ where: { id }, select: { id: true } }); + await tx.storedFileUsage.updateMany({ + data: { bytesUsed: { decrement: row.sizeBytes }, fileCount: { decrement: 1 } }, + }); + } + + async usage(): Promise<{ bytesUsed: number; capBytes: number }> { + const row = await this.db.tx.storedFileUsage.findFirst({ select: { bytesUsed: true } }); + return { bytesUsed: Number(row?.bytesUsed ?? 0), capBytes: this.capBytes }; + } +} + +function toMeta(row: { + id: string; + kind: StoredFileMeta['kind']; + mime: string; + sizeBytes: number; + sha256: string; + width: number; + height: number; +}): StoredFileMeta { + return { ...row, mime: row.mime as StoredMime }; +} From caec9f7ecf7c072924e871d004ebcb04dda10759 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:42 +0600 Subject: [PATCH 18/44] Photo and profile routes (P2 task 5): GET/PUT/DELETE /students/:id/photo (the photo is part of the full record: OWNER, ADMIN, a teacher of the student's section), GET /me/children/:id/photo (own children only), the institute profile with its logo (every member), head's signature and seal (OWNER, ADMIN); a replaced image's file is deleted in the same transaction and audited; photoUrl (never written) becomes photoId in every API type Co-Authored-By: Claude Opus 5.5 --- apps/api/src/app.module.ts | 4 + .../src/exams/results/exam-results.service.ts | 5 +- apps/api/src/exams/seats/seat-plan.service.ts | 9 +- .../src/institute/institute-profile.module.ts | 283 ++++++++++++++++++ apps/api/src/me/me.module.ts | 48 ++- .../api/src/students/student-admin.service.ts | 4 +- .../api/src/students/student-photo.service.ts | 107 +++++++ apps/api/src/students/students.module.ts | 40 ++- apps/api/test/files.e2e-spec.ts | 251 ++++++++++++++++ apps/api/test/institute-profile.e2e-spec.ts | 181 +++++++++++ packages/shared/src/api.ts | 6 +- packages/shared/src/exams-api.ts | 4 +- packages/shared/src/files-schema.ts | 35 +-- packages/shared/src/files.test.ts | 8 +- packages/shared/src/files.ts | 27 ++ packages/shared/src/students.ts | 3 +- 16 files changed, 970 insertions(+), 45 deletions(-) create mode 100644 apps/api/src/institute/institute-profile.module.ts create mode 100644 apps/api/src/students/student-photo.service.ts create mode 100644 apps/api/test/files.e2e-spec.ts create mode 100644 apps/api/test/institute-profile.e2e-spec.ts diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts index 8343465..e447db3 100644 --- a/apps/api/src/app.module.ts +++ b/apps/api/src/app.module.ts @@ -10,6 +10,7 @@ import { AuthModule } from './auth/auth.module.js'; import { DevicesModule } from './devices/devices.module.js'; import { ExamsModule } from './exams/exams.module.js'; import { FeesModule } from './fees/fees.module.js'; +import { FilesModule } from './files/files.module.js'; import { JwtAuthGuard, ModuleGuard, @@ -22,6 +23,7 @@ import { ZodValidationPipe } from './common/zod.js'; import { validateEnv, type Env } from './config/env.js'; import { HealthModule } from './health/health.module.js'; import { ImportsModule } from './imports/imports.module.js'; +import { InstituteProfileModule } from './institute/institute-profile.module.js'; import { MeModule } from './me/me.module.js'; import { PrismaModule } from './prisma/prisma.module.js'; import { RedisModule } from './redis/redis.module.js'; @@ -60,11 +62,13 @@ import { TenantContextInterceptor } from './tenancy/tenant-context.interceptor.j PrismaModule, TenancyModule, AuditModule, + FilesModule, SmsModule, AuthModule, HealthModule, MeModule, AppearanceModule, + InstituteProfileModule, StudentsModule, SetupModule, StaffModule, diff --git a/apps/api/src/exams/results/exam-results.service.ts b/apps/api/src/exams/results/exam-results.service.ts index f33f0ea..12200a9 100644 --- a/apps/api/src/exams/results/exam-results.service.ts +++ b/apps/api/src/exams/results/exam-results.service.ts @@ -455,7 +455,7 @@ export class ExamResultsService { studentCode: true, nameBn: true, nameEn: true, - photoUrl: true, + photoFileId: true, fatherNameBn: true, fatherNameEn: true, motherNameBn: true, @@ -490,7 +490,8 @@ export class ExamResultsService { studentCode: st.studentCode, nameBn: st.nameBn, nameEn: st.nameEn, - photoUrl: st.photoUrl, + // The photo is part of the full record (as on the student's page). + photoId: sees ? st.photoFileId : null, fatherNameBn: sees ? st.fatherNameBn : null, fatherNameEn: sees ? st.fatherNameEn : null, motherNameBn: sees ? st.motherNameBn : null, diff --git a/apps/api/src/exams/seats/seat-plan.service.ts b/apps/api/src/exams/seats/seat-plan.service.ts index d76a9fc..0e7b249 100644 --- a/apps/api/src/exams/seats/seat-plan.service.ts +++ b/apps/api/src/exams/seats/seat-plan.service.ts @@ -178,7 +178,7 @@ export class SeatPlanService { }, orderBy: [{ section: { name: 'asc' } }, { roll: 'asc' }], include: { - student: { select: { studentCode: true, nameBn: true, nameEn: true, photoUrl: true } }, + student: { select: { studentCode: true, nameBn: true, nameEn: true, photoFileId: true } }, section: { select: { id: true, name: true } }, studyGroup: { select: { id: true, code: true, nameBn: true, nameEn: true } }, room: { select: { name: true } }, @@ -219,7 +219,12 @@ export class SeatPlanService { ); return { candidateId: c.id, - student: c.student, + student: { + studentCode: c.student.studentCode, + nameBn: c.student.nameBn, + nameEn: c.student.nameEn, + photoId: c.student.photoFileId, + }, classLevel: c.examClass.classLevel, section: c.section, studyGroup: c.studyGroup, diff --git a/apps/api/src/institute/institute-profile.module.ts b/apps/api/src/institute/institute-profile.module.ts new file mode 100644 index 0000000..948a864 --- /dev/null +++ b/apps/api/src/institute/institute-profile.module.ts @@ -0,0 +1,283 @@ +import { + Body, + Controller, + Delete, + Get, + Inject, + Injectable, + Module, + Param, + ParseEnumPipe, + Put, + Req, + Res, + UploadedFile, +} from '@nestjs/common'; +import type { Prisma } from '@jantrik/db'; +import { + INSTITUTE_IMAGE_KIND, + INSTITUTE_IMAGE_SLOTS, + instituteProfileSchema, + type FileRef, + type InstituteImageSlot, + type InstituteProfile, + type InstituteProfileFields, +} from '@jantrik/shared'; +import type { Request, Response } from 'express'; +import { AuditService } from '../audit/audit.module.js'; +import { RequireModule, Roles } from '../common/decorators.js'; +import { RequestContext } from '../common/request-context.js'; +import { zodDto } from '../common/zod.js'; +import { FILE_STORE, type FileStore, type StoredFileMeta } from '../files/file-store.js'; +import { + ImageUpload, + ImageUploads, + sendStoredImage, + type UploadedImage, +} from '../files/files.module.js'; +import { Db } from '../tenancy/db.service.js'; + +class InstituteProfileDto extends zodDto(instituteProfileSchema) {} + +/** The profile column holding each slot's file. */ +const COLUMN = { + logo: 'logoFileId', + signature: 'headSignatureFileId', + seal: 'sealFileId', +} as const satisfies Record; + +const FIELDS = [ + 'nameBn', + 'nameEn', + 'shortName', + 'eiin', + 'addressBn', + 'addressEn', + 'phone', + 'email', + 'website', + 'headTitleBn', + 'headTitleEn', + 'headNameBn', + 'headNameEn', + 'establishedYear', +] as const satisfies readonly (keyof InstituteProfileFields)[]; + +const BANGLA = /[ঀ-৿]/; + +/** + * The institute's own profile (sprint 1 P2, docs/files.md): names, EIIN, contact, the head of the + * institute, and three images. One row per institute, created on the first save or image (no + * backfill). Every change is audited; images through FileStore only. + */ +@Injectable() +export class InstituteProfileService { + constructor( + private readonly db: Db, + private readonly context: RequestContext, + private readonly audit: AuditService, + private readonly uploads: ImageUploads, + @Inject(FILE_STORE) private readonly files: FileStore, + ) {} + + private row() { + return this.db.tx.instituteProfile.findFirst(); + } + + async get(): Promise { + const tenant = await this.db.tx.tenant.findFirstOrThrow({ + where: { id: this.context.requireTenantId() }, + select: { name: true }, + }); + const row = await this.row(); + const ref = async (id: string | null | undefined): Promise => { + const meta = id ? await this.files.meta(id) : null; + return meta ? fileRef(meta) : null; + }; + const fields = Object.fromEntries( + FIELDS.map((f) => [f, row?.[f] ?? null]), + ) as unknown as InstituteProfileFields; + return { + ...fields, + saved: row !== null, + registeredName: tenant.name, + logo: await ref(row?.logoFileId), + signature: await ref(row?.headSignatureFileId), + seal: await ref(row?.sealFileId), + storage: await this.files.usage(), + }; + } + + async update(input: InstituteProfileFields): Promise { + const tenantId = this.context.requireTenantId(); + const before = await this.row(); + const data = Object.fromEntries( + FIELDS.map((f) => [f, input[f]]), + ) as unknown as InstituteProfileFields; + const old = before ? Object.fromEntries(FIELDS.map((f) => [f, before[f]])) : null; + const changed = !old || FIELDS.some((f) => old[f] !== data[f]); + if (changed) { + const row = await this.db.tx.instituteProfile.upsert({ + where: { tenantId }, + create: { tenantId, ...data }, + update: data, + select: { id: true }, + }); + await this.audit.record({ + entity: 'institute_profile', + entityId: row.id, + action: before ? 'UPDATE' : 'CREATE', + ...(old ? { oldValues: old } : {}), + newValues: data as unknown as Prisma.InputJsonValue, + }); + } + return this.get(); + } + + /** + * Sets (or replaces) one image; the replaced file is deleted in the same transaction (F10). The + * store holds the institute's file lock from here to commit, so the old id read below is final. + */ + async setImage(slot: InstituteImageSlot, upload: UploadedImage | undefined) { + const stored = await this.uploads.store(INSTITUTE_IMAGE_KIND[slot], upload); + const profile = await this.ensureRow(); + const oldId = profile[COLUMN[slot]]; + await this.db.tx.instituteProfile.update({ + where: { id: profile.id }, + data: { [COLUMN[slot]]: stored.id }, + select: { id: true }, + }); + if (oldId) await this.files.delete(oldId); + await this.audit.record({ + entity: 'institute_profile', + entityId: profile.id, + action: 'UPDATE', + oldValues: { image: slot, fileId: oldId }, + newValues: { image: slot, fileId: stored.id }, + }); + return this.get(); + } + + async removeImage(slot: InstituteImageSlot): Promise { + await this.files.lock(); + const profile = await this.row(); + const oldId = profile?.[COLUMN[slot]]; + if (profile && oldId) { + await this.db.tx.instituteProfile.update({ + where: { id: profile.id }, + data: { [COLUMN[slot]]: null }, + select: { id: true }, + }); + await this.files.delete(oldId); + await this.audit.record({ + entity: 'institute_profile', + entityId: profile.id, + action: 'UPDATE', + oldValues: { image: slot, fileId: oldId }, + newValues: { image: slot, fileId: null }, + }); + } + return this.get(); + } + + /** The image's file id for serving, or null. */ + async imageId(slot: InstituteImageSlot): Promise { + return (await this.row())?.[COLUMN[slot]] ?? null; + } + + /** + * The profile row, created for an image uploaded before the first save (F6) with the + * registered name in the matching script, so the "one name" CHECK holds. + */ + private async ensureRow() { + const existing = await this.row(); + if (existing) return existing; + const tenantId = this.context.requireTenantId(); + const { name } = await this.db.tx.tenant.findFirstOrThrow({ + where: { id: tenantId }, + select: { name: true }, + }); + const names = BANGLA.test(name) + ? { nameBn: name.slice(0, 200) } + : { nameEn: name.slice(0, 200) }; + const row = await this.db.tx.instituteProfile.create({ data: { tenantId, ...names } }); + await this.audit.record({ + entity: 'institute_profile', + entityId: row.id, + action: 'CREATE', + newValues: names, + }); + return row; + } +} + +function fileRef(meta: StoredFileMeta): FileRef { + return { + id: meta.id, + mime: meta.mime, + sizeBytes: meta.sizeBytes, + width: meta.width, + height: meta.height, + }; +} + +const Slot = () => Param('slot', new ParseEnumPipe(INSTITUTE_IMAGE_SLOTS)); + +@Controller('institute/profile') +@RequireModule('CORE') +export class InstituteProfileController { + constructor( + private readonly profile: InstituteProfileService, + @Inject(FILE_STORE) private readonly files: FileStore, + ) {} + + @Get() + @Roles('OWNER', 'ADMIN') + get(): Promise { + return this.profile.get(); + } + + @Put() + @Roles('OWNER', 'ADMIN') + update(@Body() dto: InstituteProfileDto): Promise { + return this.profile.update(dto as unknown as InstituteProfileFields); + } + + /** The logo is the institute's public face: every member may see it, guardians too (F1). */ + @Get('logo') + @Roles('OWNER', 'ADMIN', 'TEACHER', 'ACCOUNTANT', 'STAFF', 'GUARDIAN') + async logo(@Req() req: Request, @Res() res: Response): Promise { + await sendStoredImage(this.files, await this.profile.imageId('logo'), req, res); + } + + /** The head's signature and the seal could be misused on forged papers: owner and admin (F1). */ + @Get(':slot') + @Roles('OWNER', 'ADMIN') + async image( + @Slot() slot: InstituteImageSlot, + @Req() req: Request, + @Res() res: Response, + ): Promise { + await sendStoredImage(this.files, await this.profile.imageId(slot), req, res); + } + + /** multipart/form-data with `file` (JPEG, PNG or WebP, at most 5 MB). */ + @Put(':slot') + @Roles('OWNER', 'ADMIN') + @ImageUpload() + setImage( + @Slot() slot: InstituteImageSlot, + @UploadedFile() file: UploadedImage | undefined, + ): Promise { + return this.profile.setImage(slot, file); + } + + @Delete(':slot') + @Roles('OWNER', 'ADMIN') + removeImage(@Slot() slot: InstituteImageSlot): Promise { + return this.profile.removeImage(slot); + } +} + +@Module({ controllers: [InstituteProfileController], providers: [InstituteProfileService] }) +export class InstituteProfileModule {} diff --git a/apps/api/src/me/me.module.ts b/apps/api/src/me/me.module.ts index feea0a2..d4114da 100644 --- a/apps/api/src/me/me.module.ts +++ b/apps/api/src/me/me.module.ts @@ -2,14 +2,18 @@ import { Body, Controller, ForbiddenException, + NotFoundException, Get, HttpCode, + Inject, Injectable, Module, Param, ParseUUIDPipe, Patch, Post, + Req, + Res, } from '@nestjs/common'; import { acceptInvitationSchema, @@ -24,11 +28,14 @@ import { type StaffInvitation, type ColorScheme, } from '@jantrik/shared'; +import type { Request, Response } from 'express'; import { appearanceOf } from '../appearance/appearance.module.js'; import { listMemberships } from '../auth/login-lookup.js'; import { CurrentUser, RequireModule, Roles, UserScoped } from '../common/decorators.js'; import type { Principal } from '../common/request-context.js'; import { zodDto } from '../common/zod.js'; +import { FILE_STORE, type FileStore } from '../files/file-store.js'; +import { sendStoredImage } from '../files/files.module.js'; import { Db } from '../tenancy/db.service.js'; import { TenantAccessService } from '../tenancy/tenant-access.service.js'; @@ -136,7 +143,7 @@ export class MeService { studentCode: true, nameBn: true, nameEn: true, - photoUrl: true, + photoFileId: true, status: true, enrolments: { where: { academicYearId: year?.id ?? '00000000-0000-0000-0000-000000000000' }, @@ -153,13 +160,30 @@ export class MeService { }); // A person can be linked twice to one child (two guardian records); show the child once. const seen = new Set(); - return links.flatMap(({ relation, student: { enrolments, ...s } }) => { + return links.flatMap(({ relation, student: { enrolments, photoFileId, ...s } }) => { if (seen.has(s.id)) return []; seen.add(s.id); - return [{ ...s, relation, enrolment: enrolments[0] ?? null }]; + return [{ ...s, photoId: photoFileId, relation, enrolment: enrolments[0] ?? null }]; }); } + /** + * The photo's file id of one of the caller's own children (GET /me/children/:id/photo); 404 for + * any other student, as GET /me/children lists them (sprint 1 P2, decision F1). + */ + async childPhotoId(principal: Principal, studentId: string): Promise { + const link = await this.db.tx.studentGuardian.findFirst({ + where: { + studentId, + guardian: { userId: principal.userId }, + student: { deletedAt: null }, + }, + select: { student: { select: { photoFileId: true } } }, + }); + if (!link) throw new NotFoundException('Student not found'); + return link.student.photoFileId; + } + /** The caller's pending (not expired) staff invitations, from the membership definer function. */ async invitations(): Promise { const memberships = await listMemberships(this.db.tx); @@ -211,7 +235,10 @@ export class MeService { @Controller('me') export class MeController { - constructor(private readonly me: MeService) {} + constructor( + private readonly me: MeService, + @Inject(FILE_STORE) private readonly files: FileStore, + ) {} @Get('context') context(@CurrentUser() principal: Principal): Promise { @@ -232,6 +259,19 @@ export class MeController { return this.me.children(principal); } + /** One of the caller's own children's photo (the image, 404 for anyone else's child). */ + @Get('children/:id/photo') + @RequireModule('CORE') + @Roles('GUARDIAN') + async childPhoto( + @CurrentUser() principal: Principal, + @Param('id', ParseUUIDPipe) id: string, + @Req() req: Request, + @Res() res: Response, + ): Promise { + await sendStoredImage(this.files, await this.me.childPhotoId(principal, id), req, res); + } + /** Pending staff invitations (no institute needs to be selected). */ @Get('invitations') @UserScoped() diff --git a/apps/api/src/students/student-admin.service.ts b/apps/api/src/students/student-admin.service.ts index 7cdaf83..8a88db2 100644 --- a/apps/api/src/students/student-admin.service.ts +++ b/apps/api/src/students/student-admin.service.ts @@ -300,7 +300,7 @@ export class StudentAdminService { motherNameEn: null, presentAddress: null, permanentAddress: null, - photoUrl: null, + photoId: null, guardians: [], // The basics: the current class/section/roll, not the history. enrolments: current ? [current] : [], @@ -361,7 +361,7 @@ export class StudentAdminService { motherNameEn: s.motherNameEn, presentAddress: s.presentAddress, permanentAddress: s.permanentAddress, - photoUrl: s.photoUrl, + photoId: s.photoFileId, status: s.status, deletedAt: s.deletedAt?.toISOString() ?? null, createdAt: s.createdAt.toISOString(), diff --git a/apps/api/src/students/student-photo.service.ts b/apps/api/src/students/student-photo.service.ts new file mode 100644 index 0000000..11fb80b --- /dev/null +++ b/apps/api/src/students/student-photo.service.ts @@ -0,0 +1,107 @@ +import { Inject, Injectable } from '@nestjs/common'; +import type { StudentProfile } from '@jantrik/shared'; +import { AuditService } from '../audit/audit.module.js'; +import { apiError } from '../common/api-error.js'; +import { FILE_STORE, type FileStore } from '../files/file-store.js'; +import { ImageUploads, type UploadedImage } from '../files/files.module.js'; +import { Db } from '../tenancy/db.service.js'; +import { StudentAccess } from './student-access.service.js'; +import { StudentAdminService } from './student-admin.service.js'; + +/** + * A student's photo (sprint 1 P2, docs/files.md): one STUDENT_PHOTO file per student, replaced + * or removed by OWNER/ADMIN, seen by those who see the student's full record (decision F1). A replaced + * photo's file is deleted in the same transaction (F10); the audit keeps both ids. + */ +@Injectable() +export class StudentPhotoService { + constructor( + private readonly db: Db, + private readonly admin: StudentAdminService, + private readonly access: StudentAccess, + private readonly uploads: ImageUploads, + private readonly audit: AuditService, + @Inject(FILE_STORE) private readonly files: FileStore, + ) {} + + /** The photo's file id for GET /students/:id/photo (404 when the caller may not see it). */ + async photoId(studentId: string): Promise { + const s = await this.db.tx.student.findUnique({ + where: { id: studentId }, + select: { + photoFileId: true, + deletedAt: true, + enrolments: { where: { academicYear: { isCurrent: true } }, select: { sectionId: true } }, + }, + }); + if (!s) throw apiError(404, 'NOT_FOUND', 'Student not found'); + // The photo is part of the full record (GET /students/:id leaves it out of a teacher's basic + // view): OWNER/ADMIN, or a teacher of the student's current section; a deactivated student's + // only for OWNER/ADMIN (F1, F9). Anyone else gets 404, as for a student that does not exist. + const scope = await this.access.scope(); + const current = s.enrolments[0]?.sectionId ?? null; + if (!scope.full && (s.deletedAt || !StudentAccess.sees(scope, current))) { + throw apiError(404, 'NOT_FOUND', 'Student not found'); + } + return s.photoFileId; + } + + async set(studentId: string, upload: UploadedImage | undefined): Promise { + await this.writable(studentId); + // The store holds the institute's file lock from here to commit: the old id read next is final. + const stored = await this.uploads.store('STUDENT_PHOTO', upload); + const old = await this.current(studentId); + await this.db.tx.student.update({ + where: { id: studentId }, + data: { photoFileId: stored.id }, + select: { id: true }, + }); + if (old) await this.files.delete(old); + await this.record(studentId, old, stored.id); + return this.admin.view(studentId); + } + + async remove(studentId: string): Promise { + await this.writable(studentId); + await this.files.lock(); + const old = await this.current(studentId); + if (old) { + await this.db.tx.student.update({ + where: { id: studentId }, + data: { photoFileId: null }, + select: { id: true }, + }); + await this.files.delete(old); + await this.record(studentId, old, null); + } + return this.admin.view(studentId); + } + + private async current(studentId: string): Promise { + const s = await this.db.tx.student.findUniqueOrThrow({ + where: { id: studentId }, + select: { photoFileId: true }, + }); + return s.photoFileId; + } + + /** 404 for a student this institute does not have; 409 for a deactivated one (F9). */ + private async writable(studentId: string): Promise { + const s = await this.db.tx.student.findUnique({ + where: { id: studentId }, + select: { deletedAt: true }, + }); + if (!s) throw apiError(404, 'NOT_FOUND', 'Student not found'); + if (s.deletedAt) throw apiError(409, 'DEACTIVATED', 'This student is deactivated'); + } + + private record(studentId: string, oldId: string | null, newId: string | null) { + return this.audit.record({ + entity: 'student', + entityId: studentId, + action: 'UPDATE', + oldValues: { photoFileId: oldId }, + newValues: { photoFileId: newId }, + }); + } +} diff --git a/apps/api/src/students/students.module.ts b/apps/api/src/students/students.module.ts index 6b0ca9f..0f0e660 100644 --- a/apps/api/src/students/students.module.ts +++ b/apps/api/src/students/students.module.ts @@ -4,6 +4,7 @@ import { Delete, Get, HttpCode, + Inject, Injectable, Module, Param, @@ -12,6 +13,9 @@ import { Post, Put, Query, + Req, + Res, + UploadedFile, } from '@nestjs/common'; import { searchStudentIds, type Prisma } from '@jantrik/db'; import { @@ -38,13 +42,17 @@ import { type StudentsPage, type StudentsSummary, } from '@jantrik/shared'; +import type { Request, Response } from 'express'; import { RequireModule, Roles } from '../common/decorators.js'; import { zodDto } from '../common/zod.js'; +import { FILE_STORE, type FileStore } from '../files/file-store.js'; +import { ImageUpload, sendStoredImage, type UploadedImage } from '../files/files.module.js'; import { Db } from '../tenancy/db.service.js'; import { GuardianLinker } from './guardian-linker.service.js'; import { StudentAdminService } from './student-admin.service.js'; import { StudentAccess } from './student-access.service.js'; import { StudentCodesService } from './student-codes.service.js'; +import { StudentPhotoService } from './student-photo.service.js'; export class StudentsQueryDto extends zodDto(studentsQuerySchema) {} class AdmissionDto extends zodDto(admissionSchema) {} @@ -156,7 +164,7 @@ export class StudentsService { nameBn: true, nameEn: true, status: true, - photoUrl: true, + photoFileId: true, enrolments: { where: { academicYearId: yearId }, take: 1, @@ -178,8 +186,10 @@ export class StudentsService { rows.sort((a, b) => at.get(a.id)! - at.get(b.id)!); } - const items: StudentListItem[] = rows.map(({ enrolments, guardians, ...s }) => ({ + const items: StudentListItem[] = rows.map(({ enrolments, guardians, photoFileId, ...s }) => ({ ...s, + // The photo is part of the full record (as on the student's page). + photoId: StudentAccess.sees(scope, enrolments[0]?.section?.id) ? photoFileId : null, enrolment: enrolments[0] ?? null, primaryGuardian: StudentAccess.sees(scope, enrolments[0]?.section?.id) ? (guardians[0]?.guardian ?? null) @@ -332,6 +342,8 @@ export class StudentsController { private readonly students: StudentsService, private readonly admin: StudentAdminService, private readonly codes: StudentCodesService, + private readonly photos: StudentPhotoService, + @Inject(FILE_STORE) private readonly files: FileStore, ) {} @Get() @@ -380,6 +392,29 @@ export class StudentsController { return this.admin.update(id, dto); } + /** The student's photo (JPEG), for everyone who may read students (decision F1). */ + @Get(':id/photo') + async photo(@Id() id: string, @Req() req: Request, @Res() res: Response): Promise { + await sendStoredImage(this.files, await this.photos.photoId(id), req, res); + } + + /** multipart/form-data with `file` (JPEG, PNG or WebP, at most 5 MB); stored as a JPEG. */ + @Put(':id/photo') + @Roles('OWNER', 'ADMIN') + @ImageUpload() + setPhoto( + @Id() id: string, + @UploadedFile() file: UploadedImage | undefined, + ): Promise { + return this.photos.set(id, file); + } + + @Delete(':id/photo') + @Roles('OWNER', 'ADMIN') + removePhoto(@Id() id: string): Promise { + return this.photos.remove(id); + } + @Post(':id/guardians') @Roles('OWNER', 'ADMIN') addGuardian(@Id() id: string, @Body() dto: AddGuardianDto): Promise { @@ -445,6 +480,7 @@ export class GuardiansController { StudentsService, StudentAdminService, StudentCodesService, + StudentPhotoService, GuardianLinker, StudentAccess, ], diff --git a/apps/api/test/files.e2e-spec.ts b/apps/api/test/files.e2e-spec.ts new file mode 100644 index 0000000..7fa7d09 --- /dev/null +++ b/apps/api/test/files.e2e-spec.ts @@ -0,0 +1,251 @@ +import { crc32, deflateSync } from 'node:zlib'; +import { withTenant } from '@jantrik/db'; +import type { GuardianChild, StudentProfile } from '@jantrik/shared'; +import sharp from 'sharp'; +import { + addMember, + bearer, + createHarness, + createTenant, + http, + otpLogin, + type Harness, +} from './support/harness.js'; +import { school, type School } from './support/school.js'; + +// Sprint 1 P2 (docs/plans/sprint-1-p2-files.md): student photos through FileStore. Who may see +// and change them, the hostile uploads, ETag/304, the per-institute total and its cap. + +const CAP = 1024 * 1024 * 1024; // FILE_STORAGE_PER_TENANT_MB's default, in bytes + +const photo = (w = 300, h = 400, background = '#88aa55') => + sharp({ create: { width: w, height: h, channels: 3, background } }) + .jpeg() + .toBuffer(); + +function pngClaiming(width: number, height: number): Buffer { + const chunk = (type: string, data: Buffer) => { + const len = Buffer.alloc(4); + len.writeUInt32BE(data.length); + const body = Buffer.concat([Buffer.from(type, 'latin1'), data]); + const crc = Buffer.alloc(4); + crc.writeUInt32BE(crc32(body)); + return Buffer.concat([len, body, crc]); + }; + const ihdr = Buffer.alloc(13); + ihdr.writeUInt32BE(width, 0); + ihdr.writeUInt32BE(height, 4); + ihdr[8] = 8; + return Buffer.concat([ + Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), + chunk('IHDR', ihdr), + chunk('IDAT', deflateSync(Buffer.alloc(width + 1))), + chunk('IEND', Buffer.alloc(0)), + ]); +} + +describe('student photos', () => { + let h: Harness; + let s: School; + let owner: string; + + const put = (token: string, studentId: string, file: Buffer, name = 'photo.jpg') => + http(h) + .put(`/students/${studentId}/photo`) + .set(bearer(token)) + .attach('file', file, { filename: name, contentType: 'image/jpeg' }); + const usage = (tenantId: string) => + withTenant(h.prisma, tenantId, async (tx) => { + const row = await tx.storedFileUsage.findFirst(); + const files = await tx.storedFile.findMany({ select: { sizeBytes: true } }); + return { + bytesUsed: Number(row?.bytesUsed ?? 0), + fileCount: row?.fileCount ?? 0, + sum: files.reduce((n, f) => n + f.sizeBytes, 0), + count: files.length, + }; + }); + + beforeAll(async () => { + h = await createHarness(); + s = await school(h); + owner = (await otpLogin(h, (await addMember(h, s.tenantId, { roles: ['OWNER'] })).phone)) + .accessToken; + }); + + afterAll(() => h.close()); + + it('an admin adds a photo: stored as a JPEG, served with an ETag, 304 when unchanged', async () => { + const student = s.a[0]!.id; + const res = await put(s.admin, student, await photo(1200, 1600)).expect(200); + const profile = res.body as StudentProfile; + expect(profile.photoId).toMatch(/^[0-9a-f-]{36}$/); + + const got = await http(h) + .get(`/students/${student}/photo`) + .set(bearer(s.admin)) + .buffer(true) + .expect(200); + expect(got.headers['content-type']).toBe('image/jpeg'); + expect(got.headers['cache-control']).toBe('private, no-cache'); + expect(got.headers['etag']).toMatch(/^"[0-9a-f]{64}"$/); + const meta = await sharp(got.body as Buffer).metadata(); + expect([meta.format, meta.width, meta.height]).toEqual(['jpeg', 600, 800]); + + await http(h) + .get(`/students/${student}/photo`) + .set(bearer(s.admin)) + .set('If-None-Match', got.headers['etag']!) + .expect(304); + + // The list and the profile carry the id; the audit has the change. + const listed = await http(h).get('/students').set(bearer(s.admin)).expect(200); + const row = (listed.body.items as { id: string; photoId: string | null }[]).find( + (i) => i.id === student, + ); + expect(row?.photoId).toBe(profile.photoId); + const audit = await withTenant(h.prisma, s.tenantId, (tx) => + tx.auditLog.findMany({ where: { entity: 'student', entityId: student } }), + ); + expect(audit.at(-1)).toMatchObject({ + action: 'UPDATE', + oldValues: { photoFileId: null }, + newValues: { photoFileId: profile.photoId }, + }); + }); + + it('teachers see the photo only for their own section; others get 403 or 404', async () => { + const student = s.a[0]!.id; + await http(h).get(`/students/${student}/photo`).set(bearer(s.teacher)).expect(200); + await http(h).get(`/students/${student}/photo`).set(bearer(s.otherTeacher)).expect(404); + const listed = await http(h).get('/students').set(bearer(s.otherTeacher)).expect(200); + for (const item of listed.body.items as { photoId: string | null }[]) { + expect(item.photoId).toBeNull(); + } + const accountant = await otpLogin( + h, + (await addMember(h, s.tenantId, { roles: ['ACCOUNTANT'] })).phone, + ); + await http(h).get(`/students/${student}/photo`).set(bearer(accountant.accessToken)).expect(403); + await put(s.teacher, student, await photo()).expect(403); + await http(h).delete(`/students/${student}/photo`).set(bearer(s.teacher)).expect(403); + }); + + it("another institute's admin gets 404 for this institute's student", async () => { + const other = await createTenant(h); + const admin = (await otpLogin(h, (await addMember(h, other.id, { roles: ['ADMIN'] })).phone)) + .accessToken; + const student = s.a[0]!.id; + await http(h).get(`/students/${student}/photo`).set(bearer(admin)).expect(404); + await put(admin, student, await photo()).expect(404); + await http(h).delete(`/students/${student}/photo`).set(bearer(admin)).expect(404); + expect((await usage(other.id)).count).toBe(0); + }); + + it("a guardian sees their own child's photo, and no one else's", async () => { + const child = s.a[1]!; + await put(s.admin, child.id, await photo()).expect(200); + await put(s.admin, s.a[2]!.id, await photo()).expect(200); + const m = await addMember(h, s.tenantId, { phone: child.phone, roles: ['GUARDIAN'] }); + await withTenant(h.prisma, s.tenantId, (tx) => + tx.guardian.updateMany({ where: { phone: child.phone }, data: { userId: m.userId } }), + ); + const guardian = (await otpLogin(h, m.phone)).accessToken; + const children = (await http(h).get('/me/children').set(bearer(guardian)).expect(200)) + .body as GuardianChild[]; + expect(children.map((c) => [c.id, typeof c.photoId])).toEqual([[child.id, 'string']]); + const got = await http(h) + .get(`/me/children/${child.id}/photo`) + .set(bearer(guardian)) + .buffer(true) + .expect(200); + expect(got.headers['content-type']).toBe('image/jpeg'); + await http(h).get(`/me/children/${s.a[2]!.id}/photo`).set(bearer(guardian)).expect(404); + await http(h).get(`/students/${child.id}/photo`).set(bearer(guardian)).expect(403); + }); + + it('replacing deletes the old file and removing deletes it too; the total follows', async () => { + const student = s.b[0]!.id; + const before = await usage(s.tenantId); + const first = (await put(owner, student, await photo(300, 400, '#112233')).expect(200)) + .body as StudentProfile; + const second = (await put(owner, student, await photo(300, 400, '#445566')).expect(200)) + .body as StudentProfile; + expect(second.photoId).not.toBe(first.photoId); + let now = await usage(s.tenantId); + expect(now.count).toBe(before.count + 1); + expect(now.bytesUsed).toBe(now.sum); + expect(now.fileCount).toBe(now.count); + + const removed = ( + await http(h).delete(`/students/${student}/photo`).set(bearer(owner)).expect(200) + ).body as StudentProfile; + expect(removed.photoId).toBeNull(); + await http(h).get(`/students/${student}/photo`).set(bearer(owner)).expect(404); + now = await usage(s.tenantId); + expect([now.count, now.bytesUsed]).toEqual([before.count, before.bytesUsed]); + expect(now.bytesUsed).toBe(now.sum); + }); + + it('hostile uploads are refused and leave nothing behind', async () => { + const student = s.b[0]!.id; + const before = await usage(s.tenantId); + const tooBig = Buffer.concat([Buffer.from([0xff, 0xd8, 0xff]), Buffer.alloc(6 * 1024 * 1024)]); + await put(s.admin, student, tooBig).expect(413); + const text = await put(s.admin, student, Buffer.from('not an image at all'), 'x.jpg').expect( + 422, + ); + expect(text.body.code).toBe('IMAGE_INVALID'); + const bomb = await put(s.admin, student, pngClaiming(50_000, 50_000), 'bomb.png').expect(422); + expect(bomb.body.code).toBe('IMAGE_TOO_BIG'); + await http(h) + .put(`/students/${student}/photo`) + .set(bearer(s.admin)) + .expect(400) + .expect((r) => expect(r.body.code).toBe('FILE_REQUIRED')); + expect(await usage(s.tenantId)).toEqual(before); + }); + + it('a deactivated student cannot get a new photo (409)', async () => { + const t = await school(h); + const student = t.b[0]!.id; + await http(h).post(`/students/${student}/deactivate`).set(bearer(t.admin)).expect(200); + const res = await put(t.admin, student, await photo()).expect(409); + expect(res.body.code).toBe('DEACTIVATED'); + }); + + it('over the institute cap: 413 STORAGE_FULL; two uploads at once when one fits: exactly one', async () => { + const t = await school(h); + // The size of one processed photo, measured on the first upload. + const image = await photo(900, 1200, '#336699'); + await put(t.admin, t.a[0]!.id, image).expect(200); + const size = (await usage(t.tenantId)).bytesUsed; + expect(size).toBeGreaterThan(0); + + // Room for one more of these, not two. + const preset = CAP - size - Math.floor(size * 1.5); + await withTenant(h.prisma, t.tenantId, (tx) => + tx.storedFileUsage.updateMany({ data: { bytesUsed: { increment: preset } } }), + ); + const results = await Promise.all([ + put(t.admin, t.a[1]!.id, image), + put(t.admin, t.a[2]!.id, image), + ]); + expect(results.map((r) => r.status).sort()).toEqual([200, 413]); + expect(results.find((r) => r.status === 413)!.body.code).toBe('STORAGE_FULL'); + const now = await usage(t.tenantId); + expect(now.count).toBe(2); + expect(now.bytesUsed).toBe(now.sum + preset); + // Full now: a third is refused. + const third = await put(t.admin, t.b[0]!.id, image).expect(413); + expect(third.body).toMatchObject({ code: 'STORAGE_FULL', capBytes: CAP }); + }); + + it('at most 60 uploads per person in 10 minutes (F8)', async () => { + const t = await school(h); + const tiny = await photo(20, 20); + for (let i = 0; i < 60; i++) await put(t.admin, t.b[0]!.id, tiny).expect(200); + const res = await put(t.admin, t.b[0]!.id, tiny).expect(429); + expect(Number(res.headers['retry-after'])).toBeGreaterThan(0); + }, 90_000); +}); diff --git a/apps/api/test/institute-profile.e2e-spec.ts b/apps/api/test/institute-profile.e2e-spec.ts new file mode 100644 index 0000000..53850af --- /dev/null +++ b/apps/api/test/institute-profile.e2e-spec.ts @@ -0,0 +1,181 @@ +import { withTenant } from '@jantrik/db'; +import type { InstituteProfile } from '@jantrik/shared'; +import sharp from 'sharp'; +import { + addMember, + bearer, + createHarness, + createTenant, + http, + otpLogin, + type Harness, +} from './support/harness.js'; + +// Sprint 1 P2: the institute's own profile and its logo, head's signature and seal. + +const png = (w: number, h: number) => + sharp({ + create: { width: w, height: h, channels: 4, background: { r: 20, g: 90, b: 60, alpha: 0.8 } }, + }) + .png() + .toBuffer(); + +describe('institute profile', () => { + let h: Harness; + + beforeAll(async () => { + h = await createHarness(); + }); + + afterAll(() => h.close()); + + const institute = async () => { + const t = await createTenant(h); + const login = async (role: 'OWNER' | 'ADMIN' | 'TEACHER' | 'GUARDIAN') => + (await otpLogin(h, (await addMember(h, t.id, { roles: [role] })).phone)).accessToken; + return { + id: t.id, + owner: await login('OWNER'), + admin: await login('ADMIN'), + teacher: await login('TEACHER'), + guardian: await login('GUARDIAN'), + }; + }; + const audits = (tenantId: string) => + withTenant(h.prisma, tenantId, (tx) => + tx.auditLog.findMany({ + where: { entity: 'institute_profile' }, + orderBy: { createdAt: 'asc' }, + }), + ); + const upload = (token: string, slot: string, file: Buffer) => + http(h) + .put(`/institute/profile/${slot}`) + .set(bearer(token)) + .attach('file', file, { filename: `${slot}.png`, contentType: 'image/png' }); + + it('starts empty with the registered name; the owner saves it (Bangla digits accepted)', async () => { + const t = await institute(); + const empty = (await http(h).get('/institute/profile').set(bearer(t.admin)).expect(200)) + .body as InstituteProfile; + expect(empty).toMatchObject({ + saved: false, + registeredName: 'Test Institute', + nameBn: null, + nameEn: null, + logo: null, + signature: null, + seal: null, + storage: { bytesUsed: 0, capBytes: 1024 * 1024 * 1024 }, + }); + + const body = { + nameBn: 'শাপলা উচ্চ বিদ্যালয়', + nameEn: 'Shapla High School', + eiin: '১০৮১২৩', + phone: '০১৭১১-০০০০০০', + website: 'shapla.edu.bd', + email: 'office@shapla.edu.bd', + headTitleBn: 'প্রধান শিক্ষক', + headNameEn: 'Md. Rahim', + establishedYear: '১৯৬৫', + }; + const saved = ( + await http(h).put('/institute/profile').set(bearer(t.owner)).send(body).expect(200) + ).body as InstituteProfile; + expect(saved).toMatchObject({ + saved: true, + eiin: '108123', + phone: '+8801711000000', + website: 'https://shapla.edu.bd', + establishedYear: 1965, + shortName: null, + }); + // Saving the same again changes nothing and is not audited a second time. + await http(h).put('/institute/profile').set(bearer(t.admin)).send(body).expect(200); + const rows = await audits(t.id); + expect(rows.map((r) => r.action)).toEqual(['CREATE']); + expect(rows[0]!.newValues).toMatchObject({ eiin: '108123' }); + }); + + it('refuses bad values (400) and non-admins (403)', async () => { + const t = await institute(); + for (const bad of [ + { nameBn: '', nameEn: '' }, + { nameEn: 'X', eiin: '12345' }, + { nameEn: 'X', email: 'office@' }, + { nameEn: 'X', establishedYear: 1700 }, + ]) { + await http(h).put('/institute/profile').set(bearer(t.owner)).send(bad).expect(400); + } + await http(h).get('/institute/profile').set(bearer(t.teacher)).expect(403); + await http(h) + .put('/institute/profile') + .set(bearer(t.teacher)) + .send({ nameEn: 'X' }) + .expect(403); + await upload(t.teacher, 'logo', await png(100, 100)).expect(403); + }); + + it('a logo uploaded before the first save creates the profile with the registered name', async () => { + const t = await institute(); + const res = (await upload(t.admin, 'logo', await png(1000, 600)).expect(200)) + .body as InstituteProfile; + expect(res).toMatchObject({ saved: true, nameEn: 'Test Institute', nameBn: null }); + expect(res.logo).toMatchObject({ mime: 'image/png', width: 512 }); + expect(res.storage.bytesUsed).toBe(res.logo!.sizeBytes); + }); + + it('everyone sees the logo; only owner and admin see the signature and the seal', async () => { + const t = await institute(); + await upload(t.owner, 'logo', await png(300, 300)).expect(200); + await upload(t.owner, 'signature', await png(900, 300)).expect(200); + const sealed = (await upload(t.owner, 'seal', await png(400, 400)).expect(200)) + .body as InstituteProfile; + expect(sealed.signature).toMatchObject({ mime: 'image/png' }); + + for (const token of [t.owner, t.admin, t.teacher, t.guardian]) { + const r = await http(h) + .get('/institute/profile/logo') + .set(bearer(token)) + .buffer(true) + .expect(200); + expect(r.headers['content-type']).toBe('image/png'); + } + for (const slot of ['signature', 'seal']) { + await http(h).get(`/institute/profile/${slot}`).set(bearer(t.admin)).expect(200); + await http(h).get(`/institute/profile/${slot}`).set(bearer(t.teacher)).expect(403); + await http(h).get(`/institute/profile/${slot}`).set(bearer(t.guardian)).expect(403); + } + await http(h).get('/institute/profile/stamp').set(bearer(t.admin)).expect(400); + + // Another institute has none of these. + const other = await institute(); + await http(h).get('/institute/profile/logo').set(bearer(other.admin)).expect(404); + }); + + it('replacing and removing an image keep the total equal to the stored files', async () => { + const t = await institute(); + const first = (await upload(t.admin, 'seal', await png(200, 200)).expect(200)) + .body as InstituteProfile; + const second = (await upload(t.admin, 'seal', await png(300, 300)).expect(200)) + .body as InstituteProfile; + expect(second.seal!.id).not.toBe(first.seal!.id); + expect(second.storage.bytesUsed).toBe(second.seal!.sizeBytes); + + const removed = ( + await http(h).delete('/institute/profile/seal').set(bearer(t.admin)).expect(200) + ).body as InstituteProfile; + expect(removed.seal).toBeNull(); + expect(removed.storage.bytesUsed).toBe(0); + await http(h).get('/institute/profile/seal').set(bearer(t.admin)).expect(404); + const images = (await audits(t.id)).filter( + (r) => (r.newValues as { image?: string } | null)?.image === 'seal', + ); + expect(images.map((r) => (r.newValues as { fileId: string | null }).fileId)).toEqual([ + first.seal!.id, + second.seal!.id, + null, + ]); + }); +}); diff --git a/packages/shared/src/api.ts b/packages/shared/src/api.ts index 5a0d27d..4d96fc8 100644 --- a/packages/shared/src/api.ts +++ b/packages/shared/src/api.ts @@ -65,7 +65,8 @@ export interface StudentListItem { nameBn: string | null; nameEn: string | null; status: StudentStatus; - photoUrl: string | null; + /** The stored photo's id (GET …/photo serves it), or null; a replaced photo has a new id. */ + photoId: string | null; enrolment: { classLevel: { id: string; nameBn: string; nameEn: string }; section: { id: string; name: string } | null; @@ -106,7 +107,8 @@ export interface GuardianChild { studentCode: string; nameBn: string | null; nameEn: string | null; - photoUrl: string | null; + /** The stored photo's id (GET …/photo serves it), or null; a replaced photo has a new id. */ + photoId: string | null; status: StudentListItem['status']; relation: | 'FATHER' diff --git a/packages/shared/src/exams-api.ts b/packages/shared/src/exams-api.ts index 068f5e3..1d54f87 100644 --- a/packages/shared/src/exams-api.ts +++ b/packages/shared/src/exams-api.ts @@ -513,7 +513,7 @@ export interface AdmitCards { studentCode: string; nameBn: string | null; nameEn: string | null; - photoUrl: string | null; + photoId: string | null; }; classLevel: CodedRef; section: { id: string; name: string }; @@ -817,7 +817,7 @@ export interface ReportCard { studentCode: string; nameBn: string | null; nameEn: string | null; - photoUrl: string | null; + photoId: string | null; /** Only for OWNER/ADMIN, the student's current section teachers and the guardian (#19). */ fatherNameBn: string | null; fatherNameEn: string | null; diff --git a/packages/shared/src/files-schema.ts b/packages/shared/src/files-schema.ts index e84fd84..a7068df 100644 --- a/packages/shared/src/files-schema.ts +++ b/packages/shared/src/files-schema.ts @@ -1,7 +1,11 @@ import { z } from 'zod'; import { toAsciiDigits } from './digits.js'; -import { INSTITUTE_PROFILE_LIMITS as L } from './files.js'; -import { normalizeBdPhone } from './phone.js'; +import { + INSTITUTE_PROFILE_LIMITS as L, + INSTITUTE_PROFILE_PATTERNS as P, + normalizeInstitutePhone, + normalizeWebsite, +} from './files.js'; // PUT /institute/profile (sprint 1 P2). Each rule matches a CHECK on institute_profiles, so a // value the schema accepts is never refused by the database. @@ -20,45 +24,26 @@ const digitsText = z .nullish() .transform((v) => (v ? toAsciiDigits(v).replace(/\s/g, '') : '') || null); -/** A mobile is stored as E.164; anything else as its digits (a landline), with an optional +. */ -export function normalizeInstitutePhone(input: string): string { - return ( - normalizeBdPhone(input) ?? - toAsciiDigits(input) - .trim() - .replace(/[\s\-().]/g, '') - ); -} - -/** `shapla.edu.bd` → `https://shapla.edu.bd`; a given http(s) scheme is kept. */ -export function normalizeWebsite(input: string): string { - const v = input.trim(); - return /^[a-z][a-z0-9+.-]*:/i.test(v) ? v : `https://${v}`; -} - export const instituteProfileSchema = z .object({ nameBn: text(L.name), nameEn: text(L.name), shortName: text(L.shortName), - eiin: digitsText.refine((v) => v === null || /^\d{6}$/.test(v), 'EIIN is 6 digits'), + eiin: digitsText.refine((v) => v === null || P.eiin.test(v), 'EIIN is 6 digits'), addressBn: text(L.address), addressEn: text(L.address), phone: z .string() .nullish() .transform((v) => (v?.trim() ? normalizeInstitutePhone(v) : null)) - .refine((v) => v === null || /^\+?\d{5,15}$/.test(v), 'A phone number of 5-15 digits'), - email: text(L.email).refine( - (v) => v === null || /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v), - 'An e-mail address', - ), + .refine((v) => v === null || P.phone.test(v), 'A phone number of 5-15 digits'), + email: text(L.email).refine((v) => v === null || P.email.test(v), 'An e-mail address'), website: z .string() .nullish() .transform((v) => (v?.trim() ? normalizeWebsite(v) : null)) .refine( - (v) => v === null || (v.length <= L.website && /^https?:\/\/\S+$/i.test(v)), + (v) => v === null || (v.length <= L.website && P.website.test(v)), 'A web address (http or https)', ), headTitleBn: text(L.headTitle), diff --git a/packages/shared/src/files.test.ts b/packages/shared/src/files.test.ts index ac58259..bd3dd07 100644 --- a/packages/shared/src/files.test.ts +++ b/packages/shared/src/files.test.ts @@ -1,10 +1,12 @@ import { describe, expect, it } from 'vitest'; -import { FILE_LIMITS, STORED_FILE_KINDS, UPLOAD_MAX_BYTES } from './files.js'; import { - instituteProfileSchema, + FILE_LIMITS, normalizeInstitutePhone, normalizeWebsite, -} from './files-schema.js'; + STORED_FILE_KINDS, + UPLOAD_MAX_BYTES, +} from './files.js'; +import { instituteProfileSchema } from './files-schema.js'; describe('file limits (docs/files.md, the stored_files CHECKs)', () => { it('has a limit for every kind, equal to the database caps', () => { diff --git a/packages/shared/src/files.ts b/packages/shared/src/files.ts index 3a8dd4e..377aa26 100644 --- a/packages/shared/src/files.ts +++ b/packages/shared/src/files.ts @@ -1,6 +1,9 @@ // Stored images (sprint 1 P2, docs/files.md): the kinds, their caps and the API's shapes. No zod // here: the web imports these; the input schema is in files-schema.ts. +import { toAsciiDigits } from './digits.js'; +import { normalizeBdPhone } from './phone.js'; + export const STORED_FILE_KINDS = [ 'STUDENT_PHOTO', 'APPLICANT_PHOTO', @@ -119,3 +122,27 @@ export const INSTITUTE_PROFILE_LIMITS = { yearMin: 1800, yearMax: 2100, } as const; + +/** The formats of institute_profiles' CHECKs, after the normalisers below. */ +export const INSTITUTE_PROFILE_PATTERNS = { + eiin: /^\d{6}$/, + phone: /^\+?\d{5,15}$/, + email: /^[^@\s]+@[^@\s]+\.[^@\s]+$/, + website: /^https?:\/\/\S+$/i, +} as const; + +/** A mobile is stored as E.164; anything else as its digits (a landline), with an optional +. */ +export function normalizeInstitutePhone(input: string): string { + return ( + normalizeBdPhone(input) ?? + toAsciiDigits(input) + .trim() + .replace(/[\s\-().]/g, '') + ); +} + +/** `shapla.edu.bd` → `https://shapla.edu.bd`; a given scheme is kept (and then checked). */ +export function normalizeWebsite(input: string): string { + const v = input.trim(); + return /^[a-z][a-z0-9+.-]*:/i.test(v) ? v : `https://${v}`; +} diff --git a/packages/shared/src/students.ts b/packages/shared/src/students.ts index 0d0cc80..4ee0ca8 100644 --- a/packages/shared/src/students.ts +++ b/packages/shared/src/students.ts @@ -255,7 +255,8 @@ export interface StudentProfile { motherNameEn: string | null; presentAddress: string | null; permanentAddress: string | null; - photoUrl: string | null; + /** The stored photo's id (GET …/photo serves it), or null; a replaced photo has a new id. */ + photoId: string | null; status: StudentStatus; /** Set when deactivated (soft delete). */ deletedAt: string | null; From 57cf79fec7c32245a0941b282447d1bc74347a9f Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:43 +0600 Subject: [PATCH 19/44] =?UTF-8?q?Web=20(P2=20task=206):=20Settings=20?= =?UTF-8?q?=E2=86=92=20Institute=20profile=20(names,=20EIIN,=20contact,=20?= =?UTF-8?q?head,=20logo,=20signature,=20seal,=20storage=20used),=20the=20p?= =?UTF-8?q?hoto=20dialog=20on=20the=20student=20page,=20the=20photo=20on?= =?UTF-8?q?=20the=20student=20page,=20the=20side=20peek,=20the=20guardian'?= =?UTF-8?q?s=20child=20card=20and=20the=20report=20card=20through=20authen?= =?UTF-8?q?ticated=20object=20URLs;=20lists=20keep=20initials=20(the=203?= =?UTF-8?q?=20s=20budget);=20Playwright=20spec=20for=20both=20screens?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- apps/web/e2e/files.spec.ts | 70 ++++ apps/web/messages/bn.json | 66 +++- apps/web/messages/en.json | 66 +++- apps/web/src/app/(app)/dashboard/page.tsx | 10 +- apps/web/src/app/(app)/setup/profile/page.tsx | 312 ++++++++++++++++++ apps/web/src/app/(app)/students/[id]/page.tsx | 23 +- apps/web/src/app/(app)/students/page.tsx | 8 +- apps/web/src/components/exams/report-card.tsx | 14 +- apps/web/src/components/image-upload.tsx | 81 +++++ apps/web/src/components/setup/setup-kit.tsx | 13 +- apps/web/src/components/student-photo.tsx | 53 +++ .../src/components/students/photo-dialog.tsx | 140 ++++++++ apps/web/src/lib/authed-image.ts | 72 ++++ 13 files changed, 905 insertions(+), 23 deletions(-) create mode 100644 apps/web/e2e/files.spec.ts create mode 100644 apps/web/src/app/(app)/setup/profile/page.tsx create mode 100644 apps/web/src/components/image-upload.tsx create mode 100644 apps/web/src/components/student-photo.tsx create mode 100644 apps/web/src/components/students/photo-dialog.tsx create mode 100644 apps/web/src/lib/authed-image.ts diff --git a/apps/web/e2e/files.spec.ts b/apps/web/e2e/files.spec.ts new file mode 100644 index 0000000..c289d9b --- /dev/null +++ b/apps/web/e2e/files.spec.ts @@ -0,0 +1,70 @@ +import { expect, test } from '@playwright/test'; +import { DEMO, passwordLogin } from './helpers'; + +// Sprint 1 P2 (docs/files.md): the institute profile with its logo, and a student's photo. The +// images reach the page through the bearer token as blob: URLs. + +/** A 1 × 1 PNG: the server re-encodes it like any upload. */ +const PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', + 'base64', +); + +test.describe('files', () => { + test.beforeEach(async ({ page }) => { + await passwordLogin(page, DEMO.shaplaOwner); + await expect(page).toHaveURL(/\/dashboard/); + }); + + test('the owner fills the institute profile and adds a logo', async ({ page }) => { + await page.goto('/setup/profile'); + const form = page.getByTestId('institute-profile-form'); + // A new profile starts with the registered name. + await expect(form.getByLabel('নাম (বাংলা)')).toHaveValue(DEMO.shaplaName); + await form.getByLabel('EIIN').fill('১০৮১২৩'); + await form.getByLabel('প্রতিষ্ঠার সাল').fill('১৯৬৫'); + await form.getByTestId('profile-save').click(); + await expect(page.getByText('সংরক্ষণ হয়েছে').first()).toBeVisible(); + await page.reload(); + await expect(page.getByTestId('institute-profile-form').getByLabel('EIIN')).toHaveValue( + '108123', + ); + + const logo = page.getByTestId('image-logo'); + await logo + .getByTestId('image-logo-choose-input') + .setInputFiles({ name: 'logo.png', mimeType: 'image/png', buffer: PNG }); + await expect(logo.locator('img[src^="blob:"]')).toBeVisible(); + await expect(page.getByTestId('storage-used')).toBeVisible(); + + // Removed again, so the demo institute stays as seeded for the other specs. + await logo.getByTestId('image-logo-remove').click(); + await page.getByTestId('confirm-dialog').getByRole('button', { name: 'সরান' }).click(); + await expect(logo.locator('img')).toHaveCount(0); + }); + + test("an admin adds a student's photo and sees it on the student's page", async ({ page }) => { + await page.goto('/students'); + const first = page.locator('a[href^="/students/"]').first(); + const href = (await first.getAttribute('href'))!; + await page.goto(href); + const profile = page.getByTestId('student-profile'); + await expect(profile).toBeVisible(); + + await page.getByTestId('student-photo-button').click(); + const dialog = page.getByTestId('photo-dialog'); + await dialog + .getByTestId('photo-choose-input') + .setInputFiles({ name: 'photo.png', mimeType: 'image/png', buffer: PNG }); + await expect(dialog.getByTestId('photo-preview')).toBeVisible(); + await dialog.getByTestId('photo-upload').click(); + await expect(dialog).toBeHidden(); + await expect(profile.locator('img[src^="blob:"]').first()).toBeVisible(); + + // And removed again (the button now reads "change photo"). + await page.getByTestId('student-photo-button').click(); + await page.getByTestId('photo-dialog').getByTestId('photo-remove').click(); + await expect(page.getByTestId('photo-dialog')).toBeHidden(); + await expect(profile.locator('img[src^="blob:"]')).toHaveCount(0); + }); +}); diff --git a/apps/web/messages/bn.json b/apps/web/messages/bn.json index b171795..b4de4a1 100644 --- a/apps/web/messages/bn.json +++ b/apps/web/messages/bn.json @@ -20,7 +20,12 @@ "rateLimited": "অনেকবার চেষ্টা করা হয়েছে। {seconds} সেকেন্ড পরে আবার চেষ্টা করুন।", "network": "সার্ভারের সাথে সংযোগ করা যাচ্ছে না। ইন্টারনেট সংযোগ দেখে আবার চেষ্টা করুন।", "generic": "কিছু একটা সমস্যা হয়েছে। আবার চেষ্টা করুন।", - "forbidden": "এই অংশ দেখার অনুমতি আপনার নেই।" + "forbidden": "এই অংশ দেখার অনুমতি আপনার নেই।", + "imageInvalid": "ফাইলটি JPEG, PNG বা WebP ছবি নয়, অথবা নষ্ট। অন্য একটি ছবি দিন।", + "imageTooBig": "ছবিটিতে পিক্সেল খুব বেশি (সর্বোচ্চ ৫০ মেগাপিক্সেল)। আরেকটু ছোট ছবি দিন।", + "imageCannotShrink": "ছবিটি যথেষ্ট ছোট করা গেল না। অন্য একটি ছবি দিন।", + "fileTooLarge": "ফাইলটি ৫ MB-এর বেশি বড়। ছোট একটি ফাইল দিন।", + "storageFull": "প্রতিষ্ঠানের ছবি রাখার জায়গা পূর্ণ। পুরোনো ছবি সরান বা জান্ত্রিককে জানান।" }, "login": { "title": "লগইন করুন", @@ -703,7 +708,51 @@ "codePatternError": "একটি '{NNNN}' রাখুন; শুধু '{PREFIX}', '{YEAR}', '{YY}', ইংরেজি অক্ষর, সংখ্যা, - / _", "codeTokens": "যোগ করুন:", "codeNext": "পরের ভর্তিতে: {code}", - "tabAppearance": "চেহারা" + "tabAppearance": "চেহারা", + "tabProfile": "প্রতিষ্ঠানের প্রোফাইল", + "profileHint": "প্রতিষ্ঠানের নাম, ঠিকানা ও প্রধানের তথ্য। ভর্তি ফরম, আইডি কার্ড ও সনদে এগুলো ব্যবহার হবে।", + "profileRegistered": "নিবন্ধিত নাম: {name}", + "profileNames": "নাম", + "profileContact": "ঠিকানা ও যোগাযোগ", + "profileHead": "প্রতিষ্ঠান প্রধান", + "shortName": "সংক্ষিপ্ত নাম", + "shortNameHint": "যেমন: শাউবি", + "eiin": "EIIN", + "eiinHint": "৬ অঙ্কের নম্বর, যদি থাকে", + "establishedYear": "প্রতিষ্ঠার সাল", + "addressBn": "ঠিকানা (বাংলা)", + "addressEn": "ঠিকানা (ইংরেজি)", + "phone": "ফোন", + "email": "ইমেইল", + "website": "ওয়েবসাইট", + "headTitleBn": "পদবি (বাংলা)", + "headTitleBnHint": "যেমন: প্রধান শিক্ষক, অধ্যক্ষ", + "headTitleEn": "পদবি (ইংরেজি)", + "headTitleEnHint": "যেমন: Headmaster, Principal", + "headNameBn": "প্রধানের নাম (বাংলা)", + "headNameEn": "প্রধানের নাম (ইংরেজি)", + "profileNameRequired": "বাংলা বা ইংরেজিতে একটি নাম দিন", + "eiinError": "EIIN ৬ অঙ্কের হয়", + "phoneError": "সঠিক ফোন নম্বর দিন", + "emailError": "সঠিক ইমেইল ঠিকানা দিন", + "websiteError": "সঠিক ওয়েব ঠিকানা দিন", + "yearError": "১৮০০ থেকে ২১০০-এর মধ্যে একটি সাল দিন", + "imagesTitle": "লোগো, স্বাক্ষর ও সিল", + "imagesHint": "JPEG, PNG বা WebP, ৫ MB পর্যন্ত। ছবি ছোট করে রাখা হয়; লুকানো তথ্য মুছে যায়।", + "imageLogo": "লোগো", + "imageLogoHint": "স্বচ্ছ পটভূমির PNG সবচেয়ে ভালো দেখায়", + "imageSignature": "প্রধানের স্বাক্ষর", + "imageSignatureHint": "সাদা কাগজে কালো কালিতে সই করে ছবি তুলুন", + "imageSeal": "সিল", + "imageSealHint": "সাদা কাগজে সিল দিয়ে ছবি তুলুন", + "imageUpload": "আপলোড", + "imageReplace": "বদলান", + "imageRemove": "সরান", + "imageRemoveTitle": "{name} সরাবেন?", + "imageNone": "এখনো নেই", + "imageSaved": "ছবি রাখা হয়েছে", + "imageRemoved": "ছবি সরানো হয়েছে", + "storageUsed": "ছবির জায়গা: {cap} MB-এর মধ্যে {used} MB ব্যবহৃত" }, "staff": { "title": "কর্মী ও শিক্ষক", @@ -878,7 +927,18 @@ "errorDeactivated": "এই শিক্ষার্থী নিষ্ক্রিয়।", "errorNotEnrolled": "চলতি শিক্ষাবর্ষে ভর্তি নেই।", "errorCheckForm": "লাল চিহ্নিত ঘরগুলো ঠিক করুন।", - "basicAccess": "জন্ম তারিখ, জন্ম নিবন্ধন, ঠিকানা ও অভিভাবকের তথ্য শুধু প্রশাসক ও এই {section}-এর শিক্ষকেরা দেখতে পান।" + "basicAccess": "জন্ম তারিখ, জন্ম নিবন্ধন, ঠিকানা ও অভিভাবকের তথ্য শুধু প্রশাসক ও এই {section}-এর শিক্ষকেরা দেখতে পান।", + "photo": "ছবি", + "addPhoto": "ছবি যোগ করুন", + "changePhoto": "ছবি বদলান", + "photoTitle": "{name}-এর ছবি", + "photoHint": "JPEG, PNG বা WebP, ৫ MB পর্যন্ত। ছবিটি পাসপোর্ট মাপে ছোট করে রাখা হয়; লোকেশনসহ লুকানো তথ্য মুছে যায়।", + "photoChoose": "ছবি বাছুন", + "photoUpload": "আপলোড করুন", + "photoRemove": "ছবি সরান", + "photoRemoved": "ছবি সরানো হয়েছে", + "photoNone": "এখনো ছবি নেই", + "photoPreview": "নতুন ছবি" }, "enums": { "gender_MALE": "ছেলে", diff --git a/apps/web/messages/en.json b/apps/web/messages/en.json index cd131dc..b659afa 100644 --- a/apps/web/messages/en.json +++ b/apps/web/messages/en.json @@ -20,7 +20,12 @@ "rateLimited": "Too many attempts. Try again in {seconds} seconds.", "network": "Cannot reach the server. Check your internet connection and try again.", "generic": "Something went wrong. Please try again.", - "forbidden": "You don't have permission to see this." + "forbidden": "You don't have permission to see this.", + "imageInvalid": "This file is not a JPEG, PNG or WebP image, or it is damaged. Choose another image.", + "imageTooBig": "The image has too many pixels (at most 50 megapixels). Choose a smaller one.", + "imageCannotShrink": "This image could not be made small enough. Choose another one.", + "fileTooLarge": "The file is larger than 5 MB. Choose a smaller one.", + "storageFull": "The institute's storage for images is full. Remove old images or contact Jantrik." }, "login": { "title": "Sign in", @@ -703,7 +708,51 @@ "codePatternError": "Keep one '{NNNN}'; only '{PREFIX}', '{YEAR}', '{YY}', letters, digits, - / _", "codeTokens": "Insert:", "codeNext": "Next admission: {code}", - "tabAppearance": "Appearance" + "tabAppearance": "Appearance", + "tabProfile": "Institute profile", + "profileHint": "Your institute's names, address and head. Admission forms, ID cards and certificates will use them.", + "profileRegistered": "Registered name: {name}", + "profileNames": "Names", + "profileContact": "Address and contact", + "profileHead": "Head of institute", + "shortName": "Short name", + "shortNameHint": "For example: SHS", + "eiin": "EIIN", + "eiinHint": "The 6-digit number, if you have one", + "establishedYear": "Year established", + "addressBn": "Address (Bangla)", + "addressEn": "Address (English)", + "phone": "Phone", + "email": "Email", + "website": "Website", + "headTitleBn": "Title (Bangla)", + "headTitleBnHint": "For example: প্রধান শিক্ষক, অধ্যক্ষ", + "headTitleEn": "Title (English)", + "headTitleEnHint": "For example: Headmaster, Principal", + "headNameBn": "Head's name (Bangla)", + "headNameEn": "Head's name (English)", + "profileNameRequired": "Enter a name in Bangla or English", + "eiinError": "An EIIN has 6 digits", + "phoneError": "Enter a valid phone number", + "emailError": "Enter a valid email address", + "websiteError": "Enter a valid web address", + "yearError": "Enter a year between 1800 and 2100", + "imagesTitle": "Logo, signature and seal", + "imagesHint": "JPEG, PNG or WebP, up to 5 MB. Images are shrunk; hidden details are removed.", + "imageLogo": "Logo", + "imageLogoHint": "A PNG with a transparent background looks best", + "imageSignature": "Head's signature", + "imageSignatureHint": "Sign in black ink on white paper and take a photo", + "imageSeal": "Seal", + "imageSealHint": "Stamp it on white paper and take a photo", + "imageUpload": "Upload", + "imageReplace": "Replace", + "imageRemove": "Remove", + "imageRemoveTitle": "Remove the {name}?", + "imageNone": "None yet", + "imageSaved": "Image saved", + "imageRemoved": "Image removed", + "storageUsed": "Image storage: {used} MB of {cap} MB used" }, "staff": { "title": "Staff", @@ -878,7 +927,18 @@ "errorDeactivated": "This student is deactivated.", "errorNotEnrolled": "Not enrolled in the current year.", "errorCheckForm": "Fix the fields marked in red.", - "basicAccess": "Date of birth, birth registration, addresses and guardian details are visible only to admins and the teachers of this {section}." + "basicAccess": "Date of birth, birth registration, addresses and guardian details are visible only to admins and the teachers of this {section}.", + "photo": "Photo", + "addPhoto": "Add photo", + "changePhoto": "Change photo", + "photoTitle": "Photo of {name}", + "photoHint": "JPEG, PNG or WebP, up to 5 MB. It is kept at passport size; the location and other hidden details are removed.", + "photoChoose": "Choose image", + "photoUpload": "Upload", + "photoRemove": "Remove photo", + "photoRemoved": "Photo removed", + "photoNone": "No photo yet", + "photoPreview": "New photo" }, "enums": { "gender_MALE": "Male", diff --git a/apps/web/src/app/(app)/dashboard/page.tsx b/apps/web/src/app/(app)/dashboard/page.tsx index eff643c..74878ba 100644 --- a/apps/web/src/app/(app)/dashboard/page.tsx +++ b/apps/web/src/app/(app)/dashboard/page.tsx @@ -77,7 +77,7 @@ import { import { DeltaPill, Pill } from '@/components/kit/pill'; import { HalfGauge, HatchedColumns } from '@/components/story-charts'; import { InvitationsBanner } from '@/components/invitations-banner'; -import { PersonAvatar } from '@/components/person-avatar'; +import { StudentAvatar } from '@/components/student-photo'; import { Alert, AlertDescription } from '@/components/ui/alert'; import { Button, ButtonLink } from '@/components/ui/button'; import { @@ -1241,7 +1241,13 @@ function ChildCard({ className="bg-card rounded-card shadow-card flex flex-col overflow-hidden border" >
- +

{name}

diff --git a/apps/web/src/app/(app)/setup/profile/page.tsx b/apps/web/src/app/(app)/setup/profile/page.tsx new file mode 100644 index 0000000..3518401 --- /dev/null +++ b/apps/web/src/app/(app)/setup/profile/page.tsx @@ -0,0 +1,312 @@ +'use client'; + +import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'; +import { + formatCount, + INSTITUTE_PROFILE_LIMITS as L, + INSTITUTE_PROFILE_PATTERNS as P, + normalizeInstitutePhone, + normalizeWebsite, + toAsciiDigits, + type FileRef, + type InstituteImageSlot, + type InstituteProfile, + type InstituteProfileFields, +} from '@jantrik/shared'; +import { Trash2Icon } from 'lucide-react'; +import { useLocale, useTranslations } from 'next-intl'; +import { useState } from 'react'; +import { toast } from 'sonner'; +import { SectionCard, TextField } from '@/components/form-kit'; +import { ChooseImageButton, imageForm } from '@/components/image-upload'; +import { ConfirmDialog, SetupPage } from '@/components/setup/setup-kit'; +import { Alert, AlertDescription } from '@/components/ui/alert'; +import { Button } from '@/components/ui/button'; +import { Skeleton } from '@/components/ui/skeleton'; +import type { Locale } from '@/i18n/config'; +import { useAuth } from '@/lib/auth/auth-provider'; +import { useAuthedImage, useImageErrorMessage } from '@/lib/authed-image'; +import { useErrorMessage } from '@/lib/hooks'; + +const BANGLA = /[ঀ-৿]/; + +/** Settings → Institute profile (OWNER/ADMIN): names, contact, head, and three images. */ +export default function InstituteProfilePage() { + const describe = useErrorMessage(); + const { client, session } = useAuth(); + const profile = useQuery({ + queryKey: ['institute-profile', session?.tenant?.id], + queryFn: () => client.api('/institute/profile'), + }); + return ( + + {profile.isPending ? ( + + ) : profile.isError ? ( + + {describe(profile.error)} + + ) : ( + <> + + + + )} + + ); +} + +type Form = Record; + +const KEYS: (keyof InstituteProfileFields)[] = [ + 'nameBn', + 'nameEn', + 'shortName', + 'eiin', + 'addressBn', + 'addressEn', + 'phone', + 'email', + 'website', + 'headTitleBn', + 'headTitleEn', + 'headNameBn', + 'headNameEn', + 'establishedYear', +]; + +/** The form's starting values: the saved profile, or the registered name in its script. */ +function initialForm(p: InstituteProfile): Form { + const form = Object.fromEntries(KEYS.map((k) => [k, p[k] === null ? '' : String(p[k])])) as Form; + if (!p.saved) form[BANGLA.test(p.registeredName) ? 'nameBn' : 'nameEn'] = p.registeredName; + return form; +} + +/** The same rules as the API (files-schema.ts), on the typed text; null when fine. */ +function problems(f: Form): Partial> { + const out: Partial> = {}; + if (!f.nameBn.trim() && !f.nameEn.trim()) out.nameBn = 'profileNameRequired'; + const eiin = toAsciiDigits(f.eiin).replace(/\s/g, ''); + if (eiin && !P.eiin.test(eiin)) out.eiin = 'eiinError'; + if (f.phone.trim() && !P.phone.test(normalizeInstitutePhone(f.phone))) out.phone = 'phoneError'; + if (f.email.trim() && !P.email.test(f.email.trim())) out.email = 'emailError'; + if (f.website.trim()) { + const w = normalizeWebsite(f.website); + if (w.length > L.website || !P.website.test(w)) out.website = 'websiteError'; + } + const year = toAsciiDigits(f.establishedYear).trim(); + if (year && !(/^\d{4}$/.test(year) && +year >= L.yearMin && +year <= L.yearMax)) { + out.establishedYear = 'yearError'; + } + return out; +} + +function ProfileForm({ initial }: { initial: InstituteProfile }) { + const t = useTranslations('setup'); + const describe = useErrorMessage(); + const { client, session } = useAuth(); + const queryClient = useQueryClient(); + const [form, setForm] = useState
(() => initialForm(initial)); + const [tried, setTried] = useState(false); + const errors = problems(form); + const set = (k: keyof Form) => (v: string) => setForm((f) => ({ ...f, [k]: v })); + const save = useMutation({ + mutationFn: () => + client.api('/institute/profile', { + method: 'PUT', + json: Object.fromEntries(KEYS.map((k) => [k, form[k].trim() || null])), + }), + onSuccess: (next) => { + queryClient.setQueryData(['institute-profile', session?.tenant?.id], next); + setForm(initialForm(next)); + setTried(false); + toast.success(t('saved')); + }, + onError: (e) => toast.error(describe(e)), + }); + const field = ( + k: keyof Form, + opts: { + max?: number; + hint?: string; + dir?: 'ltr'; + inputMode?: 'numeric' | 'tel' | 'email'; + } = {}, + ) => ( + + ); + return ( + { + e.preventDefault(); + setTried(true); + if (Object.keys(errors).length === 0) save.mutate(); + }} + data-testid="institute-profile-form" + className="flex flex-col gap-(--section-gap)" + > + +
+ {field('nameBn', { max: L.name })} + {field('nameEn', { max: L.name })} + {field('shortName', { max: L.shortName, hint: t('shortNameHint') })} + {field('eiin', { max: 12, hint: t('eiinHint'), dir: 'ltr', inputMode: 'numeric' })} + {field('establishedYear', { max: 4, inputMode: 'numeric' })} +
+
+ +
+ {field('addressBn', { max: L.address })} + {field('addressEn', { max: L.address })} + {field('phone', { max: 20, dir: 'ltr', inputMode: 'tel' })} + {field('email', { max: L.email, dir: 'ltr', inputMode: 'email' })} + {field('website', { max: L.website, dir: 'ltr' })} +
+
+ +
+ {field('headTitleBn', { max: L.headTitle, hint: t('headTitleBnHint') })} + {field('headTitleEn', { max: L.headTitle, hint: t('headTitleEnHint') })} + {field('headNameBn', { max: L.headName })} + {field('headNameEn', { max: L.headName })} +
+ +
+ + ); +} + +const SLOTS: { slot: InstituteImageSlot; key: 'logo' | 'signature' | 'seal' }[] = [ + { slot: 'logo', key: 'logo' }, + { slot: 'signature', key: 'signature' }, + { slot: 'seal', key: 'seal' }, +]; + +const SLOT_TEXT = { + logo: { name: 'imageLogo', hint: 'imageLogoHint' }, + signature: { name: 'imageSignature', hint: 'imageSignatureHint' }, + seal: { name: 'imageSeal', hint: 'imageSealHint' }, +} as const; + +function ImagesCard({ profile }: { profile: InstituteProfile }) { + const t = useTranslations('setup'); + const locale = useLocale() as Locale; + const mb = (bytes: number) => formatCount(Math.round((bytes / 1024 / 1024) * 10) / 10, locale); + return ( + +
    + {SLOTS.map(({ slot, key }) => ( + + ))} +
+

+ {t('storageUsed', { + used: mb(profile.storage.bytesUsed), + cap: mb(profile.storage.capBytes), + })} +

+
+ ); +} + +function ImageSlot({ slot, file }: { slot: InstituteImageSlot; file: FileRef | null }) { + const t = useTranslations('setup'); + const tErrors = useTranslations('errors'); + const describe = useImageErrorMessage(); + const { client, session } = useAuth(); + const queryClient = useQueryClient(); + const [confirm, setConfirm] = useState(false); + const url = useAuthedImage(`/institute/profile/${slot}`, file?.id ?? null); + const name = t(SLOT_TEXT[slot].name); + const done = (next: InstituteProfile, message: string) => { + queryClient.setQueryData(['institute-profile', session?.tenant?.id], next); + toast.success(message); + }; + const upload = useMutation({ + mutationFn: (f: File) => + client.api(`/institute/profile/${slot}`, { + method: 'PUT', + body: imageForm(f), + }), + onSuccess: (next) => done(next, t('imageSaved')), + onError: (e) => toast.error(describe(e)), + }); + const remove = useMutation({ + mutationFn: () => + client.api(`/institute/profile/${slot}`, { method: 'DELETE' }), + onSuccess: (next) => { + setConfirm(false); + done(next, t('imageRemoved')); + }, + onError: (e) => toast.error(describe(e)), + }); + const pending = upload.isPending || remove.isPending; + return ( +
  • + {name} +
    + {url ? ( + // eslint-disable-next-line @next/next/no-img-element + {name} + ) : ( + {t('imageNone')} + )} +
    + {t(SLOT_TEXT[slot].hint)} +
    + upload.mutate(f)} + onTooLarge={() => toast.error(tErrors('fileTooLarge'))} + testId={`image-${slot}-choose`} + > + {file ? t('imageReplace') : t('imageUpload')} + + {file && ( + + )} +
    + remove.mutate()} + /> +
  • + ); +} diff --git a/apps/web/src/app/(app)/students/[id]/page.tsx b/apps/web/src/app/(app)/students/[id]/page.tsx index 1c9c8e3..c70c944 100644 --- a/apps/web/src/app/(app)/students/[id]/page.tsx +++ b/apps/web/src/app/(app)/students/[id]/page.tsx @@ -13,6 +13,7 @@ import { import { ArrowLeftRightIcon, CalendarCheckIcon, + CameraIcon, KeyRoundIcon, LockIcon, PencilIcon, @@ -28,7 +29,8 @@ import { useEffect, useState, type ReactNode } from 'react'; import { toast } from 'sonner'; import { SectionCard, SelectField, TextField } from '@/components/form-kit'; import { PageGate } from '@/components/page-gate'; -import { PersonAvatar } from '@/components/person-avatar'; +import { StudentAvatar } from '@/components/student-photo'; +import { PhotoDialog } from '@/components/students/photo-dialog'; import { ConfirmDialog, FormDialog } from '@/components/setup/setup-kit'; import { BoardFields, @@ -54,7 +56,13 @@ import { useErrorMessage, useLabel, useMeContext } from '@/lib/hooks'; import { displayName } from '@/lib/names'; type Dialog = - 'edit' | 'transfer' | 'guardian' | 'deactivate' | { removeLink: string; name: string } | null; + | 'edit' + | 'transfer' + | 'guardian' + | 'deactivate' + | 'photo' + | { removeLink: string; name: string } + | null; export default function StudentProfilePage() { return ( @@ -169,7 +177,7 @@ function Profile() { )}
    - +

    {name}

    {other && {other}} @@ -196,6 +204,14 @@ function Profile() { )} {writable && ( <> +
    diff --git a/apps/web/src/components/image-upload.tsx b/apps/web/src/components/image-upload.tsx new file mode 100644 index 0000000..9f4714f --- /dev/null +++ b/apps/web/src/components/image-upload.tsx @@ -0,0 +1,81 @@ +'use client'; + +import { UPLOAD_ACCEPT, UPLOAD_MAX_BYTES } from '@jantrik/shared'; +import { ImageUpIcon } from 'lucide-react'; +import { useEffect, useId, useRef, useState, type ReactNode } from 'react'; +import { Button } from '@/components/ui/button'; + +/** + * A "choose image" button around a hidden file input. A file over 5 MB is refused here with the + * server's own message, before anything is sent; the server decides the rest by content. + */ +export function ChooseImageButton({ + onChoose, + onTooLarge, + children, + variant = 'outline', + size, + disabled, + testId, +}: { + onChoose: (file: File) => void; + onTooLarge: () => void; + children: ReactNode; + variant?: 'outline' | 'default' | 'ghost'; + size?: 'sm' | 'default'; + disabled?: boolean; + testId?: string; +}) { + const input = useRef(null); + const id = useId(); + return ( + <> + { + const file = e.target.files?.[0]; + e.target.value = ''; // the same file can be chosen again after an error + if (!file) return; + if (file.size > UPLOAD_MAX_BYTES) onTooLarge(); + else onChoose(file); + }} + /> + + + ); +} + +/** An object URL for a chosen file, revoked when the file changes or the view goes. */ +export function useLocalPreview(file: File | null): string | null { + const [url, setUrl] = useState<{ file: File; url: string } | null>(null); + useEffect(() => { + if (!file) return; + const next = URL.createObjectURL(file); + setUrl({ file, url: next }); + return () => URL.revokeObjectURL(next); + }, [file]); + return file && url?.file === file ? url.url : null; +} + +/** The body of an image upload: the field `file`, as the API's multipart routes expect. */ +export function imageForm(file: File): FormData { + const form = new FormData(); + form.append('file', file); + return form; +} diff --git a/apps/web/src/components/setup/setup-kit.tsx b/apps/web/src/components/setup/setup-kit.tsx index 5060704..4a99c89 100644 --- a/apps/web/src/components/setup/setup-kit.tsx +++ b/apps/web/src/components/setup/setup-kit.tsx @@ -34,7 +34,15 @@ import { useErrorMessage, useLabel, useMeContext } from '@/lib/hooks'; import { cn } from '@/lib/utils'; export type SetupTab = - 'years' | 'classes' | 'shifts' | 'subjects' | 'groups' | 'labels' | 'studentCode' | 'appearance'; + | 'years' + | 'classes' + | 'shifts' + | 'subjects' + | 'groups' + | 'labels' + | 'studentCode' + | 'profile' + | 'appearance'; const TABS: { key: SetupTab; href: string }[] = [ { key: 'years', href: '/setup' }, @@ -44,6 +52,8 @@ const TABS: { key: SetupTab; href: string }[] = [ { key: 'groups', href: '/setup/groups' }, { key: 'labels', href: '/setup/labels' }, { key: 'studentCode', href: '/setup/student-code' }, + // The institute's names, contact, head, logo, signature and seal (sprint 1 P2). + { key: 'profile', href: '/setup/profile' }, // The institute's look is the owner's choice (shown to owners only). { key: 'appearance', href: '/setup/appearance' }, ]; @@ -65,6 +75,7 @@ export function SetupTabs({ active }: { active: SetupTab }) { groups: label('study_group', 'Group'), labels: t('tabLabels'), studentCode: t('tabStudentCode', { student: label('student', 'Student', { inText: true }) }), + profile: t('tabProfile'), appearance: t('tabAppearance'), }; return ( diff --git a/apps/web/src/components/student-photo.tsx b/apps/web/src/components/student-photo.tsx new file mode 100644 index 0000000..17a8878 --- /dev/null +++ b/apps/web/src/components/student-photo.tsx @@ -0,0 +1,53 @@ +'use client'; + +import { PersonAvatar } from '@/components/person-avatar'; +import { useAuthedImage } from '@/lib/authed-image'; +import { cn } from '@/lib/utils'; + +/** Where a student's photo comes from: staff routes, or a guardian's own child. */ +export function studentPhotoPath( + studentId: string, + photoId: string | null, + as: 'staff' | 'guardian' = 'staff', +): string | null { + if (!photoId) return null; + return as === 'guardian' ? `/me/children/${studentId}/photo` : `/students/${studentId}/photo`; +} + +/** A student's avatar: the photo once loaded, the initials meanwhile or without one. */ +export function StudentAvatar({ + studentId, + photoId, + name, + as = 'staff', + size, + className, +}: { + studentId: string; + photoId: string | null; + name: string; + as?: 'staff' | 'guardian'; + size?: 'sm' | 'default' | 'lg' | 'xl'; + className?: string; +}) { + const url = useAuthedImage(studentPhotoPath(studentId, photoId, as), photoId); + return ; +} + +/** The photo as a plain image (report cards); nothing until it has loaded. */ +export function StudentPhoto({ + studentId, + photoId, + className, +}: { + studentId: string; + photoId: string | null; + className?: string; +}) { + const url = useAuthedImage(studentPhotoPath(studentId, photoId), photoId); + if (!url) return null; + return ( + // eslint-disable-next-line @next/next/no-img-element + + ); +} diff --git a/apps/web/src/components/students/photo-dialog.tsx b/apps/web/src/components/students/photo-dialog.tsx new file mode 100644 index 0000000..c24973a --- /dev/null +++ b/apps/web/src/components/students/photo-dialog.tsx @@ -0,0 +1,140 @@ +'use client'; + +import { useMutation, useQueryClient } from '@tanstack/react-query'; +import type { StudentProfile } from '@jantrik/shared'; +import { Trash2Icon } from 'lucide-react'; +import { useTranslations } from 'next-intl'; +import { useState } from 'react'; +import { toast } from 'sonner'; +import { ChooseImageButton, imageForm, useLocalPreview } from '@/components/image-upload'; +import { StudentAvatar } from '@/components/student-photo'; +import { Button } from '@/components/ui/button'; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from '@/components/ui/dialog'; +import { useAuth } from '@/lib/auth/auth-provider'; +import { useImageErrorMessage } from '@/lib/authed-image'; + +/** + * Add, replace or remove a student's photo (OWNER/ADMIN). The chosen file is previewed locally; + * the server shrinks it to passport size and removes hidden details (docs/files.md). + */ +export function PhotoDialog({ + profile, + name, + onClose, +}: { + profile: StudentProfile; + name: string; + onClose: () => void; +}) { + const t = useTranslations('profile'); + const tErrors = useTranslations('errors'); + const describe = useImageErrorMessage(); + const { client, session } = useAuth(); + const queryClient = useQueryClient(); + const [file, setFile] = useState(null); + const [error, setError] = useState(null); + const preview = useLocalPreview(file); + + const done = (p: StudentProfile, message: string) => { + queryClient.setQueryData(['student', session?.tenant?.id, profile.id], p); + void queryClient.invalidateQueries({ queryKey: ['students'] }); + toast.success(message); + onClose(); + }; + const upload = useMutation({ + mutationFn: (f: File) => + client.api(`/students/${profile.id}/photo`, { + method: 'PUT', + body: imageForm(f), + }), + onSuccess: (p) => done(p, t('saved')), + onError: (e) => setError(describe(e)), + }); + const remove = useMutation({ + mutationFn: () => + client.api(`/students/${profile.id}/photo`, { method: 'DELETE' }), + onSuccess: (p) => done(p, t('photoRemoved')), + onError: (e) => setError(describe(e)), + }); + const pending = upload.isPending || remove.isPending; + + return ( + !open && !pending && onClose()}> + + + {t('photoTitle', { name })} + {t('photoHint')} + +
    + {preview ? ( + // eslint-disable-next-line @next/next/no-img-element + {t('photoPreview')} + ) : ( + + )} + {!preview && !profile.photoId && ( + {t('photoNone')} + )} + { + setError(null); + setFile(f); + }} + onTooLarge={() => setError(tErrors('fileTooLarge'))} + disabled={pending} + testId="photo-choose" + > + {t('photoChoose')} + + {error && ( +

    + {error} +

    + )} +
    + + {profile.photoId ? ( + + ) : ( + + )} + + +
    +
    + ); +} diff --git a/apps/web/src/lib/authed-image.ts b/apps/web/src/lib/authed-image.ts new file mode 100644 index 0000000..34a7b35 --- /dev/null +++ b/apps/web/src/lib/authed-image.ts @@ -0,0 +1,72 @@ +'use client'; + +import { useTranslations } from 'next-intl'; +import { useCallback, useEffect, useState } from 'react'; +import { ApiError } from '@/lib/api/errors'; +import { useAuth } from '@/lib/auth/auth-provider'; +import { useErrorMessage } from '@/lib/hooks'; + +// Stored images (docs/files.md) come from entity routes that need the bearer token, so an +// cannot load them itself: they are fetched with AuthClient.download and shown as object URLs. +// One fetch per image and version (the file id), shared by every component that shows it. + +const MAX_CACHED = 100; +const cache = new Map>(); + +function load(download: (path: string) => Promise, path: string, key: string) { + let entry = cache.get(key); + if (entry) return entry; + entry = download(path) + .then((blob) => URL.createObjectURL(blob)) + .catch(() => { + cache.delete(key); // not found or offline: try again next time + return null; + }); + cache.set(key, entry); + if (cache.size > MAX_CACHED) { + const [oldest, url] = cache.entries().next().value!; + cache.delete(oldest); + void url.then((u) => u && URL.revokeObjectURL(u)); + } + return entry; +} + +/** + * An object URL for an authenticated image route, or null (no image, loading, or not allowed). + * `version` is the stored file's id: a replaced image has a new one and is fetched again. + */ +export function useAuthedImage(path: string | null, version: string | null): string | null { + const { client } = useAuth(); + const key = path && version ? `${path}#${version}` : null; + const [shown, setShown] = useState<{ key: string; url: string | null } | null>(null); + useEffect(() => { + if (!key || !path) return; + let live = true; + void load((p) => client.download(p), path, key).then((url) => { + if (live) setShown({ key, url }); + }); + return () => { + live = false; + }; + }, [client, key, path]); + return key && shown?.key === key ? shown.url : null; +} + +/** The message for a failed image upload: the image codes, else the usual ones. */ +export function useImageErrorMessage() { + const t = useTranslations('errors'); + const describe = useErrorMessage(); + return useCallback( + (error: unknown): string => { + if (error instanceof ApiError) { + if (error.code === 'IMAGE_INVALID') return t('imageInvalid'); + if (error.code === 'IMAGE_TOO_BIG') return t('imageTooBig'); + if (error.code === 'IMAGE_CANNOT_SHRINK') return t('imageCannotShrink'); + if (error.code === 'STORAGE_FULL') return t('storageFull'); + if (error.status === 413) return t('fileTooLarge'); + } + return describe(error); + }, + [t, describe], + ); +} From 4e4cbb2f8d32935c50070608f4c9d61720a6189e Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:39:43 +0600 Subject: [PATCH 20/44] Docs for P2 (task 7): docs/files.md, database.md (the three tables and the FileStore rule), deploy.md and the production compose (FILE_STORAGE_PER_TENANT_MB, backup growth), .env.example, decisions-pending (F1-F12) Co-Authored-By: Claude Opus 5.5 --- .env.example | 4 ++ deploy/.env.prod.example | 3 ++ deploy/docker-compose.prod.yml | 2 + docs/database.md | 32 ++++++++++++ docs/decisions-pending.md | 34 ++++++++++++ docs/deploy.md | 9 ++++ docs/files.md | 94 ++++++++++++++++++++++++++++++++++ 7 files changed, 178 insertions(+) create mode 100644 docs/files.md diff --git a/.env.example b/.env.example index 91a09ee..1d8c44f 100644 --- a/.env.example +++ b/.env.example @@ -108,6 +108,10 @@ SMS_PROVIDER=console # INGEST_MAX_ATTLOG_BYTES=524288 # INGEST_MAX_DRAIN_BYTES=2097152 +# Stored images (photos, logos, signatures, seals) per institute, in MB (docs/files.md). Over it, +# uploads are refused with 413 STORAGE_FULL. Optional (default shown). +# FILE_STORAGE_PER_TENANT_MB=1024 + # --- Web (apps/web) --- NEXT_PUBLIC_API_URL=http://localhost:4000 # The boot refresh (docs/auth.md → Web client): on unless `off`. Read per request, no rebuild. diff --git a/deploy/.env.prod.example b/deploy/.env.prod.example index beed8cc..bcaa18a 100644 --- a/deploy/.env.prod.example +++ b/deploy/.env.prod.example @@ -50,6 +50,9 @@ SMS_PROVIDER=none TRUST_PROXY=1 # BullMQ key prefix in Redis. QUEUE_PREFIX=jantrik +# Stored images (photos, logos, signatures, seals) per institute, in MB: they live in the +# database and the backups (docs/files.md). Over it, uploads are refused (413 STORAGE_FULL). +FILE_STORAGE_PER_TENANT_MB=1024 # --- Device receiver --- # Devices connect directly: the receiver trusts no X-Forwarded-For (fixed in the compose file). diff --git a/deploy/docker-compose.prod.yml b/deploy/docker-compose.prod.yml index e8d4f56..b4f1677 100644 --- a/deploy/docker-compose.prod.yml +++ b/deploy/docker-compose.prod.yml @@ -37,6 +37,8 @@ x-api-env: &api-env OTP_PEPPER: ${OTP_PEPPER:?} PLATFORM_TOTP_KEY: ${PLATFORM_TOTP_KEY:?} SMS_PROVIDER: ${SMS_PROVIDER:-none} + # Stored images per institute, in MB (docs/files.md). + FILE_STORAGE_PER_TENANT_MB: ${FILE_STORAGE_PER_TENANT_MB:-1024} # The receiver is its own service below; the API only shows its address in the setup guide. INGEST_IN_PROCESS: 'false' INGEST_PUBLIC_HOST: ${DEVICE_HOST:?} diff --git a/docs/database.md b/docs/database.md index 936ba88..a9d4a08 100644 --- a/docs/database.md +++ b/docs/database.md @@ -498,6 +498,38 @@ one row per staff member per day (unique `(tenant_id, user_id, date)`), composit - Tests: `packages/db/test/staff-attendance-rls.test.ts`; the table list in `schema-safety.test.ts`. +### Files and the institute profile (sprint 1 P2) + +Images live in the database ([files.md](files.md), decision S7): + +- **`stored_files`** (tenant table): one re-encoded image per row (`bytes bytea`), with `kind` + (`stored_file_kind`), `mime`, `size_bytes`, `sha256`, `width`, `height`, `created_by_id`. + - Grants SELECT, INSERT, DELETE: a file never changes (a replaced image is a new row and the old + one is deleted), so there is no `updated_at` either. + - CHECKs: the formats per kind (`stored_files_mime`), the size per kind and + `size_bytes = octet_length(bytes)` (`stored_files_size`), the hash format and 1–4000 pixels a + side. The caps equal `FILE_LIMITS` in `packages/shared/src/files.ts`. + - **Only `PostgresFileStore` reads or writes it** (and `stored_file_usage`); the rest of the API + goes through the `FileStore` interface. `apps/api/src/files/file-store-access.spec.ts` fails on + any other code that names them. Test code may read them. + - Selecting a file's row reads its bytes (up to 256 KB): select the columns you need + (`meta()` does), never whole rows in a list. +- **`stored_file_usage`** (tenant table, at most one row per institute, created by the first + upload): the running total for the cap. Grants SELECT, INSERT, UPDATE (no DELETE); CHECK both + counters ≥ 0. Changed only under the institute's advisory lock, in the same transaction as the + file. +- **`institute_profiles`** (tenant table, at most one row per institute, created on the first save + or image): the institute's own names, EIIN, address, contact, head of institute, established + year, and `logo_file_id`, `head_signature_file_id`, `seal_file_id`. `tenants.name` stays the name + the platform registered. Grants SELECT, INSERT, UPDATE (no DELETE). CHECKs: one name at least, + lengths, a 6-digit EIIN, a 5–15 digit phone (optional `+`), e-mail and website shapes, a year + 1800–2100, and the three images being different files. +- **`students.photo_file_id`** replaces the never-written `photo_url`. +- **Every reference to a file is a composite foreign key** (`(tenant_id, x) → stored_files +(tenant_id, id)`, `ON DELETE RESTRICT ON UPDATE RESTRICT`) and unique, so a row can only point at + its own institute's file, a file is used in one place, and a file still in use cannot be deleted. +- Isolation, grants, CHECKs and keys: `packages/db/test/files-rls.test.ts`. + ## Querying: `withContext`, `withTenant`, `tenantClient` > **In the API, services never call these.** Every authenticated request already runs inside one diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index 453bd24..ae6c178 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -656,3 +656,37 @@ P1-I. **Open, for the owner: catch part of an institute's name too?** The rule r P1-J. **Follow-up, for the owner: hide `users.password_hash` from the app login.** Real staff hashes now exist, and `jantrik_app` may still SELECT every column of the users it can see (itself, and the members of the current institute, through `users_visible`). An injection in a request could read co-members' hashes (argon2id, so slow to attack, but still). The fix: revoke SELECT on that column from `jantrik_app` and read `hasPassword` through a definer function, as the login already does; every full-row read of `users` in the app and the tests must then name its columns. A database and security change, so it needs a plan and your approval first. P1-K. **Fixed from the review** (each with a test that failed first): a code is single use even when two requests race with it (login codes too); the phone rule ignores every punctuation mark and symbol between the digits; the other sessions are revoked in one statement; the common-password list is read at start-up; password login accepts up to 512 code points (a 128-character password typed decomposed); the wrong-code message asks to check the code before sending a new one. Kept as they are: the staff check after a correct password costs one extra query (it only confirms a password the caller already has); the login page's hint sits under the password tab, which guardians do not use. + +## Sprint 1, P2: institute profile, files, photos (2026-11-16) + +Plan: [plans/sprint-1-p2-files.md](plans/sprint-1-p2-files.md), written and built during the unattended day run of 2026-11-16 (the owner asked for it while away). The PR is the approval step. Each decision below is the safe default; all are reversible. + +F1. **Who sees what.** A student's photo is part of the full record, as on the student's page today (the basic view for a teacher of another section already left it out): OWNER and ADMIN for every student, a TEACHER for the students of their current sections, a guardian for their own children only (`GET /me/children/:id/photo`). Anyone else gets 404, as for a student that does not exist. The logo: every member, guardians too. The head's signature and the seal: OWNER and ADMIN only (they could be misused on forged papers; P8/P9 widen this for printing). The profile fields: OWNER and ADMIN. + +F2. **Lists keep initials.** The student list, the cards view and other lists do not load photos: fifty photos of up to 200 KB would not fit the 3 s budget on slow 4G. Photos show on the student's page and side peek, the guardian's child card and the report card. A small thumbnail kind for lists is a follow-up. + +F3. **`photoId` replaces `photoUrl`** in every API type (student list, profile, guardian children, report cards, admit cards): the stored file's id or null. The web fetches the image with the bearer token from the entity route and caches it by that id. + +F4. **EIIN is exactly 6 digits** (BANBEIS), optional. One CHECK to widen if an institute has another form. + +F5. **The institute's phone** may be a mobile (stored as E.164) or a landline (5–15 digits, optional `+`). + +F6. **An image uploaded before the first save** creates the profile with the registered name (`tenants.name`) in its script (Bangla or English), so the "one name" rule holds. + +F7. **Formats.** JPEG, PNG and WebP only, by content. HEIC is refused (iPhones send JPEG to the browser's file picker; sharp's prebuilt build cannot decode HEVC). A transparent photo is flattened on white. Truncated files are refused; other decoder warnings are tolerated (some phone JPEGs have harmless ones). + +F8. **60 uploads per person per 10 minutes** (`file-upload:`), on top of the general limits: each upload costs CPU. + +F9. **A deactivated student's photo** can be viewed by OWNER/ADMIN but not changed (409 `DEACTIVATED`, like other student writes). + +F10. **Replacing an image deletes the old file** in the same transaction; there is no image history. The audit row keeps the old and the new file id. + +F11. **The per-institute total is counted, not recomputed**, under the institute's advisory lock; tests check it equals the sum of the files after puts, replaces, deletes and two uploads at once. + +F12. **No institute header or logo on the report card yet.** The profile and images exist for P3 (the admission slip), P8 and P9 (documents); the report card gains only the student photo, as the sprint plan says. + +Also decided while building: + +- The migrations were written by hand (no development database is used in this run) and checked with `prisma migrate diff` against a scratch database: empty. +- `sharp` 0.35.5 was already in the lockfile through Next.js; the API now depends on it directly (S8). +- Encoding effort is moderate (PNG palette effort 4, WebP effort 4): the worst case (pure noise) stays well under the request's 15 s; a test pins it under 8 s per image on this PC. diff --git a/docs/deploy.md b/docs/deploy.md index e4744f3..40a239a 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -105,6 +105,9 @@ Fill in every value of `deploy/.env.prod` (git-ignored, never commit it): `openssl rand -hex 24` each, all different. Letters and digits only, because they go into connection URLs as they are. Postgres takes the superuser's and the roles' passwords on its **first start only** (below). +- **Stored images:** `FILE_STORAGE_PER_TENANT_MB` (optional, default 1024): each institute's + total for photos, logos, signatures and seals, which live in the database + ([files.md](files.md)). Over it, uploads get 413 `STORAGE_FULL`. - **Redis memory:** `REDIS_MAXMEMORY` (default `512mb`, about an eighth of a 4 GB server). Redis refuses writes beyond it rather than evicting anything, so watch it (Monitoring) and raise it before it fills. @@ -362,6 +365,12 @@ deletes backups older than `BACKUP_KEEP_DAYS` (default 14) and writes `LAST_SUCC are private (mode 600) and belong to `BACKUP_UID:BACKUP_GID`, the deploy user, so its own cron jobs can copy them away. +**Images are in the database** ([files.md](files.md)): every student photo, logo, signature and +seal is in the dump. Expect about 100 MB more per 2 000 photos (photos are at most 200 KB, usually +about half that; JPEGs do not compress further). Size the backup folder and the off-site copy for +it, and watch the dump's size (Monitoring). If it grows past what the backup window allows, the +files move to a bucket (decision S7) without changing the app. + Create the folder once, outside the git checkout (a `git clean` there would delete it), owned by the deploy user, and put that user's ids in the settings file: diff --git a/docs/files.md b/docs/files.md new file mode 100644 index 0000000..abb8da2 --- /dev/null +++ b/docs/files.md @@ -0,0 +1,94 @@ +# Files: photos, logos, signatures and seals + +How Jantrik stores images (sprint 1 P2, decision S7). The plan with its decisions F1–F12 is +[plans/sprint-1-p2-files.md](plans/sprint-1-p2-files.md). + +## Where files live + +- **In Postgres**, table `stored_files` (`bytes bytea`), a tenant table under forced RLS like every + other. The existing backups (`pg_dump`) cover the files; nothing else to back up. +- **Only `PostgresFileStore`** (`apps/api/src/files/postgres-file-store.ts`) touches + `stored_files` and `stored_file_usage`. Everything else uses the `FileStore` interface + (`file-store.ts`: `lock`, `put`, `get`, `meta`, `delete`, `usage`). + `file-store-access.spec.ts` fails the build if other code names those tables. +- **Moving to a bucket (R2/S3) later** is a new `FileStore` implementation plus a one-off job that + copies each row's bytes to the bucket. Callers and routes do not change; `stored_files` keeps + the metadata and loses the bytes. + +## What is stored + +Never the uploaded file. `ImageService` (`apps/api/src/files/image.service.ts`, `sharp`): + +1. checks the magic bytes: JPEG, PNG or WebP only (no SVG, GIF, HEIC, PDF), whatever the browser + said the type or name was; +2. reads only the header and refuses more than 50 megapixels (`UPLOAD_MAX_PIXELS`) before + decoding anything, so a decompression bomb costs nothing; +3. decodes once (the first frame of an animation), turns it upright (EXIF orientation), shrinks it + into the kind's box, and re-encodes it until it fits the kind's cap; +4. never copies metadata: EXIF (with GPS), ICC, XMP and comments are gone. + +At most two images are processed at once per API process. + +| Kind | Stored as | Cap | Box | Used by | +| ----------------- | --------------------------------- | ------ | --------- | ---------------------------------------- | +| `STUDENT_PHOTO` | JPEG (transparency on white) | 200 KB | 600 × 800 | the student's page, report cards | +| `APPLICANT_PHOTO` | JPEG | 200 KB | 600 × 800 | P3 (online admission) | +| `LOGO`, `SEAL` | PNG, or WebP when a PNG won't fit | 100 KB | 512 × 512 | the institute profile | +| `SIGNATURE` | PNG | 100 KB | 600 × 240 | the institute profile (the head) | +| `DOCUMENT_ASSET` | JPEG, PNG or WebP | 256 KB | — | P8 (the document designer; no route yet) | + +The caps are in `packages/shared/src/files.ts` (`FILE_LIMITS`) and again in the database +(`stored_files_size`, `stored_files_mime`), so a bug in the code cannot store more. + +## The per-institute total + +- `stored_file_usage` (one row per institute, created by the first upload): `bytes_used`, + `file_count`. +- Every `put` and `delete` takes the institute's advisory lock + (`hashtextextended('stored-files:' || tenant)`) and changes the total in the same transaction, + so the total always equals the sum of the rows, even with uploads at the same moment. +- Over `FILE_STORAGE_PER_TENANT_MB` (default 1024): 413 `STORAGE_FULL` with `bytesUsed` and + `capBytes`. A per-institute limit set by the platform can come later. +- Code that replaces or clears an image calls `lock()` (or `put`, which takes it) **before** + reading which file a row points at, so two changes of one image cannot both delete or keep the + same old file. + +## Routes + +Entity routes only; there is no `/files/:id`. + +| Route | Who | +| ------------------------------------------ | -------------------------------------------------------- | +| `GET /students/:id/photo` | OWNER, ADMIN; a TEACHER of the student's current section | +| `PUT`, `DELETE /students/:id/photo` | OWNER, ADMIN (not for a deactivated student: 409) | +| `GET /me/children/:id/photo` | the guardian, for their own children only (else 404) | +| `GET`, `PUT /institute/profile` | OWNER, ADMIN | +| `PUT`, `DELETE /institute/profile/:slot` | OWNER, ADMIN (`logo`, `signature`, `seal`) | +| `GET /institute/profile/logo` | every member, guardians too | +| `GET /institute/profile/signature`, `seal` | OWNER, ADMIN | + +- A student's photo is part of the full record, as on the student's page: a teacher of another + section, and the student list for them, get no photo (404 / `photoId: null`). +- Uploads are `multipart/form-data` with one field, `file`, at most 5 MB (`UPLOAD_MAX_BYTES`; + bigger: 413), at most 60 per person per 10 minutes (429). +- Errors: 400 `FILE_REQUIRED`, 422 `IMAGE_INVALID`, 422 `IMAGE_TOO_BIG`, 422 `IMAGE_CANNOT_SHRINK`, + 413 `STORAGE_FULL`, 409 `DEACTIVATED`. +- Answers carry a strong `ETag` (the SHA-256 of the stored bytes) and + `Cache-Control: private, no-cache`; a matching `If-None-Match` gets 304 without the bytes being + read. +- Replacing an image deletes the old file in the same transaction; the audit row keeps both ids + (`student` → `photoFileId`, `institute_profile` → `{image, fileId}`). + +## The web + +- Images need the bearer token, so `` cannot load them: `useAuthedImage(path, fileId)` + (`apps/web/src/lib/authed-image.ts`) fetches with `AuthClient.download` and returns an object + URL, shared by every component and cached per path and file id (a replaced image has a new id). +- `StudentAvatar` / `StudentPhoto` (`components/student-photo.tsx`) show a student's photo. Lists + keep initials (decision F2): fifty photos would not fit the 3 s budget on slow 4G. +- API types carry `photoId` (the stored file's id or null), never a URL. + +## Backups and size + +About 100 MB per 2 000 photos. The custom-format `pg_dump` does not shrink JPEGs further, so the +backup grows by about that much; see [deploy.md](deploy.md) → Backups. From 724ffb0a7d6bf6f4603ebf6eecc6800a9e7339a0 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 13:51:05 +0600 Subject: [PATCH 21/44] The photo dialog's preview URL is made when a file is chosen, not in an effect (lint: no setState inside an effect); it is revoked when another file is chosen or the dialog closes Co-Authored-By: Claude Opus 5.5 --- apps/web/src/components/image-upload.tsx | 36 +++++++++++++------ .../src/components/students/photo-dialog.tsx | 5 ++- 2 files changed, 27 insertions(+), 14 deletions(-) diff --git a/apps/web/src/components/image-upload.tsx b/apps/web/src/components/image-upload.tsx index 9f4714f..285a0b5 100644 --- a/apps/web/src/components/image-upload.tsx +++ b/apps/web/src/components/image-upload.tsx @@ -2,7 +2,7 @@ import { UPLOAD_ACCEPT, UPLOAD_MAX_BYTES } from '@jantrik/shared'; import { ImageUpIcon } from 'lucide-react'; -import { useEffect, useId, useRef, useState, type ReactNode } from 'react'; +import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from 'react'; import { Button } from '@/components/ui/button'; /** @@ -61,16 +61,30 @@ export function ChooseImageButton({ ); } -/** An object URL for a chosen file, revoked when the file changes or the view goes. */ -export function useLocalPreview(file: File | null): string | null { - const [url, setUrl] = useState<{ file: File; url: string } | null>(null); - useEffect(() => { - if (!file) return; - const next = URL.createObjectURL(file); - setUrl({ file, url: next }); - return () => URL.revokeObjectURL(next); - }, [file]); - return file && url?.file === file ? url.url : null; +/** + * The chosen file and an object URL to preview it. The URL is made when a file is chosen (not in + * an effect) and revoked when another is chosen or the view goes. + */ +export function useFilePreview(): { + file: File | null; + preview: string | null; + choose: (file: File | null) => void; +} { + const [chosen, setChosen] = useState<{ file: File; url: string } | null>(null); + const current = useRef(null); + useEffect( + () => () => { + if (current.current) URL.revokeObjectURL(current.current); + }, + [], + ); + const choose = useCallback((file: File | null) => { + if (current.current) URL.revokeObjectURL(current.current); + const url = file ? URL.createObjectURL(file) : null; + current.current = url; + setChosen(file && url ? { file, url } : null); + }, []); + return { file: chosen?.file ?? null, preview: chosen?.url ?? null, choose }; } /** The body of an image upload: the field `file`, as the API's multipart routes expect. */ diff --git a/apps/web/src/components/students/photo-dialog.tsx b/apps/web/src/components/students/photo-dialog.tsx index c24973a..c6a031d 100644 --- a/apps/web/src/components/students/photo-dialog.tsx +++ b/apps/web/src/components/students/photo-dialog.tsx @@ -6,7 +6,7 @@ import { Trash2Icon } from 'lucide-react'; import { useTranslations } from 'next-intl'; import { useState } from 'react'; import { toast } from 'sonner'; -import { ChooseImageButton, imageForm, useLocalPreview } from '@/components/image-upload'; +import { ChooseImageButton, imageForm, useFilePreview } from '@/components/image-upload'; import { StudentAvatar } from '@/components/student-photo'; import { Button } from '@/components/ui/button'; import { @@ -38,9 +38,8 @@ export function PhotoDialog({ const describe = useImageErrorMessage(); const { client, session } = useAuth(); const queryClient = useQueryClient(); - const [file, setFile] = useState(null); + const { file, preview, choose: setFile } = useFilePreview(); const [error, setError] = useState(null); - const preview = useLocalPreview(file); const done = (p: StudentProfile, message: string) => { queryClient.setQueryData(['student', session?.tenant?.id, profile.id], p); From 110857dea38efd22dbf8723ef1b33d189be3004e Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:03:37 +0600 Subject: [PATCH 22/44] =?UTF-8?q?files.spec:=20the=20profile=20fields=20by?= =?UTF-8?q?=20id=20("=E0=A6=A8=E0=A6=BE=E0=A6=AE=20(=E0=A6=AC=E0=A6=BE?= =?UTF-8?q?=E0=A6=82=E0=A6=B2=E0=A6=BE)"=20is=20also=20part=20of=20the=20h?= =?UTF-8?q?ead's=20name=20label)=20and=20a=20student=20link=20with=20an=20?= =?UTF-8?q?id=20(the=20first=20/students/=20link=20was=20the=20new-student?= =?UTF-8?q?=20button);=20found=20by=20CI's=20first=20run?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- apps/web/e2e/files.spec.ts | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/apps/web/e2e/files.spec.ts b/apps/web/e2e/files.spec.ts index c289d9b..9a6068d5 100644 --- a/apps/web/e2e/files.spec.ts +++ b/apps/web/e2e/files.spec.ts @@ -19,16 +19,16 @@ test.describe('files', () => { test('the owner fills the institute profile and adds a logo', async ({ page }) => { await page.goto('/setup/profile'); const form = page.getByTestId('institute-profile-form'); - // A new profile starts with the registered name. - await expect(form.getByLabel('নাম (বাংলা)')).toHaveValue(DEMO.shaplaName); - await form.getByLabel('EIIN').fill('১০৮১২৩'); - await form.getByLabel('প্রতিষ্ঠার সাল').fill('১৯৬৫'); + // A new profile starts with the registered name (fields by id: "নাম (বাংলা)" is also part of + // the head's "প্রধানের নাম (বাংলা)"). + await expect(form.locator('#profile-nameBn')).toHaveValue(DEMO.shaplaName); + await form.locator('#profile-eiin').fill('১০৮১২৩'); + await form.locator('#profile-establishedYear').fill('১৯৬৫'); await form.getByTestId('profile-save').click(); await expect(page.getByText('সংরক্ষণ হয়েছে').first()).toBeVisible(); await page.reload(); - await expect(page.getByTestId('institute-profile-form').getByLabel('EIIN')).toHaveValue( - '108123', - ); + await expect(page.locator('#profile-eiin')).toHaveValue('108123'); + await expect(page.locator('#profile-establishedYear')).toHaveValue('1965'); const logo = page.getByTestId('image-logo'); await logo @@ -45,8 +45,11 @@ test.describe('files', () => { test("an admin adds a student's photo and sees it on the student's page", async ({ page }) => { await page.goto('/students'); - const first = page.locator('a[href^="/students/"]').first(); - const href = (await first.getAttribute('href'))!; + // A student's own page (not /students/new or /students/import). + const student = page.locator('a[href^="/students/0"]').first(); + await expect(student).toBeVisible(); + const href = (await student.getAttribute('href'))!; + expect(href).toMatch(/^\/students\/[0-9a-f]{8}-[0-9a-f-]{27}$/); await page.goto(href); const profile = page.getByTestId('student-profile'); await expect(profile).toBeVisible(); From 8c3a4f90df847a5354b789033a7efa6d77b548fb Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:06:07 +0600 Subject: [PATCH 23/44] After the review (P1-J7): a dedicated login for the password login. jantrik_login_app (DATABASE_LOGIN_URL) may run one function, auth_find_user_for_password_login, which returns the hash; jantrik_app may not, its own login lookup returns no password data, and the digest comparison (auth_my_password_matches) is gone: the review showed an injection could read any user's salt and test 200,000 guesses in one statement. The role is created by 01-roles.sh, create-roles.sh and CI, checked by the restore script and the production health check. Schema-safety: jantrik_app reads every users column but the hash (a column without its GRANT fails), the functions a runtime login may run whose owner can read the hash are pinned by name, none but the two logins' lookups returns a hash or a whole users row, and jantrik_login_app holds that one function only Co-Authored-By: Claude Opus 5.5 --- .env.example | 7 + .github/workflows/ci.yml | 10 +- deploy/.env.prod.example | 1 + deploy/backup/restore.sh | 2 +- deploy/docker-compose.prod.yml | 5 +- deploy/postgres/create-roles.sh | 18 ++- docker-compose.yml | 1 + docker/postgres/init/01-roles.sh | 9 +- .../migration.sql | 58 ++++---- packages/db/test/auth-functions.test.ts | 1 - packages/db/test/env.ts | 14 ++ packages/db/test/helpers.ts | 4 +- packages/db/test/schema-safety.test.ts | 134 +++++++++++++----- packages/db/test/users-password-hash.test.ts | 92 +++++------- 14 files changed, 229 insertions(+), 127 deletions(-) diff --git a/.env.example b/.env.example index 91a09ee..157f7e7 100644 --- a/.env.example +++ b/.env.example @@ -13,12 +13,16 @@ POSTGRES_PORT=5432 # that may run the platform_* functions # jantrik_ingest_app: the device (ZKTeco) receiver only; the only role that may run the # ingest_* functions +# jantrik_login_app: the password login only; the only role that may look up a password +# hash (auth_find_user_for_password_login) DB_OWNER_PASSWORD=owner_dev_password DB_APP_PASSWORD=app_dev_password # Password of jantrik_platform_app (the API platform module's role), set by the init script. DB_PLATFORM_PASSWORD=platform_dev_password # Password of jantrik_ingest_app (the device receiver's role), set by the init script. DB_INGEST_PASSWORD=ingest_dev_password +# Password of jantrik_login_app (the password login's role), set by the init script. +DB_LOGIN_PASSWORD=login_dev_password # Runtime connection (API, seed of tenant data): the RLS-restricted app role. DATABASE_URL=postgresql://jantrik_app:app_dev_password@localhost:5432/jantrik @@ -30,6 +34,9 @@ DATABASE_PLATFORM_URL=postgresql://jantrik_platform_app:platform_dev_password@lo # The device receiver (ZKTeco attendance machines): its own login, same database. Tests use this # user and password on the test / e2e database. DATABASE_INGEST_URL=postgresql://jantrik_ingest_app:ingest_dev_password@localhost:5432/jantrik +# The password login (POST /auth/login with a password): its own login, same database, the only +# one that may read a password hash. Tests use this user and password on the test / e2e database. +DATABASE_LOGIN_URL=postgresql://jantrik_login_app:login_dev_password@localhost:5432/jantrik # Integration tests (packages/db) use a separate database. DATABASE_URL_TEST=postgresql://jantrik_app:app_dev_password@localhost:5432/jantrik_test diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d3f60e..efe4392 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,12 +21,15 @@ env: DB_APP_PASSWORD: app_ci_password DB_PLATFORM_PASSWORD: platform_ci_password DB_INGEST_PASSWORD: ingest_ci_password + DB_LOGIN_PASSWORD: login_ci_password # Same roles as local dev; tests run against jantrik_test. DATABASE_URL: postgresql://jantrik_app:app_ci_password@localhost:5432/jantrik_test # The API platform module's own role (tests point it at their database themselves). DATABASE_PLATFORM_URL: postgresql://jantrik_platform_app:platform_ci_password@localhost:5432/jantrik_test # The device receiver's own role (tests point it at their database themselves). DATABASE_INGEST_URL: postgresql://jantrik_ingest_app:ingest_ci_password@localhost:5432/jantrik_test + # The password login's own role (tests point it at their database themselves). + DATABASE_LOGIN_URL: postgresql://jantrik_login_app:login_ci_password@localhost:5432/jantrik_test DATABASE_MIGRATION_URL: postgresql://jantrik_owner:owner_ci_password@localhost:5432/jantrik_test DATABASE_URL_TEST: postgresql://jantrik_app:app_ci_password@localhost:5432/jantrik_test DATABASE_MIGRATION_URL_TEST: postgresql://jantrik_owner:owner_ci_password@localhost:5432/jantrik_test @@ -261,22 +264,25 @@ jobs: APP=$(openssl rand -hex 24) PLATFORM=$(openssl rand -hex 24) INGEST=$(openssl rand -hex 24) - for pw in "$OWNER" "$APP" "$PLATFORM" "$INGEST"; do echo "::add-mask::$pw"; done + LOGIN=$(openssl rand -hex 24) + for pw in "$OWNER" "$APP" "$PLATFORM" "$INGEST" "$LOGIN"; do echo "::add-mask::$pw"; done url() { echo "postgresql://$1:$2@localhost:5432/jantrik"; } { echo "DB_OWNER_PASSWORD=$OWNER" echo "DB_APP_PASSWORD=$APP" echo "DB_PLATFORM_PASSWORD=$PLATFORM" echo "DB_INGEST_PASSWORD=$INGEST" + echo "DB_LOGIN_PASSWORD=$LOGIN" echo "DATABASE_MIGRATION_URL=$(url jantrik_owner "$OWNER")" echo "DATABASE_URL=$(url jantrik_app "$APP")" echo "DATABASE_PLATFORM_URL=$(url jantrik_platform_app "$PLATFORM")" echo "DATABASE_INGEST_URL=$(url jantrik_ingest_app "$INGEST")" + echo "DATABASE_LOGIN_URL=$(url jantrik_login_app "$LOGIN")" } >> "$GITHUB_ENV" - name: Check the passwords are this run's run: | - for v in "$DB_OWNER_PASSWORD" "$DB_APP_PASSWORD" "$DB_PLATFORM_PASSWORD" "$DB_INGEST_PASSWORD"; do + for v in "$DB_OWNER_PASSWORD" "$DB_APP_PASSWORD" "$DB_PLATFORM_PASSWORD" "$DB_INGEST_PASSWORD" "$DB_LOGIN_PASSWORD"; do [ "${#v}" -eq 48 ] || { echo "a DB_*_PASSWORD is not this run's"; exit 1; } done case "$DATABASE_URL" in diff --git a/deploy/.env.prod.example b/deploy/.env.prod.example index beed8cc..97ff16e 100644 --- a/deploy/.env.prod.example +++ b/deploy/.env.prod.example @@ -25,6 +25,7 @@ DB_OWNER_PASSWORD=CHANGE_ME_openssl_rand_hex_24 DB_APP_PASSWORD=CHANGE_ME_openssl_rand_hex_24 DB_PLATFORM_PASSWORD=CHANGE_ME_openssl_rand_hex_24 DB_INGEST_PASSWORD=CHANGE_ME_openssl_rand_hex_24 +DB_LOGIN_PASSWORD=CHANGE_ME_openssl_rand_hex_24 POSTGRES_DB_NAME=jantrik # --- Redis --- diff --git a/deploy/backup/restore.sh b/deploy/backup/restore.sh index a792be6..f3e00a6 100755 --- a/deploy/backup/restore.sh +++ b/deploy/backup/restore.sh @@ -76,7 +76,7 @@ sql() { missing=$(sql -d postgres -c "SELECT string_agg(r, ', ') FROM unnest(ARRAY['jantrik_owner', 'jantrik_app', 'jantrik_auth', 'jantrik_search', 'jantrik_platform', 'jantrik_platform_app', - 'jantrik_ingest', 'jantrik_ingest_app']) AS r WHERE NOT EXISTS + 'jantrik_ingest', 'jantrik_ingest_app', 'jantrik_login_app']) AS r WHERE NOT EXISTS (SELECT FROM pg_roles WHERE rolname = r)") [ -z "$missing" ] \ || die "roles missing ($missing): run deploy/postgres/create-roles.sh first (roles are not in a backup)" diff --git a/deploy/docker-compose.prod.yml b/deploy/docker-compose.prod.yml index e8d4f56..1abb519 100644 --- a/deploy/docker-compose.prod.yml +++ b/deploy/docker-compose.prod.yml @@ -25,6 +25,8 @@ x-api-env: &api-env API_PORT: '4000' DATABASE_URL: postgresql://jantrik_app:${DB_APP_PASSWORD:?}@postgres:5432/${POSTGRES_DB_NAME:-jantrik} DATABASE_PLATFORM_URL: postgresql://jantrik_platform_app:${DB_PLATFORM_PASSWORD:?}@postgres:5432/${POSTGRES_DB_NAME:-jantrik} + # The password login's own login (P1-J): the only one that may look up a password hash. + DATABASE_LOGIN_URL: postgresql://jantrik_login_app:${DB_LOGIN_PASSWORD:?}@postgres:5432/${POSTGRES_DB_NAME:-jantrik} REDIS_URL: redis://:${REDIS_PASSWORD:?}@redis:6379 QUEUE_PREFIX: ${QUEUE_PREFIX:-jantrik} CORS_ORIGINS: https://${APP_DOMAIN:?},https://${PLATFORM_DOMAIN:?} @@ -58,6 +60,7 @@ services: DB_APP_PASSWORD: ${DB_APP_PASSWORD:?} DB_PLATFORM_PASSWORD: ${DB_PLATFORM_PASSWORD:?} DB_INGEST_PASSWORD: ${DB_INGEST_PASSWORD:?} + DB_LOGIN_PASSWORD: ${DB_LOGIN_PASSWORD:?} JANTRIK_DB_NAME: ${POSTGRES_DB_NAME:-jantrik} TZ: UTC volumes: @@ -74,7 +77,7 @@ services: - CMD-SHELL - >- psql -h 127.0.0.1 -U postgres -d "$$JANTRIK_DB_NAME" -XAtc - "SELECT EXISTS (SELECT FROM pg_roles WHERE rolname = 'jantrik_ingest_app') + "SELECT EXISTS (SELECT FROM pg_roles WHERE rolname = 'jantrik_login_app') AND has_schema_privilege('jantrik_app', 'public', 'USAGE') AND NOT has_schema_privilege('public', 'public', 'USAGE') AND NOT has_database_privilege('public', current_database(), 'TEMPORARY') diff --git a/deploy/postgres/create-roles.sh b/deploy/postgres/create-roles.sh index 01b5a2c..e9c13e6 100755 --- a/deploy/postgres/create-roles.sh +++ b/deploy/postgres/create-roles.sh @@ -62,6 +62,7 @@ jantrik_create_roles() ( check_password DB_APP_PASSWORD "${DB_APP_PASSWORD:-}" check_password DB_PLATFORM_PASSWORD "${DB_PLATFORM_PASSWORD:-}" check_password DB_INGEST_PASSWORD "${DB_INGEST_PASSWORD:-}" + check_password DB_LOGIN_PASSWORD "${DB_LOGIN_PASSWORD:-}" # The superuser's own password when this script is given it (the compose Postgres's first # start): as strong as the others, and none of them. In the compose Postgres the image has set # it already, so deploy/compose.sh checks it before the first start; this is the second check. @@ -72,7 +73,7 @@ jantrik_create_roles() ( dupes=$( { printf '%s\n' "$DB_OWNER_PASSWORD" "$DB_APP_PASSWORD" "$DB_PLATFORM_PASSWORD" \ - "$DB_INGEST_PASSWORD" + "$DB_INGEST_PASSWORD" "$DB_LOGIN_PASSWORD" if [ -n "${POSTGRES_PASSWORD:-}" ]; then printf '%s\n' "$POSTGRES_PASSWORD"; fi } | sort | uniq -d ) @@ -84,6 +85,7 @@ SET client_min_messages TO warning; \getenv app_pw DB_APP_PASSWORD \getenv platform_pw DB_PLATFORM_PASSWORD \getenv ingest_pw DB_INGEST_PASSWORD +\getenv login_pw DB_LOGIN_PASSWORD -- Each role as in docker/postgres/init/01-roles.sh (docs/database.md → Database roles). -- Owns the schema and runs migrations. Not a superuser, so FORCE ROW LEVEL SECURITY applies to it. @@ -101,6 +103,9 @@ SELECT format('CREATE ROLE jantrik_ingest_app LOGIN NOSUPERUSER NOBYPASSRLS NOCR -- Its statements stop after 5 s (decision #79). The receiver's pool sends the same limit and the -- receiver refuses to start without it; set on every run, so an existing role gets it too. ALTER ROLE jantrik_ingest_app SET statement_timeout = '5s'; +-- The password login (DATABASE_LOGIN_URL): auth_find_user_for_password_login only (P1-J). +SELECT format('CREATE ROLE jantrik_login_app LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE PASSWORD %L', :'login_pw') + WHERE NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'jantrik_login_app') \gexec -- Owners of the SECURITY DEFINER functions: no login, no RLS bypass. jantrik_owner may SET ROLE -- to them (migrations hand them their functions) but never inherits them: their policies would @@ -127,7 +132,7 @@ BEGIN SELECT string_agg(r, ', ') INTO missing FROM unnest(ARRAY['jantrik_owner', 'jantrik_app', 'jantrik_auth', 'jantrik_search', 'jantrik_platform', 'jantrik_platform_app', 'jantrik_ingest', - 'jantrik_ingest_app']) AS r + 'jantrik_ingest_app', 'jantrik_login_app']) AS r WHERE NOT EXISTS (SELECT FROM pg_roles WHERE rolname = r); IF missing IS NOT NULL THEN RAISE EXCEPTION 'roles missing: %', missing; @@ -142,16 +147,19 @@ BEGIN SELECT string_agg(rolname, ', ') INTO bad FROM pg_roles WHERE (rolname IN ('jantrik_auth', 'jantrik_search', 'jantrik_platform', 'jantrik_ingest') AND rolcanlogin) - OR (rolname IN ('jantrik_owner', 'jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app') + OR (rolname IN ('jantrik_owner', 'jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app', + 'jantrik_login_app') AND NOT rolcanlogin) - OR (rolname IN ('jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app') AND rolcreatedb); + OR (rolname IN ('jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app', + 'jantrik_login_app') AND rolcreatedb); IF bad IS NOT NULL THEN RAISE EXCEPTION 'roles with the wrong LOGIN or CREATEDB attribute: %', bad; END IF; -- The runtime logins are members of no role (jantrik_app's rights are its own grants). SELECT string_agg(DISTINCT pg_get_userbyid(member)::text, ', ') INTO bad FROM pg_auth_members - WHERE pg_get_userbyid(member) IN ('jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app'); + WHERE pg_get_userbyid(member) IN ('jantrik_app', 'jantrik_platform_app', 'jantrik_ingest_app', + 'jantrik_login_app'); IF bad IS NOT NULL THEN RAISE EXCEPTION 'runtime logins must be members of no role: %', bad; END IF; diff --git a/docker-compose.yml b/docker-compose.yml index 57dfe9b..459c4f2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,6 +13,7 @@ services: DB_APP_PASSWORD: ${DB_APP_PASSWORD:-app_dev_password} DB_PLATFORM_PASSWORD: ${DB_PLATFORM_PASSWORD:-platform_dev_password} DB_INGEST_PASSWORD: ${DB_INGEST_PASSWORD:-ingest_dev_password} + DB_LOGIN_PASSWORD: ${DB_LOGIN_PASSWORD:-login_dev_password} TZ: UTC ports: - '${POSTGRES_PORT:-5432}:5432' diff --git a/docker/postgres/init/01-roles.sh b/docker/postgres/init/01-roles.sh index 8810391..bcc560b 100644 --- a/docker/postgres/init/01-roles.sh +++ b/docker/postgres/init/01-roles.sh @@ -6,7 +6,8 @@ set -eu psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname postgres \ -v owner_pw="$DB_OWNER_PASSWORD" -v app_pw="$DB_APP_PASSWORD" \ - -v platform_pw="$DB_PLATFORM_PASSWORD" -v ingest_pw="$DB_INGEST_PASSWORD" <<'SQL' + -v platform_pw="$DB_PLATFORM_PASSWORD" -v ingest_pw="$DB_INGEST_PASSWORD" \ + -v login_pw="$DB_LOGIN_PASSWORD" <<'SQL' -- Owns the schema and runs migrations. Not a superuser, so FORCE ROW LEVEL SECURITY applies to it. -- CREATEDB is needed for Prisma's shadow database during `prisma migrate dev`. CREATE ROLE jantrik_owner LOGIN CREATEDB NOSUPERUSER NOBYPASSRLS PASSWORD :'owner_pw'; @@ -51,6 +52,12 @@ CREATE ROLE jantrik_ingest_app LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATE -- Its statements stop after 5 s (decision #79); the receiver's pool sends the same limit. ALTER ROLE jantrik_ingest_app SET statement_timeout = '5s'; +-- Runtime role of the password login only (DATABASE_LOGIN_URL, P1-J). It may run one function, +-- auth_find_user_for_password_login, and nothing else: no table grants and NOT a member of +-- jantrik_app. jantrik_app may not run that function, so an SQL injection in an institute +-- request never reaches a password hash. Schema USAGE comes from a migration. +CREATE ROLE jantrik_login_app LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE PASSWORD :'login_pw'; + CREATE DATABASE jantrik OWNER jantrik_owner; CREATE DATABASE jantrik_test OWNER jantrik_owner; -- Playwright end-to-end tests (seeded demo data). diff --git a/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql index ec197ea..73662be 100644 --- a/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql +++ b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql @@ -1,5 +1,10 @@ -- P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's, so an SQL --- injection in a request cannot take staff hashes away to crack offline (docs/database.md → users). +-- injection in an institute request cannot take staff hashes away to crack offline. Only the +-- password-login login (jantrik_login_app, DATABASE_LOGIN_URL) may look a hash up, through one +-- function (docs/database.md → users, docs/auth.md → The API never reads a hash in a request). +-- jantrik_login_app must exist first: docker/postgres/init/01-roles.sh, or for an existing local +-- volume the commands in docs/database.md → Database roles; deploy/postgres/create-roles.sh in +-- production. -- ───────────── users: SELECT by column, every column but password_hash ───────────── -- A table-level SELECT covers every column (a column REVOKE would change nothing), so the table @@ -10,22 +15,18 @@ GRANT SELECT (id, phone, email, name, name_bn, password_changed_at, locale, colo created_at, updated_at) ON users TO jantrik_app; --- ───────────── auth_find_user_for_login(): parameters and salt, never the digest ───────────── +-- ───────────── auth_find_user_for_login(): no password data ───────────── -- It returned password_hash of any user by phone or email, which made the column grant above --- pointless. It now returns the PHC string up to its last `$` (argon2id, version 19, m, t, p and --- the salt); the API hashes the typed password with them and auth_my_password_matches() compares. --- Only the format Jantrik writes is accepted (a 32-byte digest); anything else gives NULL, as a --- corrupt hash would fail today. A changed result type needs DROP + CREATE. Privileges are set --- BEFORE the ownership change (see fix_definer_function_privileges). +-- pointless. The OTP login and the profile read need only who the person is. A changed result type +-- needs DROP + CREATE. Privileges are set BEFORE the ownership change (see +-- fix_definer_function_privileges). DROP FUNCTION auth_find_user_for_login(text, text); CREATE FUNCTION auth_find_user_for_login(p_phone text, p_email text) - RETURNS TABLE (id uuid, name text, locale locale, password_params text) + RETURNS TABLE (id uuid, name text, locale locale) LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, public, pg_temp AS $$ - SELECT u.id, u.name, u.locale, - substring(u.password_hash FROM - '^(\$argon2id\$v=19\$m=[0-9]{1,10},t=[0-9]{1,10},p=[0-9]{1,3}\$[A-Za-z0-9+/]{11,64})\$[A-Za-z0-9+/]{43}$') + SELECT u.id, u.name, u.locale FROM users u WHERE (p_phone IS NOT NULL AND u.phone = p_phone) OR (p_email IS NOT NULL AND lower(u.email) = lower(p_email)) @@ -35,28 +36,31 @@ REVOKE ALL ON FUNCTION auth_find_user_for_login(text, text) FROM PUBLIC; GRANT EXECUTE ON FUNCTION auth_find_user_for_login(text, text) TO jantrik_app; ALTER FUNCTION auth_find_user_for_login(text, text) OWNER TO jantrik_auth; --- ───────────── auth_my_password_matches(digest): the comparison, inside the database ───────────── --- True when the current user's (app.user_id) stored hash has this SHA-256. The API sends the --- SHA-256 of the hash it computed from the typed password, so the digest never leaves the --- database, and what travels is fixed-size. No user parameter: scoped by context, like --- auth_list_my_memberships(). -CREATE FUNCTION auth_my_password_matches(p_digest bytea) - RETURNS boolean +-- ───────────── auth_find_user_for_password_login(): the hash, for the login login only ───────────── +-- The password login (POST /auth/login) runs this on its own login (jantrik_login_app), which has +-- no table grants and may run nothing else, so an injection in an ordinary request (jantrik_app) +-- cannot reach it. The API verifies the password with argon2 itself. +CREATE FUNCTION auth_find_user_for_password_login(p_phone text, p_email text) + RETURNS TABLE (id uuid, name text, locale locale, password_hash text) LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, public, pg_temp AS $$ - SELECT EXISTS ( - SELECT 1 FROM users u - WHERE u.id = app_current_user_id() - AND u.password_hash IS NOT NULL - AND sha256(convert_to(u.password_hash, 'UTF8')) = p_digest - ) + SELECT u.id, u.name, u.locale, u.password_hash + FROM users u + WHERE (p_phone IS NOT NULL AND u.phone = p_phone) + OR (p_email IS NOT NULL AND lower(u.email) = lower(p_email)) + LIMIT 1 $$; -REVOKE ALL ON FUNCTION auth_my_password_matches(bytea) FROM PUBLIC; -GRANT EXECUTE ON FUNCTION auth_my_password_matches(bytea) TO jantrik_app; -ALTER FUNCTION auth_my_password_matches(bytea) OWNER TO jantrik_auth; +REVOKE ALL ON FUNCTION auth_find_user_for_password_login(text, text) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION auth_find_user_for_password_login(text, text) TO jantrik_login_app; +ALTER FUNCTION auth_find_user_for_password_login(text, text) OWNER TO jantrik_auth; + +-- The login login reaches the function through the schema; nothing else (no table grants). +GRANT USAGE ON SCHEMA public TO jantrik_login_app; -- ───────────── auth_my_password_is_set(): GET /me/password's hasPassword ───────────── +-- Scoped by app.user_id. A request can set that to any id with set_config, so an injection can +-- learn whether a given person has a password (yes or no, nothing more): docs/auth.md. CREATE FUNCTION auth_my_password_is_set() RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER diff --git a/packages/db/test/auth-functions.test.ts b/packages/db/test/auth-functions.test.ts index 6851cc6..c529ee6 100644 --- a/packages/db/test/auth-functions.test.ts +++ b/packages/db/test/auth-functions.test.ts @@ -8,7 +8,6 @@ const FUNCTIONS = [ 'auth_resolve_tenant', 'auth_find_refresh_token', 'app_find_or_create_user', - 'auth_my_password_matches', 'auth_my_password_is_set', ]; diff --git a/packages/db/test/env.ts b/packages/db/test/env.ts index fd19b39..377d7ac 100644 --- a/packages/db/test/env.ts +++ b/packages/db/test/env.ts @@ -65,3 +65,17 @@ export const INGEST_URL = (() => { url.password = new URL(login).password; return url.toString(); })(); + +/** + * The password login's own login (jantrik_login_app: user and password of DATABASE_LOGIN_URL) on + * the test database; server, port and database come from APP_URL. It may run one function, + * auth_find_user_for_password_login, and nothing else (P1-J). + */ +export const LOGIN_URL = (() => { + const login = process.env['DATABASE_LOGIN_URL']; + if (!login) throw new Error('DATABASE_LOGIN_URL is not set (see .env.example)'); + const url = new URL(APP_URL); + url.username = new URL(login).username; + url.password = new URL(login).password; + return url.toString(); +})(); diff --git a/packages/db/test/helpers.ts b/packages/db/test/helpers.ts index 74aa217..e8d59fc 100644 --- a/packages/db/test/helpers.ts +++ b/packages/db/test/helpers.ts @@ -8,7 +8,7 @@ import { type ProvisionTenantInput, type Tenant, } from '../src/index.js'; -import { APP_URL, INGEST_URL, OWNER_URL, PLATFORM_URL } from './env.js'; +import { APP_URL, INGEST_URL, LOGIN_URL, OWNER_URL, PLATFORM_URL } from './env.js'; export const appClient = (): PrismaClient => createPrismaClient(APP_URL); @@ -18,6 +18,8 @@ export const randomPhone = (): string => export const ownerClient = (): PrismaClient => createPrismaClient(OWNER_URL); /** The API platform module's role: the only one that may run the platform_* functions. */ export const platformClient = (): PrismaClient => createPrismaClient(PLATFORM_URL); +/** The password login's login (P1-J): only auth_find_user_for_password_login. */ +export const loginClient = (): PrismaClient => createPrismaClient(LOGIN_URL); /** The device receiver's login: no table grants, only the ingest_* functions. */ export const ingestClient = (): PrismaClient => createPrismaClient(INGEST_URL); diff --git a/packages/db/test/schema-safety.test.ts b/packages/db/test/schema-safety.test.ts index d562c7a..daefe11 100644 --- a/packages/db/test/schema-safety.test.ts +++ b/packages/db/test/schema-safety.test.ts @@ -125,11 +125,26 @@ describe('schema safety net', () => { ); }); + // P1-J: every definer function a runtime login may run whose owner can read + // users.password_hash ("login: function"). Each was checked to return nothing of the hash. + const PASSWORD_READING_OWNER_FUNCTIONS = [ + 'jantrik_app: app_find_or_create_user', // the id only + 'jantrik_app: auth_find_refresh_token', // the token's session and user ids + 'jantrik_app: auth_find_user_for_login', // id, name, locale + 'jantrik_app: auth_list_my_memberships', // memberships of app.user_id + 'jantrik_app: auth_my_password_is_set', // a boolean for app.user_id (P1-J2) + 'jantrik_app: auth_resolve_tenant', // the institute of a slug + 'jantrik_login_app: auth_find_user_for_password_login', // the hash: the password login only + ]; + // Whole-row patterns of a users row (u.*, to_jsonb(u), row_to_json(u), ...) in a function body. + const WHOLE_ROW_SQL = String.raw`\mu\.\*|\m(to_jsonb|to_json|row_to_json|jsonb_build_object|json_build_object|hstore)\s*\(\s*u\M`; + // SECURITY DEFINER functions see past RLS, so they must never trust a caller-supplied // tenant: scope comes only from app_current_tenant_id() / app_current_user_id(). // Exceptions: lookups that by design run before any tenant or user is known (login). const PRE_CONTEXT_AUTH_LOOKUPS = [ 'auth_find_user_for_login', + 'auth_find_user_for_password_login', 'auth_resolve_tenant', 'auth_find_refresh_token', ]; @@ -183,43 +198,33 @@ describe('schema safety net', () => { 'app_find_or_create_user', 'auth_list_my_memberships', 'auth_my_password_is_set', - 'auth_my_password_matches', 'search_student_ids', ]); expect(scoped.filter((r) => !r.scoped)).toEqual([]); }); - // P1-J: no login reads a password hash. jantrik_app reads users column by column, and the list - // is pinned here: a new column, or a table-level SELECT coming back, is a deliberate change. - it('the app login reads users by column, never password_hash', async () => { + // P1-J: only the password login's own login reads a password hash. jantrik_app may read every + // other users column, granted one by one: a new column without its GRANT fails here (whole-row + // reads of users, e.g. the refresh and /me, would otherwise fail at runtime). + it('the app login reads every users column but password_hash, with no table-level SELECT', async () => { const [table] = await app.$queryRaw<{ table_select: boolean }[]>` SELECT has_table_privilege('jantrik_app', 'users', 'SELECT') AS table_select`; expect(table).toEqual({ table_select: false }); - const columns = await app.$queryRaw<{ col: string }[]>` - SELECT a.attname::text AS col + const columns = await app.$queryRaw<{ col: string; readable: boolean }[]>` + SELECT a.attname::text AS col, + has_column_privilege('jantrik_app', 'users', a.attname, 'SELECT') AS readable FROM pg_attribute a WHERE a.attrelid = 'users'::regclass AND a.attnum > 0 AND NOT a.attisdropped - AND has_column_privilege('jantrik_app', 'users', a.attname, 'SELECT') ORDER BY a.attname`; - expect(columns.map((c) => c.col)).toEqual([ - 'color_scheme', - 'created_at', - 'email', - 'id', - 'locale', - 'name', - 'name_bn', - 'password_changed_at', - 'phone', - 'updated_at', - ]); + expect(columns.length).toBeGreaterThanOrEqual(10); + expect(columns.filter((c) => c.readable !== (c.col !== 'password_hash'))).toEqual([]); }); it('no login role but the owner, and not PUBLIC, may read users.password_hash', async () => { const readers = await app.$queryRaw<{ name: string }[]>` SELECT r.rolname::text AS name FROM pg_roles r - WHERE (r.rolcanlogin OR r.rolname = 'public') AND NOT r.rolsuper + WHERE r.rolcanlogin AND NOT r.rolsuper AND r.oid <> (SELECT relowner FROM pg_class WHERE oid = 'users'::regclass) AND has_column_privilege(r.oid, 'users'::regclass, 'password_hash', 'SELECT') UNION ALL @@ -227,22 +232,87 @@ describe('schema safety net', () => { expect(readers).toEqual([]); }); - // The hash must not come back through a function either: every definer function jantrik_app - // may run that touches password_hash is listed here, and none returns a column of that name. - it('only the three login functions the app may run touch password_hash, and none returns it', async () => { - const rows = await app.$queryRaw<{ fn: string; result: string }[]>` - SELECT p.proname::text AS fn, pg_get_function_result(p.oid) AS result + // The hash must not come back through a definer function either. Every function a runtime login + // may run whose owner can read password_hash is pinned by name: adding one is a deliberate change + // here, after checking that it returns nothing of the hash. + const RUNTIME_LOGINS = [ + 'jantrik_app', + 'jantrik_platform_app', + 'jantrik_ingest_app', + 'jantrik_login_app', + ]; + + it('the definer functions a runtime login may run, whose owner can read password_hash, are pinned', async () => { + const rows = await app.$queryRaw<{ entry: string }[]>` + SELECT r.login || ': ' || p.proname AS entry FROM pg_proc p + CROSS JOIN unnest(${RUNTIME_LOGINS}::text[]) AS r(login) WHERE p.pronamespace = 'public'::regnamespace AND p.prosecdef - AND has_function_privilege('jantrik_app', p.oid, 'EXECUTE') - AND p.prosrc ILIKE '%password_hash%' + AND has_function_privilege(r.login, p.oid, 'EXECUTE') + AND has_column_privilege(p.proowner, 'users'::regclass, 'password_hash', 'SELECT') ORDER BY 1`; - expect(rows.map((r) => r.fn)).toEqual([ - 'auth_find_user_for_login', - 'auth_my_password_is_set', - 'auth_my_password_matches', + expect(rows.map((r) => r.entry)).toEqual(PASSWORD_READING_OWNER_FUNCTIONS); + }); + + it('only the password lookup returns password_hash (or a whole users row), and only the login login may run it', async () => { + const rows = await app.$queryRaw<{ fn: string; result: string; runners: string[] }[]>` + SELECT p.proname::text AS fn, pg_get_function_result(p.oid) AS result, + ARRAY(SELECT r FROM unnest(${RUNTIME_LOGINS}::text[]) AS r + WHERE has_function_privilege(r, p.oid, 'EXECUTE') ORDER BY 1) AS runners + FROM pg_proc p + WHERE p.pronamespace = 'public'::regnamespace AND p.prosecdef + AND (pg_get_function_result(p.oid) ILIKE '%password_hash%' + OR p.prorettype = 'users'::regtype + OR p.prosrc ~* ${WHOLE_ROW_SQL}) + ORDER BY 1`; + expect(rows).toEqual([ + { + fn: 'auth_find_user_for_password_login', + result: 'TABLE(id uuid, name text, locale locale, password_hash text)', + runners: ['jantrik_login_app'], + }, + // The platform admins' own login (platform_admins.password_hash, not users'; P1-J6): only + // the platform module's login may run it. + { + fn: 'platform_find_admin_for_login', + result: + 'TABLE(id uuid, name text, password_hash text, is_active boolean, totp_secret text, totp_enrol_by timestamp with time zone)', + runners: ['jantrik_platform_app'], + }, ]); - expect(rows.filter((r) => /password_hash/i.test(r.result))).toEqual([]); + }); + + // The password login's own login: like the receiver's, it reaches the database only through its + // one function, never a table, and is a member of no role. + it('jantrik_login_app may run only the password lookup, and holds no other privilege', async () => { + const granted = await app.$queryRaw<{ name: string }[]>` + SELECT c.relname::text AS name + FROM pg_class c + WHERE c.relnamespace = 'public'::regnamespace AND c.relkind IN ('r', 'p', 'v', 'm', 'f', 'S') + AND CASE WHEN c.relkind = 'S' + THEN has_sequence_privilege('jantrik_login_app', c.oid, 'USAGE, SELECT, UPDATE') + ELSE has_table_privilege('jantrik_login_app', c.oid, + 'SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER') + OR has_any_column_privilege('jantrik_login_app', c.oid, + 'SELECT, INSERT, UPDATE, REFERENCES') + END + UNION ALL + SELECT p.proname::text + FROM pg_proc p + WHERE p.pronamespace = 'public'::regnamespace + AND p.proname <> 'auth_find_user_for_password_login' + AND has_function_privilege('jantrik_login_app', p.oid, 'EXECUTE') + AND NOT has_function_privilege('public', p.oid, 'EXECUTE')`; + expect(granted).toEqual([]); + const [role] = await app.$queryRaw< + { superuser: boolean; bypassrls: boolean; roles: string[]; owned: bigint }[] + >` + SELECT r.rolsuper AS superuser, r.rolbypassrls AS bypassrls, + ARRAY(SELECT m.roleid::regrole::text FROM pg_auth_members m + WHERE m.member = r.oid) AS roles, + (SELECT count(*) FROM pg_class c WHERE c.relowner = r.oid) AS owned + FROM pg_roles r WHERE r.rolname = 'jantrik_login_app'`; + expect(role).toEqual({ superuser: false, bypassrls: false, roles: [], owned: 0n }); }); // The login steps run before a platform session exists (the API has checked the password and diff --git a/packages/db/test/users-password-hash.test.ts b/packages/db/test/users-password-hash.test.ts index e731f26..eebc9ae 100644 --- a/packages/db/test/users-password-hash.test.ts +++ b/packages/db/test/users-password-hash.test.ts @@ -1,20 +1,16 @@ -import { createHash } from 'node:crypto'; import { hash } from '@node-rs/argon2'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { findOrCreateUser, withContext, withTenant, type PrismaClient } from '../src/index.js'; -import { appClient, createTenant, ownerClient, randomPhone } from './helpers.js'; +import { appClient, createTenant, loginClient, ownerClient, randomPhone } from './helpers.js'; -// P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's. The -// login gets the hash's parameters and salt, and the database compares (docs/database.md → users). - -const sha256 = (s: string): Buffer => createHash('sha256').update(s, 'utf8').digest(); -/** The PHC string up to its last `$`: algorithm, version, parameters and salt, no digest. */ -const paramsOf = (phc: string): string => phc.slice(0, phc.lastIndexOf('$')); -const NIL = '00000000-0000-0000-0000-000000000000'; +// P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's. Only the +// password login's own login (jantrik_login_app) may look one up, through one function +// (docs/database.md → users). describe('users.password_hash is out of the app login’s reach (P1-J)', () => { let app: PrismaClient; let owner: PrismaClient; + let login: PrismaClient; let tenantId: string; let staff: { id: string; phone: string; hash: string }; let coMember: { id: string; phone: string }; @@ -29,6 +25,7 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { beforeAll(async () => { app = appClient(); owner = ownerClient(); + login = loginClient(); tenantId = (await createTenant(app)).id; const make = (role: 'ADMIN' | 'TEACHER') => { const phone = randomPhone(); @@ -47,8 +44,7 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { }); afterAll(async () => { - await app.$disconnect(); - await owner.$disconnect(); + await Promise.all([app.$disconnect(), owner.$disconnect(), login.$disconnect()]); }); it('cannot select password_hash: not its own, not a co-member’s, not with SELECT *', async () => { @@ -91,59 +87,43 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { expect(rows.map((r) => r.id)).toEqual([staff.id]); }); - it('the login lookup returns the parameters and salt, never the digest', async () => { + it('the app’s login lookup returns who the person is, no password data', async () => { const rows = await app.$queryRaw[]>` SELECT * FROM auth_find_user_for_login(${staff.phone}, NULL)`; expect(rows).toHaveLength(1); - expect(Object.keys(rows[0]!).sort()).toEqual(['id', 'locale', 'name', 'password_params']); - expect(rows[0]!['password_params']).toBe(paramsOf(staff.hash)); - expect(staff.hash.startsWith(`${paramsOf(staff.hash)}$`)).toBe(true); + expect(Object.keys(rows[0]!).sort()).toEqual(['id', 'locale', 'name']); + expect(rows[0]!['id']).toBe(staff.id); }); - it('no parameters for a user without a password or with a hash in another format', async () => { - const paramsFor = async (phone: string) => - ( - await app.$queryRaw<{ password_params: string | null }[]>` - SELECT password_params FROM auth_find_user_for_login(${phone}, NULL)` - )[0]?.password_params; - expect(await paramsFor(noPassword.phone)).toBeNull(); + it('the app login may not run the password lookup', async () => { + await expect( + app.$queryRaw`SELECT * FROM auth_find_user_for_password_login(${staff.phone}, NULL)`, + ).rejects.toThrow(/permission denied/i); + }); - const odd = randomPhone(); - const oddId = await withTenant(app, tenantId, async (tx) => { - const id = await findOrCreateUser(tx, odd, 'Odd Hash'); - await tx.membership.create({ data: { tenantId, userId: id, role: 'STAFF' } }); - return id; - }); - const good = await hash('a long enough password'); - for (const stored of [ - 'not-a-real-hash', - good.replace('$argon2id$', '$argon2i$'), - good.replace('$v=19$', '$v=16$'), - `${paramsOf(good)}$AAAA`, // a digest that is not 32 bytes - `${good}$extra`, - ]) { - await setOwnHash(oddId, stored); - expect(await paramsFor(odd), stored).toBeNull(); - } + it('the login login gets the hash for a phone or an email, and nothing for anyone else', async () => { + const byPhone = await login.$queryRaw<{ id: string; password_hash: string | null }[]>` + SELECT id::text, password_hash FROM auth_find_user_for_password_login(${staff.phone}, NULL)`; + expect(byPhone).toEqual([{ id: staff.id, password_hash: staff.hash }]); + const none = await login.$queryRaw<{ password_hash: string | null }[]>` + SELECT password_hash FROM auth_find_user_for_password_login(${noPassword.phone}, NULL)`; + expect(none).toEqual([{ password_hash: null }]); + expect( + await login.$queryRaw` + SELECT * FROM auth_find_user_for_password_login(${randomPhone()}, NULL)`, + ).toEqual([]); }); - it('auth_my_password_matches compares inside the database, for the current user only', async () => { - const matches = (userId: string | null, digest: Buffer) => - withContext( - app, - userId ? { userId } : {}, - async (tx) => - ( - await tx.$queryRaw<{ ok: boolean }[]>` - SELECT auth_my_password_matches(${digest}) AS ok` - )[0]!.ok, - ); - expect(await matches(staff.id, sha256(staff.hash))).toBe(true); - expect(await matches(staff.id, sha256(`${staff.hash}x`))).toBe(false); - expect(await matches(coMember.id, sha256(staff.hash))).toBe(false); - expect(await matches(noPassword.id, sha256(staff.hash))).toBe(false); - expect(await matches(NIL, sha256(staff.hash))).toBe(false); - expect(await matches(null, sha256(staff.hash))).toBe(false); + it('the login login reads no table and runs no other function', async () => { + await expect(login.$queryRaw`SELECT id FROM users LIMIT 1`).rejects.toThrow( + /permission denied/i, + ); + await expect( + login.$queryRaw`SELECT * FROM auth_find_user_for_login(${staff.phone}, NULL)`, + ).rejects.toThrow(/permission denied/i); + await expect(login.$queryRaw`SELECT auth_my_password_is_set()`).rejects.toThrow( + /permission denied/i, + ); }); it('auth_my_password_is_set says whether the current user has a password', async () => { From 72b714b7b7a0d97db4e64f5f2b2a7b2bff96f806 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:06:07 +0600 Subject: [PATCH 24/44] The password login looks the hash up on its own database login (LoginPrismaService, a pool of 4, used by AuthService only: login-isolation.spec.ts) and verifies with argon2 as before. The start-up check refuses a privileged DATABASE_LOGIN_URL (fail closed) or one mixed up with DATABASE_URL; production refuses the owner or superuser there, and the receiver must not be given it. A stored hash above 64 MiB, 10 passes or 4 lanes, or one argon2 cannot read, counts as no password (the dummy check runs). Tests and Playwright derive DATABASE_LOGIN_URL like the platform login Co-Authored-By: Claude Opus 5.5 --- apps/api/src/auth/auth.module.ts | 2 + apps/api/src/auth/auth.service.ts | 18 +-- apps/api/src/auth/login-isolation.spec.ts | 47 ++++++++ apps/api/src/auth/login-lookup.ts | 40 +++---- .../api/src/auth/login-prisma.service.spec.ts | 109 ++++++++++++++++++ apps/api/src/auth/login-prisma.service.ts | 95 +++++++++++++++ apps/api/src/auth/password.service.spec.ts | 77 ++++--------- apps/api/src/auth/password.service.ts | 80 ++++--------- apps/api/src/config/dev-lan.spec.ts | 1 + apps/api/src/config/env.ts | 5 + apps/api/src/config/production-env.spec.ts | 11 +- apps/api/src/config/production-env.ts | 11 +- apps/api/test/devices-ingest-env.e2e-spec.ts | 1 + apps/api/vitest.config.ts | 10 ++ apps/web/playwright.config.ts | 10 ++ 15 files changed, 370 insertions(+), 147 deletions(-) create mode 100644 apps/api/src/auth/login-isolation.spec.ts create mode 100644 apps/api/src/auth/login-prisma.service.spec.ts create mode 100644 apps/api/src/auth/login-prisma.service.ts diff --git a/apps/api/src/auth/auth.module.ts b/apps/api/src/auth/auth.module.ts index 78e2c2e..8c4c0a2 100644 --- a/apps/api/src/auth/auth.module.ts +++ b/apps/api/src/auth/auth.module.ts @@ -4,6 +4,7 @@ import { JwtModule } from '@nestjs/jwt'; import type { Env } from '../config/env.js'; import { AuthController } from './auth.controller.js'; import { AuthService } from './auth.service.js'; +import { LoginPrismaService } from './login-prisma.service.js'; import { OtpService } from './otp.service.js'; import { PasswordController } from './password.controller.js'; import { PasswordSettingsService } from './password-settings.service.js'; @@ -23,6 +24,7 @@ import { TokenService } from './token.service.js'; controllers: [AuthController, PasswordController], providers: [ AuthService, + LoginPrismaService, OtpService, PasswordService, PasswordSettingsService, diff --git a/apps/api/src/auth/auth.service.ts b/apps/api/src/auth/auth.service.ts index d21e5c7..a883375 100644 --- a/apps/api/src/auth/auth.service.ts +++ b/apps/api/src/auth/auth.service.ts @@ -16,12 +16,12 @@ import { RateLimiter } from '../redis/rate-limiter.service.js'; import { Db } from '../tenancy/db.service.js'; import { TenantAccessService } from '../tenancy/tenant-access.service.js'; import { - findUserForLogin, + findUserForPasswordLogin, listMemberships, listMembershipsFor, - passwordMatches, type LoginUser, } from './login-lookup.js'; +import { LoginPrismaService } from './login-prisma.service.js'; import { OtpService } from './otp.service.js'; import { PasswordService } from './password.service.js'; import { newRefreshToken, SessionService, type SessionMeta } from './session.service.js'; @@ -35,6 +35,7 @@ type ResponseUser = AuthResponse['user']; export class AuthService { constructor( private readonly prisma: PrismaService, + private readonly login: LoginPrismaService, private readonly db: Db, private readonly otp: OtpService, private readonly passwords: PasswordService, @@ -80,13 +81,12 @@ export class AuthService { }, ); - const user = await findUserForLogin(this.prisma.client, { phone, email }); - // One argon2 hash and one comparison in the database whatever the account (a dummy hash and - // the nil user when needed), so timing doesn't reveal unknown accounts. The stored hash never - // leaves the database (P1-J). - const digest = await this.passwords.loginDigest(user?.password_params, password); - const ok = await passwordMatches(this.prisma.client, user?.id, digest); - if (!user || !ok) throw invalidCredentials(); + // On the password login's own database login (P1-J): no ordinary request can read a hash. + const found = await findUserForPasswordLogin(this.login.client, { phone, email }); + // Always verify (against a dummy hash if needed) so timing doesn't reveal unknown accounts. + const ok = await this.passwords.verify(found?.password_hash, password); + if (!found || !ok) throw invalidCredentials(); + const user: LoginUser = { id: found.id, name: found.name, locale: found.locale }; // Passwords are for staff (sprint 1 P1): an active staff membership in an open institute. // Anyone else gets the same answer as a wrong password, and it counts as a failed attempt. const memberships = await listMembershipsFor(this.prisma.client, user.id); diff --git a/apps/api/src/auth/login-isolation.spec.ts b/apps/api/src/auth/login-isolation.spec.ts new file mode 100644 index 0000000..9d1a1be --- /dev/null +++ b/apps/api/src/auth/login-isolation.spec.ts @@ -0,0 +1,47 @@ +import { readdirSync, readFileSync } from 'node:fs'; +import path from 'node:path'; + +// P1-J: the password login's own database login (LoginPrismaService, jantrik_login_app) is the +// only way to a password hash. It stays with the password login in code as well as in the +// database: only AuthService holds it, and only the login lookup names the function. +const SRC = path.resolve(import.meta.dirname, '..'); + +function sources(dir: string): string[] { + return readdirSync(dir, { withFileTypes: true }).flatMap((e) => { + const full = path.join(dir, e.name); + if (e.isDirectory()) return sources(full); + return e.name.endsWith('.ts') && !e.name.endsWith('.spec.ts') ? [full] : []; + }); +} + +const files = sources(SRC).map((full) => ({ + rel: path.relative(SRC, full).split(path.sep).join('/'), + code: readFileSync(full, 'utf8'), +})); + +const usesLoginClient = (code: string) => /login-prisma\.service/.test(code); +const namesLookup = (code: string) => /\bauth_find_user_for_password_login\b/.test(code); + +describe('the password login’s database login stays with the password login', () => { + it('only AuthService (and its module) use LoginPrismaService', () => { + expect(files.filter((f) => usesLoginClient(f.code)).map((f) => f.rel)).toEqual([ + 'auth/auth.module.ts', + 'auth/auth.service.ts', + ]); + }); + + it('only the login lookup and the start-up check name the password lookup', () => { + expect(files.filter((f) => namesLookup(f.code)).map((f) => f.rel)).toEqual([ + 'auth/login-lookup.ts', + 'auth/login-prisma.service.ts', + ]); + }); + + it('the scan finds what it looks for', () => { + expect(usesLoginClient("import { LoginPrismaService } from './login-prisma.service.js';")).toBe( + true, + ); + expect(namesLookup('SELECT * FROM auth_find_user_for_password_login($1, $2)')).toBe(true); + expect(namesLookup('SELECT * FROM auth_find_user_for_login($1, $2)')).toBe(false); + }); +}); diff --git a/apps/api/src/auth/login-lookup.ts b/apps/api/src/auth/login-lookup.ts index b7bc1cb..6b999f7 100644 --- a/apps/api/src/auth/login-lookup.ts +++ b/apps/api/src/auth/login-lookup.ts @@ -5,43 +5,35 @@ export interface LoginUser { id: string; name: string; locale: 'bn' | 'en'; - /** - * The stored password hash up to its last `$` (argon2id, version, cost, salt), never its digest - * (P1-J); null without a usable password. - */ - password_params: string | null; } -/** Login lookup through the SECURITY DEFINER function (users RLS hides everyone otherwise). */ +/** + * Login lookup through the SECURITY DEFINER function (users RLS hides everyone otherwise), on the + * app login. It returns who the person is, never password data (P1-J). + */ export async function findUserForLogin( prisma: PrismaClient, by: { phone?: string | null; email?: string | null }, ): Promise { const rows = await prisma.$queryRaw` - SELECT id::text, name, locale::text AS locale, password_params + SELECT id::text, name, locale::text AS locale FROM auth_find_user_for_login(${by.phone ?? null}, ${by.email ?? null})`; return rows[0]; } -/** Stands in for "no such user", so a failed lookup runs the same queries as a real account. */ -const NO_USER = '00000000-0000-0000-0000-000000000000'; - /** - * Whether `digest` (`PasswordService.loginDigest`) is the SHA-256 of the user's stored password - * hash. The database compares (`auth_my_password_matches`, scoped by `app.user_id`): the hash - * never reaches the API (P1-J). + * The password login's lookup, with the stored hash (null: no password). `login` must be the + * password login's own database login (LoginPrismaService, jantrik_login_app): it is the only + * one that may run this function, so no ordinary request can reach a hash (P1-J). */ -export async function passwordMatches( - prisma: PrismaClient, - userId: string | undefined, - digest: Buffer, -): Promise { - const rows = await withContext( - prisma, - { userId: userId ?? NO_USER }, - (tx) => tx.$queryRaw<{ ok: boolean }[]>`SELECT auth_my_password_matches(${digest}) AS ok`, - ); - return rows[0]?.ok === true; +export async function findUserForPasswordLogin( + login: PrismaClient, + by: { phone?: string | null; email?: string | null }, +): Promise<(LoginUser & { password_hash: string | null }) | undefined> { + const rows = await login.$queryRaw<(LoginUser & { password_hash: string | null })[]>` + SELECT id::text, name, locale::text AS locale, password_hash + FROM auth_find_user_for_password_login(${by.phone ?? null}, ${by.email ?? null})`; + return rows[0]; } interface MembershipRow { diff --git a/apps/api/src/auth/login-prisma.service.spec.ts b/apps/api/src/auth/login-prisma.service.spec.ts new file mode 100644 index 0000000..2979d41 --- /dev/null +++ b/apps/api/src/auth/login-prisma.service.spec.ts @@ -0,0 +1,109 @@ +import type { LoginPrivileges } from '@jantrik/db'; +import { LoginPrismaService } from './login-prisma.service.js'; + +// The password login's own database login (P1-J), checked at start-up like the platform one. + +const SAFE: LoginPrivileges = { + login: 'jantrik_login_app', + superuser: false, + bypassRls: false, + canBecome: [], +}; + +/** The privilege query's row (readLoginPrivileges reads pg_roles). */ +const privilegeRow = (p: LoginPrivileges) => ({ + login: p.login, + superuser: p.superuser, + bypass_rls: p.bypassRls, + can_become: p.canBecome, +}); + +/** + * A client whose privilege query answers `privileges` in turn (a row or a failure; the last one + * repeats) and whose role check (may it run the password lookup?) answers `ok` (or fails). + */ +const client = (ok: boolean | Error, privileges: (LoginPrivileges | Error)[] = [SAFE]) => { + let i = 0; + return { + $queryRaw: vi.fn((strings: TemplateStringsArray) => { + if (strings.join('').includes('pg_roles')) { + const p = privileges[Math.min(i++, privileges.length - 1)]!; + return p instanceof Error ? Promise.reject(p) : Promise.resolve([privilegeRow(p)]); + } + return ok instanceof Error ? Promise.reject(ok) : Promise.resolve([{ ok }]); + }), + }; +}; + +const unreachable = () => + Object.assign(new Error("Raw query failed. Message: Can't reach database server"), { + name: 'PrismaClientKnownRequestError', + code: 'P2010', + meta: { driverAdapterError: { cause: { kind: 'DatabaseNotReachable', port: 5432 } } }, + }); + +function service( + loginCanRun: boolean | Error, + mainCanRun: boolean | Error, + privileges: (LoginPrivileges | Error)[] = [SAFE], +) { + const warn = vi.fn(); + const s = Object.create(LoginPrismaService.prototype) as LoginPrismaService; + Object.assign(s, { + client: client(loginCanRun, privileges), + main: { client: client(mainCanRun) }, + logger: { warn, log: vi.fn() }, + retryDelaysMs: [0, 0, 0], + checkTimeoutMs: 50, + }); + return { s, warn }; +} + +describe('LoginPrismaService startup check', () => { + it('starts when only the login login may run the password lookup', async () => { + await expect(service(true, false).s.onModuleInit()).resolves.toBeUndefined(); + }); + + it.each([ + ['DATABASE_URL uses the login login', true, true], + ['DATABASE_LOGIN_URL uses the app login', false, false], + ['the two are swapped', false, true], + ])('refuses to start when %s', async (_case, login, main) => { + await expect(service(login, main).s.onModuleInit()).rejects.toThrow(/mixed up/); + }); + + it('only warns when the role check itself fails after the privilege check passed', async () => { + const { s, warn } = service(new Error('connect ECONNREFUSED'), false); + await expect(s.onModuleInit()).resolves.toBeUndefined(); + expect(warn).toHaveBeenCalledWith(expect.stringContaining('ECONNREFUSED')); + }); +}); + +describe('LoginPrismaService login privileges (fail closed)', () => { + it('refuses a superuser login at once, naming DATABASE_LOGIN_URL and the login', async () => { + const { s } = service(true, false, [{ ...SAFE, login: 'postgres', superuser: true }]); + await expect(s.onModuleInit()).rejects.toThrow(/DATABASE_LOGIN_URL.*postgres is a superuser/); + }); + + it('refuses a login with BYPASSRLS', async () => { + const { s } = service(true, false, [{ ...SAFE, bypassRls: true }]); + await expect(s.onModuleInit()).rejects.toThrow(/DATABASE_LOGIN_URL.*has BYPASSRLS/); + }); + + it('refuses a login that can become a superuser role', async () => { + const { s } = service(true, false, [{ ...SAFE, canBecome: ['postgres'] }]); + await expect(s.onModuleInit()).rejects.toThrow(/can become postgres/); + }); + + it('waits while the database is unreachable, then checks as usual', async () => { + const { s } = service(true, false, [unreachable(), unreachable(), SAFE]); + await expect(s.onModuleInit()).resolves.toBeUndefined(); + }); + + it('refuses to start unchecked when the database never answers', async () => { + const { s } = service(true, false, [unreachable()]); + await expect(s.onModuleInit()).rejects.toThrow( + /DATABASE_LOGIN_URL\).*DatabaseNotReachable\. The password login does not start unchecked/, + ); + }); +}); diff --git a/apps/api/src/auth/login-prisma.service.ts b/apps/api/src/auth/login-prisma.service.ts new file mode 100644 index 0000000..61b21fa --- /dev/null +++ b/apps/api/src/auth/login-prisma.service.ts @@ -0,0 +1,95 @@ +import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common'; +import { ConfigService } from '@nestjs/config'; +import { + createPrismaClient, + loginPrivilegeProblems, + readLoginPrivileges, + type PrismaClient, +} from '@jantrik/db'; +import { + STARTUP_CHECK_TIMEOUT_MS, + STARTUP_RETRY_DELAYS_MS, + runStartupCheck, + startupErrorLabel, +} from '../common/startup-check.js'; +import type { Env } from '../config/env.js'; +import { PrismaService } from '../prisma/prisma.service.js'; + +/** + * The password login's own database login (DATABASE_LOGIN_URL, role jantrik_login_app, P1-J). + * It may run one function, auth_find_user_for_password_login, and nothing else; the rest of the + * API (jantrik_app) may not run that function, so an SQL injection in an ordinary request never + * reaches a password hash. Used by AuthService.loginWithPassword only + * (login-isolation.spec.ts checks who imports it). A small pool: one lookup per login. + */ +@Injectable() +export class LoginPrismaService implements OnModuleInit, OnModuleDestroy { + private readonly logger = new Logger(LoginPrismaService.name); + readonly client: PrismaClient; + /** Waits between failed start-up checks (about 3 minutes in all; tests shorten them). */ + retryDelaysMs: readonly number[] = STARTUP_RETRY_DELAYS_MS; + /** How long one start-up check may take. */ + checkTimeoutMs = STARTUP_CHECK_TIMEOUT_MS; + + constructor( + config: ConfigService, + private readonly main: PrismaService, + ) { + this.client = createPrismaClient(config.get('DATABASE_LOGIN_URL', { infer: true }), { + max: 4, + }); + } + + /** + * First the login's privileges, failing closed like the API's own login (PrismaService): never + * a superuser, BYPASSRLS, or a login that can become such a role; while the check cannot run it + * is asked again for about 3 minutes, then the start is refused. + * + * Then refuse to start when the URLs are mixed up (DATABASE_URL given the login login, or the + * other way round): the separation would silently disappear. An error in this second check only + * warns (the first has just shown the database answers); logins fail on their own then. + */ + async onModuleInit(): Promise { + await runStartupCheck({ + run: () => readLoginPrivileges(this.client), + verdict: (p) => { + const problems = loginPrivilegeProblems(p); + return problems.length === 0 + ? true + : `DATABASE_LOGIN_URL must use the password login's login (jantrik_login_app): ` + + `${p.login} ${problems.join(', ')}. See docs/auth.md.`; + }, + retryDelaysMs: this.retryDelaysMs, + checkTimeoutMs: this.checkTimeoutMs, + logger: this.logger, + what: "the password login's database login (DATABASE_LOGIN_URL)", + unchecked: 'The password login does not start unchecked.', + label: startupErrorLabel, + }); + + const canRun = (client: PrismaClient) => + client.$queryRaw<{ ok: boolean }[]>` + SELECT has_function_privilege( + 'public.auth_find_user_for_password_login(text, text)', 'EXECUTE') AS ok`.then( + ([row]) => row?.ok === true, + ); + let login: boolean; + let main: boolean; + try { + [login, main] = await Promise.all([canRun(this.client), canRun(this.main.client)]); + } catch (error) { + this.logger.warn(`Could not check the database roles: ${(error as Error).message}`); + return; + } + if (!login || main) { + throw new Error( + 'Database roles are mixed up: DATABASE_LOGIN_URL must use the password login (jantrik_login_app) ' + + 'and DATABASE_URL the app login (jantrik_app). See docs/auth.md.', + ); + } + } + + async onModuleDestroy(): Promise { + await this.client.$disconnect(); + } +} diff --git a/apps/api/src/auth/password.service.spec.ts b/apps/api/src/auth/password.service.spec.ts index 83bffb2..726e591 100644 --- a/apps/api/src/auth/password.service.spec.ts +++ b/apps/api/src/auth/password.service.spec.ts @@ -1,19 +1,13 @@ -import { createHash } from 'node:crypto'; -import { hash } from '@node-rs/argon2'; +import { hash, verify } from '@node-rs/argon2'; import { PasswordService } from './password.service.js'; -// Wrapped so the tests can count the hashes a login computes; the real library does the work. +// Wrapped so the tests can see which hash each check verified against; the real library works. vi.mock('@node-rs/argon2', async (importOriginal) => { const real = await importOriginal(); - return { ...real, hash: vi.fn(real.hash) }; + return { ...real, verify: vi.fn(real.verify) }; }); -const sha256 = (s: string): Buffer => createHash('sha256').update(s, 'utf8').digest(); -/** What the login lookup returns: the PHC string up to its last `$` (no digest). */ -const paramsOf = (phc: string): string => phc.slice(0, phc.lastIndexOf('$')); -const NO_MATCH = Buffer.alloc(32); - -describe('PasswordService.loginDigest (P1-J: the database compares, the hash never leaves it)', () => { +describe('PasswordService.verify', () => { const service = new PasswordService(); const password = 'correct horse battery staple'; let stored: string; @@ -22,67 +16,42 @@ describe('PasswordService.loginDigest (P1-J: the database compares, the hash nev stored = await service.hash(password); }); - it('is the SHA-256 of the hash that the stored parameters and salt give the password', async () => { - expect(await service.loginDigest(paramsOf(stored), password)).toEqual(sha256(stored)); + beforeEach(() => { + vi.mocked(verify).mockClear(); }); - it('hashes the password NFC-normalised, as setting it did (P1-C)', async () => { + it('accepts the right password, NFC-normalised (P1-C), and refuses a wrong one', async () => { + expect(await service.verify(stored, password)).toBe(true); + expect(await service.verify(stored, `${password}!`)).toBe(false); const composed = 'পাসওয়ার্ড-café-2026'; - const decomposed = composed.normalize('NFD'); - expect(decomposed).not.toBe(composed); - const storedNfc = await service.hash(composed); - expect(await service.loginDigest(paramsOf(storedNfc), decomposed)).toEqual(sha256(storedNfc)); - }); - - it('gives another digest for a wrong password', async () => { - const digest = await service.loginDigest(paramsOf(stored), `${password}!`); - expect(digest).not.toEqual(sha256(stored)); - expect(digest).toHaveLength(32); + const nfc = await service.hash(composed); + expect(await service.verify(nfc, composed.normalize('NFD'))).toBe(true); }); it('follows stored parameters other than today’s, up to the ceiling', async () => { const costly = await hash(password, { memoryCost: 65_536, timeCost: 3, parallelism: 2 }); - expect(await service.loginDigest(paramsOf(costly), password)).toEqual(sha256(costly)); + expect(await service.verify(costly, password)).toBe(true); }); it.each([ ['no user', undefined], ['no password', null], - ['empty', ''], ['not a hash', 'not-a-real-hash'], - ['argon2i', 'ALGO'], - ['version 16', 'V16'], ['memory above 64 MiB', 'M_HIGH'], ['more than 10 passes', 'T_HIGH'], ['more than 4 lanes', 'P_HIGH'], - ['memory below 8 × lanes', 'M_LOW'], - ['a digest left on', 'WITH_DIGEST'], - ])('%s: hashes once with the defaults and matches nothing', async (_, kind) => { - const p = paramsOf(stored); - const params = + ])('%s: refused after one full argon2 check against the dummy hash (P1-J4)', async (_, kind) => { + const stored2 = { - ALGO: p.replace('$argon2id$', '$argon2i$'), - V16: p.replace('$v=19$', '$v=16$'), - M_HIGH: p.replace('m=19456', 'm=65537'), - T_HIGH: p.replace('t=2', 't=11'), - P_HIGH: p.replace('p=1', 'p=5'), - M_LOW: p.replace('m=19456,t=2,p=1', 'm=15,t=2,p=2'), - WITH_DIGEST: stored, + M_HIGH: stored.replace('m=19456', 'm=65537'), + T_HIGH: stored.replace('t=2', 't=11'), + P_HIGH: stored.replace('p=1', 'p=5'), }[kind as string] ?? kind; - vi.mocked(hash).mockClear(); - expect(await service.loginDigest(params, password)).toEqual(NO_MATCH); - // One hash at today's cost, as for a real account: the time does not tell the cases apart. - expect(vi.mocked(hash)).toHaveBeenCalledTimes(1); - expect(vi.mocked(hash).mock.calls[0]![1]).toMatchObject({ - memoryCost: 19_456, - timeCost: 2, - parallelism: 1, - }); - }); - - it('a real account also hashes exactly once', async () => { - vi.mocked(hash).mockClear(); - await service.loginDigest(paramsOf(stored), 'wrong but long password'); - expect(vi.mocked(hash)).toHaveBeenCalledTimes(1); + expect(await service.verify(stored2, password)).toBe(false); + // The time matches a real account's: one verification, at today's cost, never the stored one. + expect(vi.mocked(verify)).toHaveBeenCalledTimes(1); + const checked = vi.mocked(verify).mock.calls[0]![0] as string; + expect(checked).toMatch(/^\$argon2id\$v=19\$m=19456,t=2,p=1\$/); + expect(checked).not.toBe(stored2); }); }); diff --git a/apps/api/src/auth/password.service.ts b/apps/api/src/auth/password.service.ts index a4ff020..f425ad6 100644 --- a/apps/api/src/auth/password.service.ts +++ b/apps/api/src/auth/password.service.ts @@ -1,45 +1,29 @@ -import { createHash } from 'node:crypto'; import { Injectable } from '@nestjs/common'; import { normalizePassword } from '@jantrik/shared'; -import { hash, verify } from '@node-rs/argon2'; +import { hash, parseOptions, verify } from '@node-rs/argon2'; // Argon2id (the library default) with OWASP-recommended parameters: 19 MiB, 2 iterations. const OPTIONS = { memoryCost: 19_456, timeCost: 2, parallelism: 1 }; /** - * The most a stored hash may make one staff login spend (P1-J4): 64 MiB, 10 passes, 4 lanes. - * Hashes Jantrik writes use OPTIONS; above this a stored hash is treated as unusable. + * The most a stored hash may make one login spend (P1-J4): 64 MiB, 10 passes, 4 lanes. Hashes + * Jantrik writes use OPTIONS. Above this, or unreadable, a stored hash is treated as no password: + * a hash someone wrote into their own row cannot make each login attempt arbitrarily expensive. */ -const LOGIN_COST_CEILING = { memoryCost: 65_536, timeCost: 10, parallelism: 4 }; - -/** The login lookup's `password_params`: argon2id, version 19, m, t, p and the salt (no digest). */ -const PARAMS = /^\$argon2id\$v=19\$m=(\d{1,10}),t=(\d{1,10}),p=(\d{1,3})\$([A-Za-z0-9+/]{11,64})$/; - -/** The salt of the login's dummy hash (unknown user, no password, unusable parameters). */ -const DUMMY_SALT = Buffer.from('jantrik-dummy-salt-16b').subarray(0, 16); - -/** A digest no stored hash has: what the dummy path returns. */ -const NO_MATCH = Buffer.alloc(32); - -const sha256 = (value: string): Buffer => createHash('sha256').update(value, 'utf8').digest(); - -/** argon2 options from the login lookup's parameters, or null when they are missing or unusable. */ -function loginOptions(params: string | null | undefined) { - const m = params ? PARAMS.exec(params) : null; - if (!m) return null; - const [memoryCost, timeCost, parallelism] = [m[1], m[2], m[3]].map(Number) as [ - number, - number, - number, - ]; - const usable = - timeCost >= 1 && - parallelism >= 1 && - memoryCost >= 8 * parallelism && - memoryCost <= LOGIN_COST_CEILING.memoryCost && - timeCost <= LOGIN_COST_CEILING.timeCost && - parallelism <= LOGIN_COST_CEILING.parallelism; - return usable ? { memoryCost, timeCost, parallelism, salt: Buffer.from(m[4]!, 'base64') } : null; +const COST_CEILING = { memoryCost: 65_536, timeCost: 10, parallelism: 4 }; + +/** Whether argon2 may verify against `stored` (readable, and within the cost ceiling). */ +function usableHash(stored: string): boolean { + try { + const o = parseOptions(stored); + return ( + o.memoryCost <= COST_CEILING.memoryCost && + o.timeCost <= COST_CEILING.timeCost && + o.parallelism <= COST_CEILING.parallelism + ); + } catch { + return false; + } } /** @@ -56,36 +40,16 @@ export class PasswordService { } /** - * Verify a password against a stored hash (platform admins). With no stored hash it still runs - * a full argon2 verification against a dummy hash, so response time does not reveal whether the - * account exists. Staff logins use `loginDigest` instead: their hashes never leave the database. + * Verify a password. With no stored hash (unknown user, or OTP-only account), or one that is + * unreadable or above the cost ceiling, it still runs a full argon2 verification against a dummy + * hash, so response time does not reveal which case it was. */ async verify(storedHash: string | null | undefined, password: string): Promise { - if (!storedHash) { + if (!storedHash || !usableHash(storedHash)) { this.dummyHash ??= hash('jantrik-dummy-password', OPTIONS); await verify(await this.dummyHash, password).catch(() => false); return false; } return verify(storedHash, normalizePassword(password)).catch(() => false); } - - /** - * A staff login's half of the password check (P1-J): the argon2 hash of `password` under the - * stored hash's parameters and salt (the login lookup's `password_params`), as the SHA-256 the - * database compares with `auth_my_password_matches`. The stored hash never reaches the API. - * - * Always exactly one hash: with no parameters (unknown user, no password) or unusable ones, it - * hashes with today's cost and a dummy salt and returns a digest that matches nothing, so the - * time does not tell the cases apart. - */ - async loginDigest(params: string | null | undefined, password: string): Promise { - const options = loginOptions(params); - const candidate = await hash( - normalizePassword(password), - options ?? { ...OPTIONS, salt: DUMMY_SALT }, - ).catch(() => null); - // The salt must come back exactly as stored (it does for every hash this library wrote). - if (!options || !candidate?.startsWith(`${params}$`)) return NO_MATCH; - return sha256(candidate); - } } diff --git a/apps/api/src/config/dev-lan.spec.ts b/apps/api/src/config/dev-lan.spec.ts index 6d138c2..050f265 100644 --- a/apps/api/src/config/dev-lan.spec.ts +++ b/apps/api/src/config/dev-lan.spec.ts @@ -4,6 +4,7 @@ import { envSchema } from './env.js'; const base = { DATABASE_URL: 'postgresql://x@localhost/jantrik', DATABASE_PLATFORM_URL: 'postgresql://p@localhost/jantrik', + DATABASE_LOGIN_URL: 'postgresql://l@localhost/jantrik', DATABASE_INGEST_URL: 'postgresql://i@localhost/jantrik', JWT_ACCESS_SECRET: 'x'.repeat(40), OTP_PEPPER: 'y'.repeat(40), diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts index 7ee964a..73500c1 100644 --- a/apps/api/src/config/env.ts +++ b/apps/api/src/config/env.ts @@ -67,6 +67,11 @@ export const envSchema = z * platform_* functions. Same database as DATABASE_URL. */ DATABASE_PLATFORM_URL: z.string().min(1), + /** + * The password login's own login (role jantrik_login_app): the only role that may look up a + * password hash (the password lookup, P1-J; docs/auth.md). Same database as DATABASE_URL. + */ + DATABASE_LOGIN_URL: z.string().min(1), /** * The device receiver's own login (role jantrik_ingest_app): the only role that may run the * ingest_* functions. Same database as DATABASE_URL. Required when the receiver runs in this diff --git a/apps/api/src/config/production-env.spec.ts b/apps/api/src/config/production-env.spec.ts index 807884e..c8f9c47 100644 --- a/apps/api/src/config/production-env.spec.ts +++ b/apps/api/src/config/production-env.spec.ts @@ -17,6 +17,7 @@ const api = { NODE_ENV: 'production', DATABASE_URL: 'postgresql://jantrik_app:pw@db:5432/jantrik', DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:pw@db:5432/jantrik', + DATABASE_LOGIN_URL: 'postgresql://jantrik_login_app:pw@db:5432/jantrik', REDIS_URL: `redis://:${'f3'.repeat(24)}@redis:6379`, TRUST_PROXY: '1', CORS_ORIGINS: 'https://app.jantrik.com.bd,https://platform.jantrik.com.bd', @@ -156,6 +157,7 @@ describe('production env: the API and the worker', () => { const dev = { DATABASE_URL: 'postgresql://jantrik_app:x@localhost:5432/jantrik', DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:x@localhost:5432/jantrik', + DATABASE_LOGIN_URL: 'postgresql://jantrik_login_app:x@localhost:5432/jantrik', DATABASE_INGEST_URL: 'postgresql://jantrik_ingest_app:x@localhost:5432/jantrik', JWT_ACCESS_SECRET: 'x'.repeat(40), OTP_PEPPER: 'y'.repeat(40), @@ -209,7 +211,12 @@ describe('production env: the API and the worker', () => { }); it('refuses the schema owner, the superuser and a URL without a login for the runtime logins', () => { - for (const key of ['DATABASE_URL', 'DATABASE_PLATFORM_URL', 'DATABASE_INGEST_URL']) { + for (const key of [ + 'DATABASE_URL', + 'DATABASE_PLATFORM_URL', + 'DATABASE_LOGIN_URL', + 'DATABASE_INGEST_URL', + ]) { for (const user of ['jantrik_owner', 'postgres']) { expect(apiError({ ...api, [key]: `postgresql://${user}:pw@db:5432/jantrik` })).toContain( `${key} must not log in as ${user} in production`, @@ -343,6 +350,7 @@ describe('production env: development and tests are not affected', () => { NODE_ENV: 'test', DATABASE_URL: 'postgresql://jantrik_app:app_ci_password@localhost:5432/jantrik_e2e', DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:p@localhost:5432/jantrik_e2e', + DATABASE_LOGIN_URL: 'postgresql://jantrik_login_app:l@localhost:5432/jantrik_e2e', DATABASE_INGEST_URL: 'postgresql://jantrik_ingest_app:i@localhost:5432/jantrik_e2e', INGEST_IN_PROCESS: 'true', INGEST_TRUST_PROXY: 'true', @@ -362,6 +370,7 @@ describe('production env: development and tests are not affected', () => { const dev = { DATABASE_URL: 'postgresql://jantrik_app:app_dev_password@localhost:5432/jantrik', DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:p@localhost:5432/jantrik', + DATABASE_LOGIN_URL: 'postgresql://jantrik_login_app:l@localhost:5432/jantrik', DATABASE_INGEST_URL: 'postgresql://jantrik_ingest_app:i@localhost:5432/jantrik', ...Object.fromEntries( Object.entries(envFile('.env.example')).filter(([k]) => diff --git a/apps/api/src/config/production-env.ts b/apps/api/src/config/production-env.ts index 88f98fc..b966173 100644 --- a/apps/api/src/config/production-env.ts +++ b/apps/api/src/config/production-env.ts @@ -152,6 +152,7 @@ export const DATABASE_ADMIN_SECRETS = [ 'DB_APP_PASSWORD', 'DB_PLATFORM_PASSWORD', 'DB_INGEST_PASSWORD', + 'DB_LOGIN_PASSWORD', ] as const; /** @@ -188,6 +189,7 @@ export interface ApiProductionEnv { PLATFORM_TOTP_KEY?: string | undefined; DATABASE_URL: string; DATABASE_PLATFORM_URL: string; + DATABASE_LOGIN_URL: string; DATABASE_INGEST_URL?: string | undefined; } @@ -263,7 +265,12 @@ export function apiProductionProblems(env: ApiProductionEnv): EnvProblem[] { if (env[a] === env[b]) add(b, `${b} must differ from ${a}: one secret per purpose`); } } - for (const key of ['DATABASE_URL', 'DATABASE_PLATFORM_URL', 'DATABASE_INGEST_URL'] as const) { + for (const key of [ + 'DATABASE_URL', + 'DATABASE_PLATFORM_URL', + 'DATABASE_LOGIN_URL', + 'DATABASE_INGEST_URL', + ] as const) { const url = env[key]; if (url === undefined) continue; const problem = databaseUrlProblem(key, url); @@ -288,6 +295,7 @@ export interface ReceiverProductionEnv { export const API_ONLY_SECRETS = [ 'DATABASE_URL', 'DATABASE_PLATFORM_URL', + 'DATABASE_LOGIN_URL', 'DATABASE_MIGRATION_URL', 'JWT_ACCESS_SECRET', 'OTP_PEPPER', @@ -324,6 +332,7 @@ export function receiverProductionProblems(env: ReceiverProductionEnv): EnvProbl ...PRIVILEGED_DB_USERS, 'jantrik_app', 'jantrik_platform_app', + 'jantrik_login_app', ]); if (problem) problems.push(problem); if (redisUser(env.REDIS_URL) !== INGEST_REDIS_USER) { diff --git a/apps/api/test/devices-ingest-env.e2e-spec.ts b/apps/api/test/devices-ingest-env.e2e-spec.ts index 961b95b..b3cd1d1 100644 --- a/apps/api/test/devices-ingest-env.e2e-spec.ts +++ b/apps/api/test/devices-ingest-env.e2e-spec.ts @@ -99,6 +99,7 @@ describe('device receiver environment', () => { for (const key of [ 'DATABASE_URL', 'DATABASE_PLATFORM_URL', + 'DATABASE_LOGIN_URL', 'JWT_ACCESS_SECRET', 'OTP_PEPPER', ]) { diff --git a/apps/api/vitest.config.ts b/apps/api/vitest.config.ts index b43283a..401931c 100644 --- a/apps/api/vitest.config.ts +++ b/apps/api/vitest.config.ts @@ -23,6 +23,15 @@ const platformUrl = (): string => { return url.toString(); }; +/** The password login's login (DATABASE_LOGIN_URL) on the test database, derived like the platform one. */ +const loginUrl = (): string => { + const url = new URL(required('DATABASE_URL_TEST')); + const login = new URL(required('DATABASE_LOGIN_URL')); + url.username = login.username; + url.password = login.password; + return url.toString(); +}; + /** The device receiver's login (DATABASE_INGEST_URL) on the test database, derived like the platform one. */ const ingestUrl = (): string => { const url = new URL(required('DATABASE_URL_TEST')); @@ -46,6 +55,7 @@ export default defineConfig({ NODE_ENV: 'test', DATABASE_URL: required('DATABASE_URL_TEST'), DATABASE_PLATFORM_URL: platformUrl(), + DATABASE_LOGIN_URL: loginUrl(), DATABASE_INGEST_URL: ingestUrl(), DATABASE_MIGRATION_URL_TEST: required('DATABASE_MIGRATION_URL_TEST'), REDIS_URL: process.env['REDIS_URL_TEST'] ?? 'redis://localhost:6379/1', diff --git a/apps/web/playwright.config.ts b/apps/web/playwright.config.ts index 7f6b4dc..4bfaf37 100644 --- a/apps/web/playwright.config.ts +++ b/apps/web/playwright.config.ts @@ -35,6 +35,15 @@ const platformUrl = (): string => { return url.toString(); }; +/** The password login's login (DATABASE_LOGIN_URL) on the e2e database, derived like the platform one. */ +const loginUrl = (): string => { + const url = new URL(required('DATABASE_URL_E2E')); + const login = new URL(required('DATABASE_LOGIN_URL')); + url.username = login.username; + url.password = login.password; + return url.toString(); +}; + /** The device receiver's login (DATABASE_INGEST_URL) on the e2e database, derived like the platform one. */ const ingestUrl = (): string => { const url = new URL(required('DATABASE_URL_E2E')); @@ -77,6 +86,7 @@ export default defineConfig({ API_PORT: '4000', DATABASE_URL: required('DATABASE_URL_E2E'), DATABASE_PLATFORM_URL: platformUrl(), + DATABASE_LOGIN_URL: loginUrl(), DATABASE_INGEST_URL: ingestUrl(), INGEST_IN_PROCESS: 'true', INGEST_PORT: '4280', From 06f32362246abb6968d570cbb3f113aa9a623aa8 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:06:07 +0600 Subject: [PATCH 25/44] Docs after the P1-J review: what an injection in an ordinary request can and cannot do now (auth.md), the login role (database.md role table, start-up checks, local volume command; deploy.md roles, env checks and the upgrade for an existing server, including the gap between migrate and restart), the typed client's limits stated plainly, decisions-pending P1-J1 to P1-J7, and the plan's 'Changed after the review' Co-Authored-By: Claude Opus 5.5 --- docs/auth.md | 57 +++++++++++++++--------- docs/database.md | 46 ++++++++++++------- docs/decisions-pending.md | 14 +++--- docs/deploy.md | 49 +++++++++++++------- docs/devices.md | 3 +- docs/plans/sprint-1-p1j-password-hash.md | 40 +++++++++++++++-- 6 files changed, 143 insertions(+), 66 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index 01c05b8..852b9b1 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -30,8 +30,9 @@ Code lives in [`apps/api/src/auth`](../apps/api/src/auth) and the user lookup. An SMS is sent only if the phone belongs to a user. - Every failure of `otp/verify` and `login` (unknown user, wrong code or password, expired or burned code, OTP-only account) returns the same `401 Invalid credentials`. -- Password checks always run one argon2 hash and one database comparison, with a dummy salt - and the nil user if needed, so timing doesn't leak either. +- Password checks always run one argon2 verification, against a dummy hash if needed (no + account, no password, or a stored hash that is unreadable or above the cost ceiling), so timing + doesn't leak either. **OTP storage.** Codes are never stored in plain text. Redis holds `HMAC-SHA256(OTP_PEPPER, phone:code)` with a 5-minute TTL, plus an attempt counter. The 5th wrong @@ -222,26 +223,38 @@ Password login accepts up to 512 code points, as many as a settable password can decomposed. `PasswordSettingsService` is the only code that writes `users.password_hash` (`password-writes.spec.ts` checks it). -**The API never reads a staff password hash (P1-J).** `jantrik_app` may write -`users.password_hash` but not read it, so an SQL injection in a request cannot take hashes away -to crack offline ([database.md](database.md) → users). Checking a password at login: - -1. `auth_find_user_for_login(phone, email)` returns the stored hash up to its last `$` - (`password_params`: argon2id, version 19, `m`, `t`, `p`, the salt), never the digest; NULL for - no password or any other format; -2. `PasswordService.loginDigest` hashes the typed password (NFC) with those parameters and that - salt, and takes the SHA-256 of the result. Parameters above 64 MiB, 10 passes or 4 lanes are - treated as unusable (a hash written into someone's own row cannot make each attempt - arbitrarily expensive); -3. `auth_my_password_matches(digest)`, run with `app.user_id` set to that user, compares it with - the SHA-256 of the stored hash and answers yes or no. - -With no user, no password or unusable parameters, step 2 hashes once at today's cost with a dummy -salt and step 3 runs for the nil user, so every case costs the same. `GET /me/password` reads -`hasPassword` from `auth_my_password_is_set()`. What is left: an injection can still ask step 3 -about guesses it hashed itself, one query per guess and only while the hole is open, which is less -than reading the hash. The platform admins' login is separate and unchanged -([platform.md](platform.md)). +### The API never reads a hash in a request (P1-J) + +Ordinary requests run as `jantrik_app`, which may write `users.password_hash` (setting a password) +but cannot read it: not with a query (the column is not granted), and not through a function +(`auth_find_user_for_login` returns who the person is, never password data). The password login +alone has its own database login: + +- `POST /auth/login` with a password looks the person up through `LoginPrismaService` + (`DATABASE_LOGIN_URL`, role `jantrik_login_app`) and the function + `auth_find_user_for_password_login(phone, email)`, which returns the stored hash; the API + verifies with argon2 as before. +- `jantrik_login_app` may run that one function and nothing else (no table, no other function), + and `jantrik_app` may not run it. Only `AuthService` holds that client + (`login-isolation.spec.ts`). Its pool is small (4 connections). +- At start-up the API refuses a `DATABASE_LOGIN_URL` that is a superuser, has BYPASSRLS or can + become such a role (fail closed, like the other logins), and one mixed up with `DATABASE_URL`. +- A stored hash above 64 MiB, 10 passes or 4 lanes, or one argon2 cannot read, counts as no + password (the dummy check runs): a hash someone wrote into their own row cannot make each login + attempt arbitrarily expensive. + +**What an SQL injection in an ordinary request can and cannot do now:** + +- It **cannot** read any password hash or salt: its own, a co-member's or a stranger's. +- It **cannot** run the password lookup, or anything as `jantrik_login_app`: that login's + password is only in the API's environment. +- It **can** learn whether a given person has a password at all, yes or no: + `auth_my_password_is_set()` (for `GET /me/password`) answers for `app.user_id`, which any SQL can + set with `set_config`. It reveals nothing about the password itself. +- It can still set its own row's hash (the app login keeps UPDATE on the column, under RLS: its + own row only), as before. + +The platform admins' login is separate and unchanged ([platform.md](platform.md)). ## Tenants diff --git a/docs/database.md b/docs/database.md index 60a7287..5d0993d 100644 --- a/docs/database.md +++ b/docs/database.md @@ -35,11 +35,12 @@ the template. | `jantrik_platform_app` | The API's platform module (`DATABASE_PLATFORM_URL`) | LOGIN, NOSUPERUSER, NOBYPASSRLS, owns nothing. The **only** role with EXECUTE on the `platform_*` functions (`jantrik_app` has none), and that is all it has: not a member of `jantrik_app`, no table grants, so it never reads an institute's rows. | | `jantrik_ingest` | Owner of the `ingest_*` functions (the ZKTeco device receiver) | Same rules as `jantrik_auth`, with `TO jantrik_ingest` policies on the device tables and by column on tenants, modules and attendance settings. See "Devices (step 11)" below. | | `jantrik_ingest_app` | The device receiver (`DATABASE_INGEST_URL`) | LOGIN, NOSUPERUSER, NOBYPASSRLS, owns nothing. The **only** role with EXECUTE on the four `ingest_*` functions (`jantrik_app` has none), and that is all it has: a member of no role, no table, column or sequence grants. Its statements stop after 5 s (`statement_timeout`, decision #79): set on the role and sent by the receiver's pool. | +| `jantrik_login_app` | The password login (`DATABASE_LOGIN_URL`, P1-J) | LOGIN, NOSUPERUSER, NOBYPASSRLS, owns nothing. The **only** role with EXECUTE on `auth_find_user_for_password_login`, the one way to a password hash (`jantrik_app` has none), and that is all it has: a member of no role, no table, column or sequence grants. Used by `AuthService.loginWithPassword` only (`LoginPrismaService`). | **Every running service checks its login at start-up** (`readLoginPrivileges` in [`packages/db/src/login-privileges.ts`](../packages/db/src/login-privileges.ts)): the API and the -worker (`jantrik_app`), the platform module (`jantrik_platform_app`) and the receiver -(`jantrik_ingest_app`) refuse to start when their login is a superuser, has BYPASSRLS, or can +worker (`jantrik_app`), the platform module (`jantrik_platform_app`), the password login +(`jantrik_login_app`) and the receiver (`jantrik_ingest_app`) refuse to start when their login is a superuser, has BYPASSRLS, or can become (`pg_has_role(…, 'MEMBER')`) a role that is either, or `pg_read_all_data`, `pg_write_all_data` or one of the server file and program roles. The check fails closed: while the database does not answer, it is asked again for about 3 minutes, then the service exits. @@ -66,6 +67,7 @@ docker compose exec postgres psql -U postgres \ -c "GRANT jantrik_ingest TO jantrik_owner WITH INHERIT FALSE, SET TRUE" \ -c "CREATE ROLE jantrik_ingest_app LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE PASSWORD 'ingest_dev_password'" \ -c "ALTER ROLE jantrik_ingest_app SET statement_timeout = '5s'" \ + -c "CREATE ROLE jantrik_login_app LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE PASSWORD 'login_dev_password'" \ -c "CREATE DATABASE jantrik_e2e OWNER jantrik_owner" # A volume that already granted jantrik_app to jantrik_platform_app (early step 8): take it back. docker compose exec postgres psql -U postgres -c "REVOKE jantrik_app FROM jantrik_platform_app" @@ -169,14 +171,24 @@ references such as `sections.shift_id`. A row can only point at rows of its own ([auth.md](auth.md) → Setting a password). - **`password_hash` is not readable by the app (P1-J).** `jantrik_app` has SELECT on every other column, granted column by column (a table-level SELECT would cover the hash again), and - UPDATE on it (setting a password). **A new `users` column needs its own - `GRANT SELECT (column) ON users TO jantrik_app`**, or the app cannot read it; - `schema-safety.test.ts` pins the readable columns, checks that no login but the owner may read - the hash, and lists the app-runnable functions that touch it. Every Prisma client omits - `passwordHash` (`createPrismaClient`, `CLIENT_OMIT` in `packages/db/src/client.ts`), so - whole-row reads and updates never name the column; the package's `PrismaClient` type is that - client's, and the generated class is not exported. A test that needs the hash reads it through - the owner, in the user's context, with `select` or `omit: { passwordHash: false }`. + UPDATE on it (setting a password). Only the password login's own login (`jantrik_login_app`) + may look a hash up, through `auth_find_user_for_password_login`. + - **A new `users` column needs its own `GRANT SELECT (column) ON users TO jantrik_app`.** + Without it the app cannot read the column, and whole-row reads (the refresh, `/me`) fail; + `schema-safety.test.ts` fails first: it checks that `jantrik_app` may read every column but + the hash. + - `schema-safety.test.ts` also checks that no login but the owner may read the hash, pins by + name every definer function a runtime login may run whose owner can read it, and refuses + any function that returns the hash or a whole users row other than the password lookup. + - Every Prisma client omits `passwordHash` (`createPrismaClient`, `CLIENT_OMIT` in + `packages/db/src/client.ts`), so whole-row reads and updates never name the column. The + package's `PrismaClient` type is that client's, so a read without `select` has no + `passwordHash` and `new PrismaClient` from the package does not type-check. Two things are + **not** stopped by TypeScript, only by the database: an explicit + `select: { passwordHash: true }`, and the generated class, which the package's + `export *` still exports at runtime. + - A test that needs the hash reads it through the owner, in the user's context, with `select` + or `omit: { passwordHash: false }`. - **No INSERT or DELETE for the app.** Create people with `findOrCreateUser(tx, phone, name)`, which needs a tenant context. It returns only the id, so a person from another tenant stays hidden until they get a membership here. @@ -186,12 +198,14 @@ references such as `sections.shift_id`. A row can only point at rows of its own - Each is owned by `jantrik_auth`, pins `search_path = pg_catalog, public, pg_temp` (`pg_temp` last, so a temporary table cannot stand in for a real one), and is executable only by `jantrik_app`. - - `auth_find_user_for_login(phone, email)`: the user's id, name, locale and - `password_params` (the stored hash up to its last `$`: parameters and salt, never the - digest; P1-J) - - `auth_my_password_matches(digest)`: whether the SHA-256 of the current user's stored hash - (`app.user_id`) is `digest`; the login's comparison ([auth.md](auth.md) → Setting a password) - - `auth_my_password_is_set()`: whether the current user has a password (`GET /me/password`) + - `auth_find_user_for_login(phone, email)`: the user's id, name and locale, no password data + (P1-J) + - `auth_find_user_for_password_login(phone, email)`: the same plus `password_hash`. **The one + exception to "executable only by `jantrik_app`":** only `jantrik_login_app` may run it, and + `jantrik_app` may not (P1-J, [auth.md](auth.md) → The API never reads a hash in a request) + - `auth_my_password_is_set()`: whether the current user (`app.user_id`) has a password + (`GET /me/password`). A request can set `app.user_id` to any id, so this tells an injection + whether a given person has a password: yes or no, nothing more - `auth_list_my_memberships()`: uses `app.user_id`, with no user parameter. It also returns `invited_at`, so the login flow can show pending invitations. - `auth_resolve_tenant(slug)` diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index c054efa..2499b09 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -653,18 +653,20 @@ P1-I. **Open, for the owner: catch part of an institute's name too?** The rule r - To change: `passwordProblems` in `packages/shared/src/password.ts` (the server and the form share it). -P1-J. **Built (day run 2026-11-16), for the owner's review with its PR: the app login can no longer read password hashes.** Plan: [plans/sprint-1-p1j-password-hash.md](plans/sprint-1-p1j-password-hash.md), written and built while the owner was away, as asked. `jantrik_app` lost SELECT on `users.password_hash` (granted column by column; UPDATE kept), the login lookup returns only the hash's parameters and salt and the database compares, `hasPassword` comes from `auth_my_password_is_set()`, and every Prisma client omits the hash. Decisions taken alone, each the safest option (P1-J1 to P1-J6): +P1-J. **Built (day run 2026-11-16), for the owner's review with its PR: no ordinary request can read a password hash.** Plan: [plans/sprint-1-p1j-password-hash.md](plans/sprint-1-p1j-password-hash.md), written and built while the owner was away, as asked, then changed after the database-security review (P1-J7). `jantrik_app` lost SELECT on `users.password_hash` (granted column by column; UPDATE kept), its login lookup returns no password data, and the password login looks the hash up on its own database login (`jantrik_login_app`, `DATABASE_LOGIN_URL`) through one function only that login may run. Every Prisma client omits the hash. **Setup on your machine:** create the role once (docs/database.md → Database roles, the `CREATE ROLE jantrik_login_app …` line) and add `DATABASE_LOGIN_URL` to `.env` (from `.env.example`). Decisions taken alone, each the safest option (P1-J1 to P1-J7): -P1-J1. **The login lookup returned any user's hash, so it changed too.** `auth_find_user_for_login`, which `jantrik_app` may run, returned `password_hash` for any phone or email, whatever the institute: hiding the column alone would have closed nothing. It now returns `password_params` (the hash up to its last `$`); the API hashes the typed password with them and `auth_my_password_matches(digest)` compares inside the database. What is left: an injection could ask that function about guesses it hashed itself (the cost of an offline attack, but one query per guess and only while the hole is open), which is less than reading the hash. Not rate-limited inside the database. +P1-J1. **The app's login lookup returned any user's hash, so it changed too.** `auth_find_user_for_login`, which `jantrik_app` may run, returned `password_hash` for any phone or email, whatever the institute: hiding the column alone would have closed nothing. It now returns id, name and locale only (the OTP login never needed more). -P1-J2. **`hasPassword` comes from a definer function for the current user only** (`auth_my_password_is_set()`, no parameter, scoped by `app.user_id`), like `auth_list_my_memberships()`. The two new functions take no id, so the schema-safety rules (no uuid parameter, scoped by context) needed no new exception. +P1-J2. **`hasPassword` comes from `auth_my_password_is_set()`**, a definer function for `app.user_id` with no parameter. **It leaks one bit:** any SQL in a request can set `app.user_id` with `set_config`, so an injection can learn whether a given person has a password (yes or no; nothing about the password). Moving it to the login's own login would close that too; not done, to keep that login used by the password login only. -P1-J3. **Every Prisma client omits `passwordHash`** (a global `omit` in `createPrismaClient`), instead of a `select` at each call site. The package's `PrismaClient` type is now that client's type and the generated class is no longer exported, so TypeScript refuses code that reads the hash and every client comes from the factory (the test helper's one-connection client too, with a new `max` pool option). The seed's and the harness's whole-row updates of users keep working unchanged. +P1-J3. **Every Prisma client omits `passwordHash`** (a global `omit` in `createPrismaClient`), instead of a `select` at each call site. The package's `PrismaClient` type is that client's, so a read without `select` has no `passwordHash` and `new PrismaClient` from the package does not type-check (the test helper's one-connection client now comes from the factory, with a new `max` pool option). Not stopped by TypeScript, only by the database: an explicit `select: { passwordHash: true }`, and the generated class, which the package's `export *` still exports at runtime. -P1-J4. **A cost ceiling for stored hashes at login:** at most 64 MiB, 10 passes, 4 lanes (today's hashes: 19 MiB, 2, 1). Above it the stored hash is treated as unusable. Before, argon2 verified whatever parameters a stored hash named, so someone who wrote a huge-cost hash into their own row could make each of their login attempts arbitrarily expensive. +P1-J4. **A cost ceiling for stored hashes at login:** at most 64 MiB, 10 passes, 4 lanes (today's hashes: 19 MiB, 2, 1). Above it, or unreadable, the stored hash counts as no password (the dummy check runs, so the time is the same). Before, argon2 verified whatever parameters a stored hash named, so someone who wrote a huge-cost hash into their own row could make each of their login attempts arbitrarily expensive. -P1-J5. **Only argon2id version 19 with a 32-byte digest** (what `@node-rs/argon2` writes) can sign in. Any other stored value gives no parameters, as a corrupt hash fails today; the person sets a new password after a phone code. Every hash Jantrik has written has this format; nothing to migrate. +P1-J5. **(Dropped after the review.)** The first version accepted only argon2id v19 with a 32-byte digest, because the API recomputed the hash. With argon2's own verify back (P1-J7) any argon2 hash within the ceiling works again. P1-J6. **Not changed: the platform admins' login** (`platform_find_admin_for_login` returns `platform_admins` hashes and TOTP secrets to `jantrik_platform_app`). It is a separate login with no tenant traffic; the same change can follow if you want it. +P1-J7. **Built after the review; you may drop these commits:** the first version kept the hash in the database and compared a digest there (`auth_my_password_matches`). The review showed that an injection could read any user's salt, set `app.user_id` to them and check 200,000 offline-computed guesses in one 6.4-second statement: close to reading the hash. Now a dedicated login, `jantrik_login_app`, is the only one that may run the hash lookup (`auth_find_user_for_password_login`); `jantrik_app` has neither the lookup nor any comparison function, and the API verifies with argon2 as before. It follows the platform and receiver logins: its own env URL (required, refused in production as the owner or superuser, never given to the receiver), its own small pool, the fail-closed privilege check and a mixed-up-URLs check at start-up, and the role in `01-roles.sh`, `create-roles.sh`, the production compose, CI, the restore check and the docs. **Upgrade gap:** between `migrate` and the restart, the old API fails whole-row reads of `users` (the refresh, `/auth/me`) and both logins; a failed refresh is retried and nobody is signed out (docs/deploy.md → Upgrades). + P1-K. **Fixed from the review** (each with a test that failed first): a code is single use even when two requests race with it (login codes too); the phone rule ignores every punctuation mark and symbol between the digits; the other sessions are revoked in one statement; the common-password list is read at start-up; password login accepts up to 512 code points (a 128-character password typed decomposed); the wrong-code message asks to check the code before sending a new one. Kept as they are: the staff check after a correct password costs one extra query (it only confirms a password the caller already has); the login page's hint sits under the password tab, which guardians do not use. diff --git a/docs/deploy.md b/docs/deploy.md index e4744f3..8b22143 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -24,8 +24,8 @@ the repo's [`Dockerfile`](../Dockerfile): Start order (Docker enforces it): `postgres` and `redis` healthy → `migrate` finished without an error → `api`, `worker`, `receiver`. Only `migrate` gets the owner role's password; the API and -the worker log in as `jantrik_app` and `jantrik_platform_app`, the receiver as -`jantrik_ingest_app` and gets none of the API's secrets. +the worker log in as `jantrik_app`, `jantrik_platform_app` and `jantrik_login_app` (the password +login only), the receiver as `jantrik_ingest_app` and gets none of the API's secrets. ## 1. A server @@ -100,7 +100,7 @@ Fill in every value of `deploy/.env.prod` (git-ignored, never commit it): - **Domains:** `APP_DOMAIN`, `API_DOMAIN`, `PLATFORM_DOMAIN`, `DEVICE_HOST` (a domain or the server's fixed IP), `ACME_EMAIL` (Let's Encrypt's expiry warnings). -- **Passwords** (Postgres superuser, the four roles, Redis's two users: `REDIS_PASSWORD` for the +- **Passwords** (Postgres superuser, the five roles, Redis's two users: `REDIS_PASSWORD` for the API and the worker, `REDIS_INGEST_PASSWORD` for the device receiver's own user): `openssl rand -hex 24` each, all different. Letters and digits only, because they go into connection URLs as they are. Postgres takes the @@ -153,7 +153,7 @@ The API and the worker refuse: | a secret under 32 characters | too short to resist guessing | | a secret with an example marker (`change-me`, `CHANGE_ME`, `dev-only`, `test-only`, `ci-only`, `dev_password`, `ci_password`, `placeholder`, `example`; the same list as `compose.sh` and `create-roles.sh`) | copied from `.env.example`, `deploy/.env.prod.example`, CI or a test config, not generated | | two of `JWT_ACCESS_SECRET`, `OTP_PEPPER`, `PLATFORM_TOTP_KEY` equal | one leak would open two doors | -| `DATABASE_URL`, `DATABASE_PLATFORM_URL` or `DATABASE_INGEST_URL` logging in as `jantrik_owner` or `postgres`, or naming no login | the owner and the superuser are not subject to the database's protections the app relies on | +| `DATABASE_URL`, `DATABASE_PLATFORM_URL`, `DATABASE_LOGIN_URL` or `DATABASE_INGEST_URL` logging in as `jantrik_owner` or `postgres`, or naming no login | the owner and the superuser are not subject to the database's protections the app relies on | | a password in `REDIS_URL` under 24 characters or with an example marker | the published example would open Redis (its queues and sessions) to anything on the network. A URL without a password is allowed (Redis on a private network) | | `DATABASE_MIGRATION_URL`, `POSTGRES_PASSWORD` or any `DB_*_PASSWORD` in its environment | the owner's and the superuser's credentials and the roles' raw passwords belong to Postgres and the migrate step only | | `PLATFORM_TOTP_KEY` missing | the platform admins' 2FA secrets need their own key | @@ -161,23 +161,24 @@ The API and the worker refuse: The device receiver refuses: -| Setting | Why | -| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| any of `DATABASE_URL`, `DATABASE_PLATFORM_URL`, `DATABASE_MIGRATION_URL`, `JWT_ACCESS_SECRET`, `OTP_PEPPER`, `PLATFORM_TOTP_KEY` in its environment | it is open to the internet without a login: code run in it must find no login that can choose an institute and no key that signs sessions | -| `INGEST_TRUST_PROXY` `true` or a `/0` range | a client could claim a school's trusted address and receive its commands | -| `DATABASE_INGEST_URL` as `jantrik_owner`, `postgres`, `jantrik_app` or `jantrik_platform_app` | its own login only | -| `REDIS_URL` not set, or with an example or short password | as for the API | -| `REDIS_URL` not logging in as `jantrik_ingest` | Redis's default user could queue jobs the worker trusts; `jantrik_ingest` reaches only the receiver's keys and queue (§ 10a) | -| `DATABASE_MIGRATION_URL`, `POSTGRES_PASSWORD` or any `DB_*_PASSWORD` in its environment | as for the API | +| Setting | Why | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| any of `DATABASE_URL`, `DATABASE_PLATFORM_URL`, `DATABASE_LOGIN_URL`, `DATABASE_MIGRATION_URL`, `JWT_ACCESS_SECRET`, `OTP_PEPPER`, `PLATFORM_TOTP_KEY` in its environment | it is open to the internet without a login: code run in it must find no login that can choose an institute and no key that signs sessions | +| `INGEST_TRUST_PROXY` `true` or a `/0` range | a client could claim a school's trusted address and receive its commands | +| `DATABASE_INGEST_URL` as `jantrik_owner`, `postgres`, `jantrik_app`, `jantrik_platform_app` or `jantrik_login_app` | its own login only | +| `REDIS_URL` not set, or with an example or short password | as for the API | +| `REDIS_URL` not logging in as `jantrik_ingest` | Redis's default user could queue jobs the worker trusts; `jantrik_ingest` reaches only the receiver's keys and queue (§ 10a) | +| `DATABASE_MIGRATION_URL`, `POSTGRES_PASSWORD` or any `DB_*_PASSWORD` in its environment | as for the API | Beyond these, every service checks its database login at start-up, against the database itself: - **No login may be a superuser, have BYPASSRLS, or be able to become such a role** (nor `pg_read_all_data`, `pg_write_all_data` or the server file and program roles): the API and the - worker (`DATABASE_URL`), the platform module (`DATABASE_PLATFORM_URL`) and the receiver - (`DATABASE_INGEST_URL`). Fail closed: while the database does not answer, the check is asked + worker (`DATABASE_URL`), the platform module (`DATABASE_PLATFORM_URL`), the password login + (`DATABASE_LOGIN_URL`) and the receiver (`DATABASE_INGEST_URL`). Fail closed: while the database does not answer, the check is asked again for about 3 minutes, then the service exits ([database.md](database.md) → Database roles). - The platform login can run the platform functions and the main login cannot. +- The password login's login can run the password lookup and the main login cannot (P1-J). - The receiver's login cannot read a table, and its statements stop after 5 s (`statement_timeout`, [devices.md](devices.md)). @@ -203,7 +204,8 @@ the script on its first start (an empty volume) with the passwords from the sett - creates `jantrik_owner` (owns the schema, runs migrations; not a superuser, so forced row-level security applies to it), `jantrik_app` (the API), `jantrik_platform_app` (the API's platform - module), `jantrik_ingest_app` (the receiver), and the function owners `jantrik_auth`, + module), `jantrik_ingest_app` (the receiver), `jantrik_login_app` (the password login only: + the one role that may look up a password hash), and the function owners `jantrik_auth`, `jantrik_search`, `jantrik_platform`, `jantrik_ingest` (no login; the owner may `SET ROLE` to them but never inherits them), exactly as `docker/postgres/init/01-roles.sh` does for development ([database.md](database.md) → Database roles); @@ -242,7 +244,7 @@ land in the shell history and the process list), then restart the services: ```bash deploy/compose.sh exec -u postgres postgres psql -# \password jantrik_app (or jantrik_platform_app, jantrik_ingest_app, jantrik_owner, postgres) +# \password jantrik_app (or jantrik_platform_app, jantrik_login_app, jantrik_ingest_app, jantrik_owner, postgres) ``` **Check it:** @@ -352,6 +354,18 @@ deploy/compose.sh ps `ALTER ROLE jantrik_ingest_app SET statement_timeout = '5s';` 3. upgrade as above (`up -d` restarts Redis with the new user), then run the Redis check (§ 10a). +- **A server set up before sprint 1's P1-J** (the password login's own database login): + 1. add `DB_LOGIN_PASSWORD` (`openssl rand -hex 24`, different from every other password) to + the settings file (`DATABASE_LOGIN_URL` needs nothing: the compose file builds it); + 2. create the role **before** the migration (the migration grants to it): recreate the + Postgres container so it gets the new password (`deploy/compose.sh up -d postgres`; the data + stays), then run the roles script again, which creates only what is missing + (`deploy/compose.sh exec -u postgres postgres sh /jantrik/postgres/create-roles.sh`); + 3. upgrade as above. **Between `migrate` and `up -d`**, the old API still running fails: every + whole-row read of `users` (the session refresh, `/auth/me`) and both logins (its login + lookup asks for a column the function no longer returns), until it restarts. Nothing is + lost: a refresh that fails is retried by the browser, and nobody is signed out. Keep the + gap short (run the two commands together). ## 12. Backups @@ -491,7 +505,8 @@ To use a provider's Postgres 16 instead of the `postgres` service: ```bash install -m 600 /dev/null roles.env nano roles.env # PGHOST=..., PGPORT=5432, PGUSER=, PGPASSWORD=..., PGSSLMODE=require, - # DB_OWNER_PASSWORD=..., DB_APP_PASSWORD=..., DB_PLATFORM_PASSWORD=..., DB_INGEST_PASSWORD=... + # DB_OWNER_PASSWORD=..., DB_APP_PASSWORD=..., DB_PLATFORM_PASSWORD=..., DB_INGEST_PASSWORD=..., + # DB_LOGIN_PASSWORD=... (set -a && . ./roles.env && sh deploy/postgres/create-roles.sh) shred -u roles.env ``` diff --git a/docs/devices.md b/docs/devices.md index 1381efe..f1c2f98 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -152,7 +152,8 @@ screen. Devices that support HTTPS can use a TLS proxy in front of the receiver' ([`ingest-env.ts`](../apps/api/src/config/ingest-env.ts)): `NODE_ENV`, `DATABASE_INGEST_URL` (required), `REDIS_URL`, `QUEUE_PREFIX`, `INGEST_PORT`, `INGEST_TRUST_PROXY` and the limits. In production give it only these: never the API's logins or secrets (`DATABASE_URL`, - `DATABASE_PLATFORM_URL`, `JWT_ACCESS_SECRET`, `OTP_PEPPER`, `PLATFORM_TOTP_KEY`), so code run + `DATABASE_PLATFORM_URL`, `DATABASE_LOGIN_URL`, `JWT_ACCESS_SECRET`, `OTP_PEPPER`, + `PLATFORM_TOTP_KEY`), so code run in the receiver finds no login that can choose an institute and no key that signs sessions ([decisions-pending.md](decisions-pending.md) → Deployment requirements). The setup guide's `INGEST_PUBLIC_HOST` and `INGEST_PUBLIC_PORT` belong to the API, which refuses to start in diff --git a/docs/plans/sprint-1-p1j-password-hash.md b/docs/plans/sprint-1-p1j-password-hash.md index d8b3efb..a719a41 100644 --- a/docs/plans/sprint-1-p1j-password-hash.md +++ b/docs/plans/sprint-1-p1j-password-hash.md @@ -9,6 +9,38 @@ follow-up is P1-J in [decisions-pending.md](../decisions-pending.md); the phase > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans (one implementer, > one database-security review subagent at the end). Steps use checkbox (`- [ ]`) syntax. +## Changed after the review (P1-J7; the owner may drop these commits) + +The database-security review found that the first design below left an oracle as good as the +hash: as `jantrik_app`, an injection could read any user's salt from `auth_find_user_for_login`, +set `app.user_id` to them, and check 200,000 offline-computed guesses against +`auth_my_password_matches` in one statement (6.4 s on the scratch database). What was built +instead, and what this plan's sections below describe only where they say so: + +- **A dedicated login, `jantrik_login_app`** (`DATABASE_LOGIN_URL`), like the platform and + receiver logins: LOGIN, no table grants, a member of no role, not a member of `jantrik_app`. It + may run one function, `auth_find_user_for_password_login(phone, email)`, which returns the + stored hash; `jantrik_app` may not run it. `LoginPrismaService` (a small pool, used by + `AuthService.loginWithPassword` only) checks at start-up that the login is not privileged (fail + closed) and not mixed up with `DATABASE_URL`. +- **The API verifies with argon2 as before** (`PasswordService.verify`, dummy hash for unknown + users). The digest exchange (`loginDigest`, `auth_my_password_matches`) is gone, and with it the + format restriction (P1-J5). The cost ceiling (P1-J4) stays, now in `verify`. +- **`auth_find_user_for_login`** (the app's) returns id, name and locale only. +- **What an injection in an ordinary request can and cannot do now:** it cannot read any hash or + salt, its own or anyone's, and cannot run the password lookup. It can learn whether a given + person has a password (yes or no) through `auth_my_password_is_set()` with a `set_config` of + `app.user_id` (P1-J2). +- **Guards:** `schema-safety.test.ts` checks that `jantrik_app` may read every `users` column but + the hash (a new column without its GRANT fails), pins by name every definer function a runtime + login may run whose owner can read the hash, refuses any function that returns the hash or a + whole users row except the password lookup, and holds `jantrik_login_app` to that one function. +- **Setup:** the role in `01-roles.sh`, `create-roles.sh`, the production compose and its + settings example, the restore check, CI and `.env.example`. On an existing machine: create the + role once (database.md → Database roles) and add `DATABASE_LOGIN_URL` to `.env`. On an existing + server: deploy.md → Upgrades (create the role before the migration; the old API fails some reads + between migrate and restart). + **Goal:** an SQL injection in any institute request (which runs as `jantrik_app`) can no longer read a staff member's argon2 password hash, neither of co-members nor of anyone else. Everything the app needs keeps working: password login, `GET /me/password` (`hasPassword`), setting a @@ -153,10 +185,10 @@ Each function: `REVOKE ALL … FROM PUBLIC`, `GRANT EXECUTE … TO jantrik_app`, in an error message. 2. **No timing difference** between an unknown phone, a user without a password and a wrong password (one argon2 hash and one transaction each). -3. **The oracle that remains:** `auth_my_password_matches` answers yes/no for a digest. An - injection could ask it for guesses after computing argon2 for each one itself (the cost of an - offline attack, but online, one query per guess, and only while the hole is open). That is - strictly less than reading the hash (P1-J1). +3. **(Wrong in the first version, see "Changed after the review".)** The first version said the + remaining oracle allowed one query per guess. In fact the salt was readable and one statement + could test 200,000 guesses, close to reading the hash. The oracle is gone; what is left is one + bit per person ("has a password", P1-J2). 4. **Nothing else broke:** the seed (demo passwords and Bangla names), the API harness, every `users` read. From 82f66008359884648afa5c4f3152ed4fbb0f01a9 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:42:57 +0600 Subject: [PATCH 26/44] Test phones never wrap and their lock survives races (review of PR #17): the clock floor rises 1 number a second instead of 20 (the range lasts until about May 2028 instead of 29 November 2026), and when the 49 million numbers are used up drawing stops with a message to recreate the test database, instead of wrapping onto numbers older runs gave out (P0-8 would have come back for runs about 28 days apart). The lock takes over a stale lock only by moving it aside and checking its owner token, so it never removes a fresh lock another process made meanwhile, releases only its own lock, and treats Windows' EPERM/EACCES (a lock being removed) as busy. Tests: no wrap, the floor's rate, EPERM/EACCES, the takeover race (a fake file system), and four processes drawing at once past a stale lock Co-Authored-By: Claude Opus 5.5 --- apps/api/test/support/test-phones.ts | 79 +++++++++++++---- packages/db/test/test-phones.test.ts | 123 +++++++++++++++++++++++++-- packages/db/test/test-phones.ts | 79 +++++++++++++---- 3 files changed, 240 insertions(+), 41 deletions(-) diff --git a/apps/api/test/support/test-phones.ts b/apps/api/test/support/test-phones.ts index f03c431..d200eed 100644 --- a/apps/api/test/support/test-phones.ts +++ b/apps/api/test/support/test-phones.ts @@ -1,3 +1,4 @@ +import { randomUUID } from 'node:crypto'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; @@ -13,7 +14,8 @@ import path from 'node:path'; * one by one. The counter never goes back behind the clock (`floorAt`), so a lost counter file * does not restart at numbers earlier runs gave out. The numbers sit where nothing else is: * `` + 50 000 000–98 999 999 (the seeds' fixed numbers are below; the old random phones - * used other operators). + * used other operators). They never wrap: when the range is used up (the clock alone reaches its + * end in about May 2028), drawing stops with a message instead of repeating old numbers. * * Kept identical in packages/db/test/test-phones.ts and apps/api/test/support/test-phones.ts (a * test of the db copy pins how it behaves). @@ -23,9 +25,13 @@ import path from 'node:path'; const BLOCK = 200; const LOW = 50_000_000; const SPAN = 49_000_000; -/** The counter's floor grows 20 a second from this day, so it is always ahead of older runs. */ +/** The counter's floor grows 1 a second from this day, so it is always ahead of older runs. */ const EPOCH_MS = Date.UTC(2026, 10, 1); -const PER_SECOND = 20; +const PER_SECOND = 1; +/** A lock older than this was left by a process that died (the locked work takes microseconds). */ +const STALE_MS = 10_000; +/** What `mkdir` answers while the lock exists, or (Windows) while it is being removed. */ +const BUSY = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY', 'ENOTEMPTY']); export const floorAt = (nowMs: number): number => Math.max(0, Math.floor(((nowMs - EPOCH_MS) / 1000) * PER_SECOND)); @@ -34,22 +40,55 @@ const pause = (ms: number): void => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }; -/** Runs `fn` while holding a lock directory; a lock older than 10 s is left over and taken. */ -function withLock(lockDir: string, fn: () => T): T { +const ownerOf = (f: typeof fs, lockDir: string): string | null => { + try { + return f.readFileSync(path.join(lockDir, 'owner'), 'utf8'); + } catch { + return null; + } +}; + +/** + * Removes the lock if it is stale. It is first moved aside (a rename: only one process can), and + * removed only if its owner is still the one seen as stale; a fresh lock that another process made + * meanwhile is put back. + */ +function takeOverIfStale(f: typeof fs, lockDir: string): void { + const seen = ownerOf(f, lockDir); + try { + if (Date.now() - f.statSync(lockDir).mtimeMs <= STALE_MS) return; + } catch { + return; // released meanwhile + } + const aside = `${lockDir}.stale-${randomUUID()}`; + try { + f.renameSync(lockDir, aside); + } catch { + return; // another process moved or released it first + } + if (ownerOf(f, aside) === seen) { + f.rmSync(aside, { recursive: true, force: true }); + return; + } + try { + f.renameSync(aside, lockDir); + } catch { + // Its owner has finished and a newer lock exists; nothing refers to this copy any more. + f.rmSync(aside, { recursive: true, force: true }); + } +} + +/** Runs `fn` while holding the lock directory `lockDir`, taking over a stale one. */ +export function withLock(lockDir: string, fn: () => T, f: typeof fs = fs): T { + const token = randomUUID(); for (let tries = 0; ; tries++) { try { - fs.mkdirSync(lockDir); + f.mkdirSync(lockDir); + f.writeFileSync(path.join(lockDir, 'owner'), token); break; } catch (error) { - if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; - try { - if (Date.now() - fs.statSync(lockDir).mtimeMs > 10_000) { - fs.rmSync(lockDir, { recursive: true, force: true }); - continue; - } - } catch { - continue; // released meanwhile - } + if (!BUSY.has((error as NodeJS.ErrnoException).code ?? '')) throw error; + takeOverIfStale(f, lockDir); if (tries > 3_000) throw new Error(`test-phones: lock ${lockDir} stays taken`); pause(10); } @@ -57,7 +96,7 @@ function withLock(lockDir: string, fn: () => T): T { try { return fn(); } finally { - fs.rmSync(lockDir, { recursive: true, force: true }); + if (ownerOf(f, lockDir) === token) f.rmSync(lockDir, { recursive: true, force: true }); } } @@ -99,6 +138,12 @@ export function phoneSource( return () => { if (next >= end) takeBlock(); const n = next++; - return `${prefix}${LOW + (n % SPAN)}`; + if (n >= SPAN) { + throw new Error( + `The test phone range of ${url.pathname.slice(1)} is used up: recreate the test database, ` + + `delete ${counterFile} and move EPOCH_MS in test-phones.ts (both copies) to today`, + ); + } + return `${prefix}${LOW + n}`; }; } diff --git a/packages/db/test/test-phones.test.ts b/packages/db/test/test-phones.test.ts index 877a4ec..50d5a46 100644 --- a/packages/db/test/test-phones.test.ts +++ b/packages/db/test/test-phones.test.ts @@ -1,14 +1,17 @@ +import { execFile } from 'node:child_process'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; +import { promisify } from 'node:util'; import { BD_PHONE_E164 } from '@jantrik/shared'; import { afterEach, beforeEach, describe, expect, it } from 'vitest'; -import { floorAt, phoneSource } from './test-phones.js'; +import { floorAt, phoneSource, withLock } from './test-phones.js'; describe('test phones (decisions-pending P0-8)', () => { let dir: string; const db = 'postgresql://u:p@localhost:5432/jantrik_x_test'; const t0 = Date.UTC(2026, 10, 16, 9); + const counterFile = () => path.join(dir, 'localhost_5432_jantrik_x_test__88013.txt'); beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-phones-')); @@ -40,9 +43,24 @@ describe('test phones (decisions-pending P0-8)', () => { const first = phoneSource('+88013', db, { dir, now: () => t0 }); const earlier = new Set(Array.from({ length: 300 }, () => first())); fs.rmSync(dir, { recursive: true, force: true }); - const later = phoneSource('+88013', db, { dir, now: () => t0 + 60_000 }); + const later = phoneSource('+88013', db, { dir, now: () => t0 + 3_600_000 }); for (let i = 0; i < 300; i++) expect(earlier.has(later())).toBe(false); - expect(floorAt(t0 + 60_000) - floorAt(t0)).toBeGreaterThan(300); + }); + + it('lets the clock floor rise one number a second (about a year and a half of range)', () => { + expect(floorAt(t0 + 1_000) - floorAt(t0)).toBe(1); + expect(floorAt(Date.UTC(2028, 3, 1))).toBeLessThan(49_000_000); + }); + + it('never wraps: past the end of its range it stops instead of repeating old numbers', () => { + // The clock alone past the end (about May 2028). + const late = phoneSource('+88013', db, { dir, now: () => Date.UTC(2028, 6, 1) }); + expect(() => late()).toThrow(/test phone range .* is used up/); + // A counter at the last number: that one is given, the next one is refused. + fs.writeFileSync(counterFile(), String(49_000_000 - 1)); + const last = phoneSource('+88013', db, { dir, now: () => t0 }); + expect(last()).toBe('+8801398999999'); + expect(() => last()).toThrow(/is used up/); }); it('keeps a counter per database: another database starts on its own', () => { @@ -66,12 +84,103 @@ describe('test phones (decisions-pending P0-8)', () => { }); it('takes over a lock left behind by a process that died', () => { - const counter = path.join(dir, 'localhost_5432_jantrik_x_test__88013.txt'); - fs.mkdirSync(`${counter}.lock`); + fs.mkdirSync(`${counterFile()}.lock`); const old = new Date(Date.now() - 60_000); - fs.utimesSync(`${counter}.lock`, old, old); + fs.utimesSync(`${counterFile()}.lock`, old, old); const next = phoneSource('+88013', db, { dir, now: () => t0 }); expect(next()).toMatch(BD_PHONE_E164); - expect(fs.existsSync(`${counter}.lock`)).toBe(false); + expect(fs.existsSync(`${counterFile()}.lock`)).toBe(false); + }); + + it('waits when Windows refuses to make the lock (EPERM, EACCES: a lock being removed)', () => { + const lock = path.join(dir, 'x.lock'); + let refusals = 0; + const flaky: typeof fs = { + ...fs, + mkdirSync: ((p: fs.PathLike, o?: fs.MakeDirectoryOptions) => { + if (p === lock && refusals < 2) { + refusals++; + throw Object.assign(new Error('refused'), { code: refusals === 1 ? 'EPERM' : 'EACCES' }); + } + return fs.mkdirSync(p, o); + }) as typeof fs.mkdirSync, + }; + expect(withLock(lock, () => 'done', flaky)).toBe('done'); + expect(refusals).toBe(2); + expect(fs.existsSync(lock)).toBe(false); + }); + + it('never removes a fresh lock that replaced the stale one it saw', () => { + const lock = path.join(dir, 'x.lock'); + const owner = (): string | null => { + try { + return fs.readFileSync(path.join(lock, 'owner'), 'utf8'); + } catch { + return null; + } + }; + fs.mkdirSync(lock); + fs.writeFileSync(path.join(lock, 'owner'), 'dead'); + const old = new Date(Date.now() - 60_000); + fs.utimesSync(lock, old, old); + let replaced = false; + let waits = 0; + let freshRemoved = 0; + const racy: typeof fs = { + ...fs, + // Right after this process sees the stale lock, another one takes it over first. + statSync: ((p: fs.PathLike) => { + const stat = fs.statSync(p); + if (p === lock && !replaced) { + replaced = true; + fs.rmSync(lock, { recursive: true, force: true }); + fs.mkdirSync(lock); + fs.writeFileSync(path.join(lock, 'owner'), 'fresh'); + } + return stat; + }) as typeof fs.statSync, + // The other process finishes after a few of this one's attempts. + mkdirSync: ((p: fs.PathLike, o?: fs.MakeDirectoryOptions) => { + if (p === lock && replaced && owner() === 'fresh' && ++waits === 3) { + fs.rmSync(lock, { recursive: true, force: true }); + } + return fs.mkdirSync(p, o); + }) as typeof fs.mkdirSync, + rmSync: ((p: fs.PathLike, o?: fs.RmOptions) => { + if (p === lock && owner() === 'fresh') freshRemoved++; + return fs.rmSync(p, o); + }) as typeof fs.rmSync, + }; + expect(withLock(lock, () => 'done', racy)).toBe('done'); + expect(replaced).toBe(true); + expect(freshRemoved).toBe(0); + expect(waits).toBeGreaterThanOrEqual(3); + }); + + it('never repeats when several processes draw at once, a stale lock waiting for them', async () => { + fs.mkdirSync(`${counterFile()}.lock`); + const old = new Date(Date.now() - 60_000); + fs.utimesSync(`${counterFile()}.lock`, old, old); + const child = path.join(dir, 'draw.mjs'); + fs.writeFileSync( + child, + [ + "import { pathToFileURL } from 'node:url';", + 'const { phoneSource } = await import(pathToFileURL(process.argv[2]).href);', + "const next = phoneSource('+88013', process.argv[3], { dir: process.argv[4] });", + 'const out = [];', + 'for (let i = 0; i < 1000; i++) out.push(next());', + 'process.stdout.write(JSON.stringify(out));', + ].join('\n'), + ); + const source = path.join(import.meta.dirname, 'test-phones.ts'); + const runs = await Promise.all( + Array.from({ length: 4 }, () => + promisify(execFile)(process.execPath, [child, source, db, dir], { timeout: 60_000 }), + ), + ); + const all = runs.flatMap((r) => JSON.parse(r.stdout) as string[]); + expect(all).toHaveLength(4_000); + expect(new Set(all).size).toBe(4_000); }); }); diff --git a/packages/db/test/test-phones.ts b/packages/db/test/test-phones.ts index f03c431..d200eed 100644 --- a/packages/db/test/test-phones.ts +++ b/packages/db/test/test-phones.ts @@ -1,3 +1,4 @@ +import { randomUUID } from 'node:crypto'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; @@ -13,7 +14,8 @@ import path from 'node:path'; * one by one. The counter never goes back behind the clock (`floorAt`), so a lost counter file * does not restart at numbers earlier runs gave out. The numbers sit where nothing else is: * `` + 50 000 000–98 999 999 (the seeds' fixed numbers are below; the old random phones - * used other operators). + * used other operators). They never wrap: when the range is used up (the clock alone reaches its + * end in about May 2028), drawing stops with a message instead of repeating old numbers. * * Kept identical in packages/db/test/test-phones.ts and apps/api/test/support/test-phones.ts (a * test of the db copy pins how it behaves). @@ -23,9 +25,13 @@ import path from 'node:path'; const BLOCK = 200; const LOW = 50_000_000; const SPAN = 49_000_000; -/** The counter's floor grows 20 a second from this day, so it is always ahead of older runs. */ +/** The counter's floor grows 1 a second from this day, so it is always ahead of older runs. */ const EPOCH_MS = Date.UTC(2026, 10, 1); -const PER_SECOND = 20; +const PER_SECOND = 1; +/** A lock older than this was left by a process that died (the locked work takes microseconds). */ +const STALE_MS = 10_000; +/** What `mkdir` answers while the lock exists, or (Windows) while it is being removed. */ +const BUSY = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY', 'ENOTEMPTY']); export const floorAt = (nowMs: number): number => Math.max(0, Math.floor(((nowMs - EPOCH_MS) / 1000) * PER_SECOND)); @@ -34,22 +40,55 @@ const pause = (ms: number): void => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }; -/** Runs `fn` while holding a lock directory; a lock older than 10 s is left over and taken. */ -function withLock(lockDir: string, fn: () => T): T { +const ownerOf = (f: typeof fs, lockDir: string): string | null => { + try { + return f.readFileSync(path.join(lockDir, 'owner'), 'utf8'); + } catch { + return null; + } +}; + +/** + * Removes the lock if it is stale. It is first moved aside (a rename: only one process can), and + * removed only if its owner is still the one seen as stale; a fresh lock that another process made + * meanwhile is put back. + */ +function takeOverIfStale(f: typeof fs, lockDir: string): void { + const seen = ownerOf(f, lockDir); + try { + if (Date.now() - f.statSync(lockDir).mtimeMs <= STALE_MS) return; + } catch { + return; // released meanwhile + } + const aside = `${lockDir}.stale-${randomUUID()}`; + try { + f.renameSync(lockDir, aside); + } catch { + return; // another process moved or released it first + } + if (ownerOf(f, aside) === seen) { + f.rmSync(aside, { recursive: true, force: true }); + return; + } + try { + f.renameSync(aside, lockDir); + } catch { + // Its owner has finished and a newer lock exists; nothing refers to this copy any more. + f.rmSync(aside, { recursive: true, force: true }); + } +} + +/** Runs `fn` while holding the lock directory `lockDir`, taking over a stale one. */ +export function withLock(lockDir: string, fn: () => T, f: typeof fs = fs): T { + const token = randomUUID(); for (let tries = 0; ; tries++) { try { - fs.mkdirSync(lockDir); + f.mkdirSync(lockDir); + f.writeFileSync(path.join(lockDir, 'owner'), token); break; } catch (error) { - if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; - try { - if (Date.now() - fs.statSync(lockDir).mtimeMs > 10_000) { - fs.rmSync(lockDir, { recursive: true, force: true }); - continue; - } - } catch { - continue; // released meanwhile - } + if (!BUSY.has((error as NodeJS.ErrnoException).code ?? '')) throw error; + takeOverIfStale(f, lockDir); if (tries > 3_000) throw new Error(`test-phones: lock ${lockDir} stays taken`); pause(10); } @@ -57,7 +96,7 @@ function withLock(lockDir: string, fn: () => T): T { try { return fn(); } finally { - fs.rmSync(lockDir, { recursive: true, force: true }); + if (ownerOf(f, lockDir) === token) f.rmSync(lockDir, { recursive: true, force: true }); } } @@ -99,6 +138,12 @@ export function phoneSource( return () => { if (next >= end) takeBlock(); const n = next++; - return `${prefix}${LOW + (n % SPAN)}`; + if (n >= SPAN) { + throw new Error( + `The test phone range of ${url.pathname.slice(1)} is used up: recreate the test database, ` + + `delete ${counterFile} and move EPOCH_MS in test-phones.ts (both copies) to today`, + ); + } + return `${prefix}${LOW + n}`; }; } From 27403c3badf8a574a98cf3487fd0c262cf7a3cd5 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:42:57 +0600 Subject: [PATCH 27/44] =?UTF-8?q?The=20institute-name=20rule=20compares=20?= =?UTF-8?q?passwords=20and=20names=20like=20the=20phone=20rule=20(review?= =?UTF-8?q?=20of=20PR=20#17):=20NFKC=20(full-width=20letters=20and=20digit?= =?UTF-8?q?s),=20lower=20case,=20ASCII=20digits,=20khanda=20ta's=20old=20e?= =?UTF-8?q?ncoding=20(=E0=A6=A4=20+=20=E0=A7=8D=20+=20ZWJ)=20read=20as=20?= =?UTF-8?q?=E0=A7=8E,=20and=20without=20spaces,=20punctuation,=20symbols?= =?UTF-8?q?=20or=20any=20invisible=20character=20(soft=20hyphen,=20zero-wi?= =?UTF-8?q?dth=20space,=20word=20joiner=E2=80=A6,=20not=20only=20ZWJ/ZWNJ)?= =?UTF-8?q?.=20Names=20also=20split=20at=20zero-width=20spaces.=20So=20ko.?= =?UTF-8?q?dom2026xyzw,=20k-o-d-o-m-2026,=20full-width=20=EF=BD=8B?= =?UTF-8?q?=EF=BD=8F=EF=BD=84=EF=BD=8F=EF=BD=8D,=20kodom=20?= =?UTF-8?q?and=20a=20name=20typed=20"KodomTola"=20are=20caught.=20Wo?= =?UTF-8?q?rds=20of=20digits=20only=20are=20not=20distinctive=20("Udvash?= =?UTF-8?q?=202026=20Batch"=20no=20longer=20refuses=20mypass2026abc;=20the?= =?UTF-8?q?=20whole=20name=20still=20counts).=20More=20generic=20words=20i?= =?UTF-8?q?n=20English=20letters=20and=20Bangla:=20balika,=20uchcha,=20bid?= =?UTF-8?q?yalay,=20madhyamik,=20prathomik,=20adarsha,=20sarkari,=20pilot,?= =?UTF-8?q?=20memorial,=20smriti,=20shaheed,=20shishu,=20ebtedayee,=20nurs?= =?UTF-8?q?ery=20and=20their=20spellings.=20Glued=20generic=20endings=20ar?= =?UTF-8?q?e=20cut=20only=20when=20they=20are=206=20or=20more=20code=20poi?= =?UTF-8?q?nts=20together,=20so=20"Australia"=20no=20longer=20yields=20the?= =?UTF-8?q?=20fragment=20"austr"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- packages/shared/src/password.test.ts | 53 ++++++++++++++++++++++++++++ packages/shared/src/password.ts | 49 +++++++++++++++++++------ 2 files changed, 91 insertions(+), 11 deletions(-) diff --git a/packages/shared/src/password.test.ts b/packages/shared/src/password.test.ts index 5dde652..a5f33d7 100644 --- a/packages/shared/src/password.test.ts +++ b/packages/shared/src/password.test.ts @@ -143,6 +143,59 @@ describe('password rules (S26, P1-C, P1-D)', () => { refused('শা‌পলা২০২৬১২৩৪', 'শাপলা মাদ্রাসা'); }); + it.each<[string, string]>([ + // Invisible characters (soft hyphen, zero-width space, word joiner) on either side. + ['শাপলা২০২৬১২৩৪', 'শা­পলা উচ্চ বিদ্যালয়'], + ['kodom2026xyzw', 'Kodom​Tola School'], + ['tola2026xyzw', 'Kodom​Tola School'], + ['ko​dom2026xyzw', 'Kodom Tola School'], + ['ko­dom2026xyzw', 'Kodom Tola School'], + ['ko⁠dom2026xyzw', 'Kodom Tola School'], + // Khanda ta in its old encoding (ত + hasant + ZWJ) is ৎ. + ['উত্‍সব২০২৬১২৩৪', 'উৎসব উচ্চ বিদ্যালয়'], + ['উৎসব২০২৬১২৩৪', 'উত্‍সব উচ্চ বিদ্যালয়'], + // Punctuation and symbols between the letters, full-width letters, Bangla digits. + ['ko.dom2026xyzw', 'Kodom Tola School'], + ['k-o-d-o-m-2026', 'Kodom Tola School'], + ['kodom2০২৬x', 'Kodom Tola School'], + ['alo৭১২০২৬xyz', 'Alo71 Coaching'], + ])('refuses %s for "%s" (written another way)', (pw, name) => refused(pw, name)); + + it('skips words that are only digits (the whole name still counts)', () => { + allowed('mypass2026abc', 'Udvash 2026 Batch'); + allowed('anything১৯৭১x', 'Kodom 1971 School'); + refused('kodom১৯৭১school', 'Kodom 1971 School'); + }); + + it.each<[string, string]>([ + ['balika2026xyz', 'Kodom Tola Balika Bidyalaya'], + ['uchcha2026xyz', 'Shapla Uchcha Bidyalay'], + ['madhyamik2026', 'Shapla Madhyamik Bidyalay'], + ['prathomik2026', 'Shapla Prathomik Bidyalay'], + ['adarsha2026xy', 'Shapla Adarsha Bidyalay'], + ['sarkari2026xy', 'Shapla Sarkari Bidyalay'], + ['pilot2026xyzw', 'Kodom Pilot High School'], + ['memorial2026x', 'Abdul Karim Memorial School'], + ['স্মৃতি২০২৬১২৩৪', 'শহীদ স্মৃতি উচ্চ বিদ্যালয়'], + ['শহীদ২০২৬১২৩৪', 'শহীদ স্মৃতি উচ্চ বিদ্যালয়'], + ['ইবতেদায়ী২০২৬১২', 'শাপলা ইবতেদায়ী মাদ্রাসা'], + ['ebtedayee2026', 'Shapla Ebtedayee Madrasa'], + ['শিশু২০২৬১২৩৪৫', 'শাপলা শিশু নিকেতন'], + ['নার্সারি২০২৬১২', 'শাপলা নার্সারি স্কুল'], + ['nursery2026xy', 'Shapla Nursery School'], + ['পাইলট২০২৬১২৩৪', 'শাপলা পাইলট উচ্চ বিদ্যালয়'], + ])('allows %s for "%s" (generic words written in English letters, and more)', (pw, name) => + allowed(pw, name), + ); + + it('cuts glued generic endings of 6 characters or more only, so short ones leave no fragments', () => { + // "alia" (4) ends Australia: not cut, so "austr" is not a word of the name. + allowed('austr2026xyzw', 'Australia International School'); + refused('australia2026', 'Australia International School'); + // "republic" ends in "public" (6): cut, but "re" is too short to count; the word stays. + refused('republic2026x', 'Republic Model School'); + }); + it('still refuses the whole name, generic words included', () => { refused('alocoaching!!', 'Alo Coaching'); refused('উচ্চবিদ্যালয়', 'উচ্চ বিদ্যালয়'); diff --git a/packages/shared/src/password.ts b/packages/shared/src/password.ts index 5dfd7e4..d7d6e47 100644 --- a/packages/shared/src/password.ts +++ b/packages/shared/src/password.ts @@ -23,12 +23,26 @@ export function normalizePassword(pw: string): string { return pw.normalize('NFC'); } -/** Zero-width joiner and non-joiner: typed inside some Bangla words (মাদ্‌রাসা), invisible. */ -const ZERO_WIDTH = /[‌‍]/gu; +/** Khanda ta in its old encoding (ত + hasant + zero-width joiner), the same letter as ৎ. */ +const OLD_KHANDA_TA = /\u09A4\u09CD\u200D/gu; +/** Characters that show nothing (soft hyphen, zero-width space and joiners, word joiner…). */ +const INVISIBLE = /\p{Default_Ignorable_Code_Point}/gu; +/** Where an institute name splits into words: spaces, punctuation, symbols, zero-width spaces. */ +const WORD_BREAK = /[\p{P}\p{S}\s\u200B]+/u; +/** What a password and a name are compared without, as the phone rule does. */ +const NOT_COMPARED = /[\p{P}\p{S}\s\p{Default_Ignorable_Code_Point}]/gu; -/** NFC, lower-case, without whitespace or zero-width joiners: how passwords and names compare. */ +/** + * NFKC (full-width letters and digits become plain ones), khanda ta unified, lower-case, ASCII + * digits: the form in which passwords and institute names are compared. + */ +function folded(text: string): string { + return toAsciiDigits(text.normalize('NFKC').replace(OLD_KHANDA_TA, '\u09CE').toLowerCase()); +} + +/** `folded`, without spaces, punctuation, symbols or invisible characters. */ function comparable(text: string): string { - return text.normalize('NFC').toLowerCase().replace(/\s+/gu, '').replace(ZERO_WIDTH, ''); + return folded(text).replace(NOT_COMPARED, ''); } /** @@ -47,6 +61,9 @@ export const GENERIC_NAME_WORDS: readonly string[] = ` alia aliya aliah dakhil alim fazil kamil hafizia hafezia hifz hifzul tahfiz tahfizul quran qawmi qaumi kawmi nurani noorani darul uloom ulum jamia jamea bidyalaya bidyaloy biddyaloy vidyalaya bidyapith bidyaniketan niketan pathshala shikkha + balika balok uchcha uccha bidyalay biddyalay vidyalay madhyamik madhyomik maddhomik + prathomik prathamik adarsha adarsho adarsa sarkari sorkari pilot memorial smriti smrity sriti + shishu sishu ebtedayee ebtedayi ibtedayee ibtedayi nursery shaheed shahid shohid বিদ্যালয় মহাবিদ্যালয় উচ্চ মাধ্যমিক নিম্ন প্রাথমিক জুনিয়র সিনিয়র স্কুল হাই কলেজ মাদ্রাসা মাদরাসা একাডেমি একাডেমী বিশ্ববিদ্যালয় সরকারি সরকারী বেসরকারি বেসরকারী মডেল আদর্শ আইডিয়াল পাবলিক ক্যাডেট আবাসিক রেসিডেন্সিয়াল বালিকা বালক মহিলা গার্লস বয়েজ ইংলিশ বাংলা মিডিয়াম ভার্সন @@ -55,6 +72,7 @@ export const GENERIC_NAME_WORDS: readonly string[] = ` কামিল হাফিজিয়া হাফেজিয়া হিফজ হিফজুল তাহফিজুল কুরআন কোরআন নূরানী নুরানী কওমী কওমি ইসলামিয়া ইসলামী ইসলামি দারুল উলুম জামিয়া পাঠশালা বিদ্যানিকেতন বিদ্যাপীঠ বিদ্যামন্দির নিকেতন শিক্ষা শিক্ষালয় অ্যান্ড এন্ড এবং + পাইলট মেমোরিয়াল স্মৃতি শিশু ইবতেদায়ী ইবতেদায়ি নার্সারি নার্সারী শহীদ শহিদ ` .split(/\s+/u) .filter((w) => w !== ''); @@ -62,6 +80,13 @@ export const GENERIC_NAME_WORDS: readonly string[] = ` const GENERIC = new Set(GENERIC_NAME_WORDS.map(comparable)); const GENERIC_LIST = [...GENERIC]; +/** + * Generic words glued to the end of a word are cut off only when together they are this long (in + * code points): `শাপলাউচ্চবিদ্যালয়` → `শাপলা`, `kodomtolaschool` → `kodomtola`, but `australia` keeps + * its `alia`, so no fragment like `austr` becomes a word of the name. + */ +const MIN_GLUED_TAIL = 6; + /** * Where the generic words glued to the end of a word start (`কোচিংসেন্টার` → 0, * `শাপলাউচ্চবিদ্যালয়` → the index of উচ্চ), so `শাপলা` is found in a name typed without spaces. @@ -84,16 +109,18 @@ const codePoints = (text: string): number => [...text].length; /** * The words of an institute name that point at that institute (P1-I): split at spaces, - * punctuation and symbols, generic words dropped, 4 characters (code points) or more. A word with - * generic words glued to its end counts twice, whole and without them. + * punctuation, symbols and zero-width spaces, compared as `comparable` does; generic words and + * words of digits only are dropped; 4 characters (code points) or more. A word with generic words + * of `MIN_GLUED_TAIL` or more glued to its end counts twice, whole and without them. */ export function distinctiveNameWords(name: string): string[] { const words = new Set(); - const raw = name.normalize('NFC').toLowerCase().replace(ZERO_WIDTH, ''); - for (const word of raw.split(/[\p{P}\p{S}\s]+/u)) { - if (word === '') continue; - const stem = word.slice(0, genericTailStart(word)); - if (stem === '') continue; // only generic words + for (const part of folded(name).split(WORD_BREAK)) { + const word = part.replace(INVISIBLE, ''); + if (word === '' || /^\d+$/u.test(word)) continue; + const cut = genericTailStart(word); + if (cut === 0) continue; // only generic words + const stem = codePoints(word.slice(cut)) >= MIN_GLUED_TAIL ? word.slice(0, cut) : word; for (const w of [word, stem]) if (codePoints(w) >= MIN_NAME_LENGTH) words.add(w); } return [...words]; From 7aa31c5f5c8d5c76c7953c8487fbd79f62cd4d22 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:42:58 +0600 Subject: [PATCH 28/44] An origin setting with a login, a path, a query or a fragment is no origin (review of PR #17): normaliseOrigin used URL.origin, which drops them, so https://app.jantrik.com.bd@evil.example became https://evil.example and passed the production check, in CORS_ORIGINS and (since before this PR) in PLATFORM_ORIGINS. Now production refuses such an entry in either list ("not an origin"), PLATFORM_ORIGINS refuses it everywhere as it refused non-URLs, and in development a CORS_ORIGINS entry like that stays as written and matches no browser Co-Authored-By: Claude Opus 5.5 --- apps/api/src/config/env.ts | 10 +++++-- apps/api/src/config/production-env.spec.ts | 34 ++++++++++++++++++++++ apps/api/src/config/production-env.ts | 11 +++++-- 3 files changed, 49 insertions(+), 6 deletions(-) diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts index a471784..3b4d2fb 100644 --- a/apps/api/src/config/env.ts +++ b/apps/api/src/config/env.ts @@ -29,8 +29,9 @@ export const envSchema = z /** * Comma-separated allowlist of browser origins (credentials are allowed). Normalised as * browsers send `Origin` (lower-case host, no trailing slash, no default port), so the CORS - * check (an exact match) allows what the production check passed. An entry that is not an - * origin stays as written: it matches nothing, and production refuses it. + * check (an exact match) allows what the production check passed. An entry that is not exactly + * an origin (not a URL, or with a login, a path, a query or a fragment) stays as written: it + * matches no browser's Origin, and production refuses it. */ CORS_ORIGINS: z .string() @@ -58,7 +59,10 @@ export const envSchema = z .filter(Boolean)) { const origin = normaliseOrigin(entry); if (origin === null) { - ctx.addIssue({ code: 'custom', message: `PLATFORM_ORIGINS: "${entry}" is not a URL` }); + ctx.addIssue({ + code: 'custom', + message: `PLATFORM_ORIGINS: "${entry}" is not an origin (scheme, host and port only)`, + }); return z.NEVER; } origins.push(origin); diff --git a/apps/api/src/config/production-env.spec.ts b/apps/api/src/config/production-env.spec.ts index 91d5de7..c4a5568 100644 --- a/apps/api/src/config/production-env.spec.ts +++ b/apps/api/src/config/production-env.spec.ts @@ -6,6 +6,7 @@ import { validateIngestEnv } from './ingest-env.js'; import { API_ONLY_SECRETS, DATABASE_ADMIN_SECRETS, + normaliseOrigin, trustsAnyClient, unsafeOrigin, } from './production-env.js'; @@ -190,6 +191,39 @@ describe('production env: the API and the worker', () => { expect(new Set(images.map((i) => i.image)).size).toBe(1); }); + it('treats an entry with a login, a path, a query or a fragment as no origin at all', () => { + const dev = { + DATABASE_URL: 'postgresql://jantrik_app:x@localhost:5432/jantrik', + DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:x@localhost:5432/jantrik', + DATABASE_INGEST_URL: 'postgresql://jantrik_ingest_app:x@localhost:5432/jantrik', + JWT_ACCESS_SECRET: 'x'.repeat(40), + OTP_PEPPER: 'y'.repeat(40), + }; + for (const entry of [ + // A URL's origin would drop the part before @: this is https://evil.example. + 'https://app.jantrik.com.bd@evil.example', + 'https://user:pw@app.jantrik.com.bd', + 'https://app.jantrik.com.bd/app', + 'https://app.jantrik.com.bd/?x=1', + 'https://app.jantrik.com.bd/#top', + ]) { + expect(normaliseOrigin(entry), entry).toBeNull(); + // Production refuses it in either list. + expect( + apiError({ ...api, CORS_ORIGINS: `${entry},https://platform.jantrik.com.bd` }), + ).toMatch(/CORS_ORIGINS must hold https origins only; ".*" is not an origin/); + expect(apiError({ ...api, PLATFORM_ORIGINS: entry })).toMatch( + /PLATFORM_ORIGINS: ".*" is not an origin/, + ); + // Development keeps a CORS entry as written: it matches no browser's Origin. + const parsed = envSchema.parse({ ...dev, CORS_ORIGINS: entry }); + expect(parsed.CORS_ORIGINS).toEqual([entry]); + expect(isAllowedOrigin('https://evil.example', parsed)).toBe(false); + expect(isAllowedOrigin('https://app.jantrik.com.bd', parsed)).toBe(false); + } + expect(normaliseOrigin('HTTPS://App.Jantrik.com.bd:443/')).toBe('https://app.jantrik.com.bd'); + }); + it('normalises CORS_ORIGINS too, so the CORS middleware allows what the start-up check passed', () => { const dev = { DATABASE_URL: 'postgresql://jantrik_app:x@localhost:5432/jantrik', diff --git a/apps/api/src/config/production-env.ts b/apps/api/src/config/production-env.ts index 293528e..0018f2e 100644 --- a/apps/api/src/config/production-env.ts +++ b/apps/api/src/config/production-env.ts @@ -26,15 +26,19 @@ const LOCAL_HOST = /^(localhost|127(\.\d{1,3}){3}|\[::1\]|0\.0\.0\.0|\[::\])$/i; /** * A browser origin as browsers send it in `Origin` (scheme, lower-case host, port when not the - * default; no path or trailing slash), or null when `value` is not a URL with an origin. + * default; no trailing slash), or null when `value` is not exactly an origin. A login, a path, a + * query or a fragment makes it no origin: `URL.origin` would silently drop them, and + * `https://app.example@evil.example` would become `https://evil.example`. */ export function normaliseOrigin(value: string): string | null { + let url: URL; try { - const origin = new URL(value).origin; - return origin === 'null' ? null : origin; + url = new URL(value); } catch { return null; } + if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) return null; + return url.origin === 'null' ? null : url.origin; } /** Why a browser origin may not be allowed in production, or null when it may. */ @@ -46,6 +50,7 @@ export function unsafeOrigin(origin: string): string | null { } catch { return 'not a URL'; } + if (normaliseOrigin(origin) === null) return 'not an origin (scheme, host and port only)'; if (url.protocol !== 'https:') return 'not https'; if (LOCAL_HOST.test(url.hostname) || url.hostname.endsWith('.localhost')) { return 'a local address'; From fd6430e9c5bbb4f957404260530de1aa79efdd24 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:42:58 +0600 Subject: [PATCH 29/44] Docs after the review of PR #17: P1-I's title line says it is built here (its other lines untouched), F-1 gives how both sides are compared and the 6-character rule for glued endings, F-2 the added generic words, F-3 the origin fix (PLATFORM_ORIGINS too), F-6 the 1-a-second floor, no wrapping and the lock; auth.md describes the rule and exact origins Co-Authored-By: Claude Opus 5.5 --- docs/auth.md | 20 ++++++++---- docs/decisions-pending.md | 67 +++++++++++++++++++++++++-------------- 2 files changed, 56 insertions(+), 31 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index 9e5ac5d..e0220fc 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -200,13 +200,16 @@ audited in that institute. Someone who is staff elsewhere switches to that insti - `HAS_PHONE`: the person's 10-digit national number, in any form (`01…`, `+880…`, Bangla digits, split by spaces, punctuation or symbols); - `HAS_INSTITUTE_NAME`: the whole name of any institute they are an active member of (as a - guardian too), or one of its distinctive words (P1-I), ignoring case, spaces and zero-width - joiners. Distinctive: the name split at spaces, punctuation and symbols, generic words - dropped (`GENERIC_NAME_WORDS` in `packages/shared/src/password.ts`: school, college, madrasa, - academy, coaching, high, model, বিদ্যালয়, উচ্চ, স্কুল, মাদ্রাসা, কলেজ, কোচিং… and their spellings), - and generic words glued to a word's end also counted without them (`শাপলাউচ্চবিদ্যালয়` → - `শাপলা`). Names and words under 4 characters (code points) are skipped. So for "শাপলা উচ্চ - বিদ্যালয়", `শাপলা২০২৬১২৩৪` is refused and `বিদ্যালয়২০২৬১২` is not; + guardian too), or one of its distinctive words (P1-I). Both sides are compared in NFKC, lower + case, with ASCII digits, khanda ta's old encoding read as ৎ, and without spaces, punctuation, + symbols or invisible characters (soft hyphen, zero-width space and joiners…), so `ko.dom2026` + contains `kodom`. Distinctive: the name split at spaces, punctuation, symbols and zero-width + spaces; generic words (`GENERIC_NAME_WORDS` in `packages/shared/src/password.ts`: school, + college, madrasa, academy, coaching, high, model, বিদ্যালয়, উচ্চ, স্কুল, মাদ্রাসা, কলেজ, কোচিং… + and their spellings) and words of digits only dropped; generic words of 6 or more code points + glued to a word's end also cut off (`শাপলাউচ্চবিদ্যালয়` → `শাপলা`). Names and words under 4 + characters (code points) are skipped. So for "শাপলা উচ্চ বিদ্যালয়", `শাপলা২০২৬১২৩৪` is refused + and `বিদ্যালয়২০২৬১২` is not; - `TOO_COMMON`: on the list in `apps/api/src/auth/common-passwords.txt` (SecLists' 10,000 most common, MIT; plus jantrik, bangladesh and password with digits and years). Server only; 3. the code, else `422 PASSWORD_CODE_INVALID` (wrong, expired or used). Checking the rules first @@ -464,6 +467,9 @@ Code: [`apps/web/src/lib/auth/auth-client.ts`](../apps/web/src/lib/auth/auth-cli `CORS_ORIGINS` and `PLATFORM_ORIGINS` are normalised as browsers send `Origin` (lower-case host, no trailing slash or default port), so an entry written `https://App.example.com/` still matches. +An entry with a login, a path, a query or a fragment is no origin (`https://app.example@evil.example` +is not `https://evil.example`): production refuses it in either list, `PLATFORM_ORIGINS` everywhere, +and in development a `CORS_ORIGINS` entry like that matches nothing. In production `SMS_PROVIDER=none` stands in until a gateway is built: every SMS fails and is recorded as failed. What else production refuses: [deploy.md](deploy.md) → Environment checks. diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index 9619c05..38be80b 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -605,35 +605,49 @@ Branch `chore/small-followups`, one PR. Decided by the agent alone (the owner wa be changed in review. F-1. **P1-I is built as the owner answered:** a password is also refused when it contains a -distinctive word of an institute's name. The name is split at spaces, punctuation and symbols; -generic words are dropped; every remaining word of 4 or more code points (the whole-name rule's -counting) is refused. The whole-name rule stays. The error code stays `HAS_INSTITUTE_NAME` (its -message now says "the name or a word from it"), so the web and the API did not change shape. +distinctive word of an institute's name. The name is split at spaces, punctuation, symbols and +zero-width spaces; generic words and words of digits only (`2026` in "Udvash 2026 Batch") are +dropped; every remaining word of 4 or more code points (the whole-name rule's counting) is +refused. The whole-name rule stays (digits included). Both sides are compared like the phone rule: +NFKC (full-width letters and digits), lower case, ASCII digits, khanda ta in its old encoding +(ত + ্ + ZWJ) read as ৎ, and without spaces, punctuation, symbols or invisible characters (soft +hyphen, zero-width space and joiners, word joiner…), so `ko.dom2026` or `k-o-d-o-m` count as +`kodom`. **Glued endings:** generic words glued to the end of a word are cut off only when they +are 6 or more code points together (`শাপলাউচ্চবিদ্যালয়` → `শাপলা`, `Kodomtolaschool` → +`kodomtola`), so a short generic ending leaves no fragment (`Australia` keeps its `alia`; `austr` +is not a word of the name). The error code stays `HAS_INSTITUTE_NAME` (its message now says "the +name or a word from it"), so the web and the API did not change shape. F-2. **The generic words** (`GENERIC_NAME_WORDS` in `packages/shared/src/password.ts`), chosen from the owner's examples "and similar": the kind of institute (school, college, madrasa, academy, coaching, centre, institute, kindergarten, polytechnic, pathshala…), its level (high, secondary, primary, junior, dakhil, alim, fazil, kamil…), who it is for (girls, boys, mohila…), its medium and standing (english, bangla, version, international, model, ideal, public, government/govt, cadet, -residential…), madrasa name words (darul, uloom, jamia, hafizia, nurani, qawmi, islamia, quran…), -`and` written in Bangla, each in Bangla and in English letters with common spellings (madrasah, -madrassa, মাদরাসা, সরকারী, একাডেমী…). Not generic: place names and people's names (`Dhaka`, -`Motijheel`, `Salim`): they point at the institute, so they are refused. Choices beyond the -owner's words: - -- **Generic words glued to the end of a word** are cut off too (`শাপলাউচ্চবিদ্যালয়` → `শাপলা`, - `Kodomtolaschool` → `kodomtola`), and the whole glued word is still refused as well, so the rule - never refuses less than splitting at spaces alone. Only endings: a generic word at the start of - an ordinary word is not cut (`Highland` stays `highland`, so `highschool2026` is allowed). -- **Zero-width joiners** (U+200C, U+200D: typed inside some Bangla words) are ignored on both - sides, for whole names too. Unicode forms (য় as one code point or two) were already unified. +residential, pilot, memorial, smriti, shaheed…), madrasa name words (darul, uloom, jamia, hafizia, +nurani, qawmi, islamia, quran, ebtedayee…), nursery and shishu, `and` written in Bangla, each in +Bangla and in English letters with common spellings (madrasah, madrassa, bidyalay, uchcha, +balika, madhyamik, prathomik, adarsha, sarkari, মাদরাসা, সরকারী, একাডেমী…). Not generic: place +names and people's names (`Dhaka`, `Motijheel`, `Cantonment`, `Salim`): they point at the +institute, so they are refused. Choices beyond the owner's words: + +- **Generic words glued to the end of a word** are cut off too (6 or more code points together, + F-1), and the whole glued word is still refused as well, so the rule never refuses less than + splitting at spaces alone. Only endings: a generic word at the start of an ordinary word is not + cut (`Highland` stays `highland`, so `highschool2026` is allowed). +- **Invisible characters and other ways of writing** are ignored on both sides, for whole names + too (F-1). Unicode forms (য় as one code point or two) were already unified. - **The slug is not checked** (the decision mentioned it as a "perhaps"; the owner's answer did not ask for it). F-3. **`CORS_ORIGINS` is normalised in `env.ts`** like `PLATFORM_ORIGINS` (lower-case host, no -trailing slash or default port). An entry that is not an origin (`*`, a bare host) is kept as -written instead of stopping the start: it matches nothing, production refuses it as before, and a -developer's existing `.env` keeps working. +trailing slash or default port). An entry that is not exactly an origin (`*`, a bare host, or a +URL with a login, a path, a query or a fragment) is kept as written instead of stopping the start: +it matches no browser's Origin, production refuses it, and a developer's existing `.env` keeps +working. **Also fixed for `PLATFORM_ORIGINS`** (they share the helper, which used `URL.origin`): +`https://app.jantrik.com.bd@evil.example` used to become `https://evil.example` and pass the +production check (in both lists, since before this PR for `PLATFORM_ORIGINS`). Such an entry is +now no origin: production refuses it in either list, and `PLATFORM_ORIGINS` refuses it everywhere, +as it already refused entries that are not URLs. F-4. **Redis is pinned to `redis:7.4.11-alpine`**, the version of the image this PC had (built 2026-09-17; the tag exists on Docker Hub), in the production compose, the development compose and @@ -652,10 +666,15 @@ F-6. **Test users' phones are unique per database, across runs too** (the appear P0-8). A per-run counter is not enough: the test database keeps every run's users, and Vitest gives each test file its own module (no shared memory). So one counter per database lives in a file in the OS temp folder (`jantrik-test-phones/`), taken 200 numbers at a time under a lock, and -never behind a clock that moves 20 numbers a second (a deleted file restarts ahead of older runs). -New phones use operators no test used before (API +88013, db package +88014, from 50 000 000; the -seeds' fixed numbers are lower and the old random phones were 017/018), so they cannot meet old -test users either. `randomPhone` kept its name (about 40 files call it). +never behind a clock that moves 1 number a second (a deleted file restarts ahead of older runs, +given about an hour and a half per 5 000 phones they used). New phones use operators no test used +before (API +88013, db package +88014, 50 000 000 to 98 999 999; the seeds' fixed numbers are lower +and the old random phones were 017/018), so they cannot meet old test users either. **The numbers +never wrap:** when the 49 million are used up (the clock alone gets there in about May 2028), +drawing stops with a message to recreate the test database and move the start date, instead of +repeating numbers older runs gave out. The lock is taken over only when stale (10 s), by moving it +aside first and checking its owner, and Windows' "being removed" answers (EPERM, EACCES) mean +"busy". `randomPhone` kept its name (about 40 files call it). ## The refresh race fix (2026-11-15) @@ -707,7 +726,7 @@ P1-G. **The rules are checked before the code** (a change to the plan's order, w P1-H. **`GET /me/password` also returns the person's own phone** (an addition to the plan), so the form can check the phone rule as they type. It is their own number, returned only to them. -P1-I. **Open, for the owner: catch part of an institute's name too?** The rule refuses a password containing an institute's whole name (spaces and case ignored), as planned. The review found that the likely weak form, the name's distinctive word plus a year (`শাপলা২০২৬১২৩৪` for "শাপলা উচ্চ বিদ্যালয়", `kodomtola@2026` for "Kodom Tola School"), passes. Catching it means dropping generic words (school, coaching, centre, college, academy, madrasa, high, model, উচ্চ, বিদ্যালয়, কোচিং, সেন্টার, মাদ্রাসা, একাডেমি…) and refusing what remains (4 characters or more), perhaps the slug too. It widens the rule you set, so it is not built. +P1-I. **Built in the follow-ups PR (`chore/small-followups`, the owner's answer of 2026-11-16; see F-1): a distinctive word of an institute's name is refused too.** The rule refuses a password containing an institute's whole name (spaces and case ignored), as planned. The review found that the likely weak form, the name's distinctive word plus a year (`শাপলা২০২৬১২৩৪` for "শাপলা উচ্চ বিদ্যালয়", `kodomtola@2026` for "Kodom Tola School"), passes. Catching it means dropping generic words (school, coaching, centre, college, academy, madrasa, high, model, উচ্চ, বিদ্যালয়, কোচিং, সেন্টার, মাদ্রাসা, একাডেমি…) and refusing what remains (4 characters or more), perhaps the slug too. It widened the rule you set, so it waited for your answer. - To change: `passwordProblems` in `packages/shared/src/password.ts` (the server and the form share it). From 9dbee45fe252b8922171b478d8b14c24f6f51d92 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:47:32 +0600 Subject: [PATCH 30/44] P1-J migration after the second review: it first checks that jantrik_login_app exists and stops before changing anything otherwise (Prisma does not run a migration in one transaction), and every statement can run again after migrate resolve --rolled-back (DROP FUNCTION IF EXISTS; a DB test runs the guard against a missing role and the whole migration a second time, rolled back). Schema-safety: no view or materialised view may depend on users.password_hash (with a self-check). A mixed-case email test. CI runs create-roles.sh twice Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 5 + .../migration.sql | 16 +++- packages/db/test/schema-safety.test.ts | 36 ++++++- packages/db/test/users-password-hash.test.ts | 94 +++++++++++++++++++ 4 files changed, 149 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index efe4392..25a723a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -331,6 +331,11 @@ jobs: - name: Create the roles and the production database (create-roles.sh) run: sh deploy/postgres/create-roles.sh + # An upgrade runs it again on a live cluster to add new roles (docs/deploy.md → Upgrades): + # a second run must succeed and change nothing that exists. + - name: create-roles.sh again (safe to re-run) + run: sh deploy/postgres/create-roles.sh + # Version comes from "packageManager" in package.json. - uses: pnpm/action-setup@v6 diff --git a/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql index 73662be..b323c82 100644 --- a/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql +++ b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql @@ -5,6 +5,18 @@ -- jantrik_login_app must exist first: docker/postgres/init/01-roles.sh, or for an existing local -- volume the commands in docs/database.md → Database roles; deploy/postgres/create-roles.sh in -- production. +-- +-- Prisma does not run a migration in one transaction: a statement that fails leaves the ones +-- before it applied. So the role is checked first, before anything changes, and every statement +-- can run again (after `prisma migrate resolve --rolled-back 20261116000000_users_password_hash_hidden`). + +DO $$ +BEGIN + IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'jantrik_login_app') THEN + RAISE EXCEPTION 'create the role jantrik_login_app first: docs/deploy.md → Upgrades (production), docs/database.md → Database roles (development)'; + END IF; +END +$$; -- ───────────── users: SELECT by column, every column but password_hash ───────────── -- A table-level SELECT covers every column (a column REVOKE would change nothing), so the table @@ -20,7 +32,7 @@ GRANT SELECT (id, phone, email, name, name_bn, password_changed_at, locale, colo -- pointless. The OTP login and the profile read need only who the person is. A changed result type -- needs DROP + CREATE. Privileges are set BEFORE the ownership change (see -- fix_definer_function_privileges). -DROP FUNCTION auth_find_user_for_login(text, text); +DROP FUNCTION IF EXISTS auth_find_user_for_login(text, text); CREATE FUNCTION auth_find_user_for_login(p_phone text, p_email text) RETURNS TABLE (id uuid, name text, locale locale) LANGUAGE sql STABLE SECURITY DEFINER @@ -40,6 +52,7 @@ ALTER FUNCTION auth_find_user_for_login(text, text) OWNER TO jantrik_auth; -- The password login (POST /auth/login) runs this on its own login (jantrik_login_app), which has -- no table grants and may run nothing else, so an injection in an ordinary request (jantrik_app) -- cannot reach it. The API verifies the password with argon2 itself. +DROP FUNCTION IF EXISTS auth_find_user_for_password_login(text, text); CREATE FUNCTION auth_find_user_for_password_login(p_phone text, p_email text) RETURNS TABLE (id uuid, name text, locale locale, password_hash text) LANGUAGE sql STABLE SECURITY DEFINER @@ -61,6 +74,7 @@ GRANT USAGE ON SCHEMA public TO jantrik_login_app; -- ───────────── auth_my_password_is_set(): GET /me/password's hasPassword ───────────── -- Scoped by app.user_id. A request can set that to any id with set_config, so an injection can -- learn whether a given person has a password (yes or no, nothing more): docs/auth.md. +DROP FUNCTION IF EXISTS auth_my_password_is_set(); CREATE FUNCTION auth_my_password_is_set() RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER diff --git a/packages/db/test/schema-safety.test.ts b/packages/db/test/schema-safety.test.ts index daefe11..496de80 100644 --- a/packages/db/test/schema-safety.test.ts +++ b/packages/db/test/schema-safety.test.ts @@ -1,6 +1,6 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import type { PrismaClient } from '../src/index.js'; -import { appClient, tenantTableNames } from './helpers.js'; +import { appClient, ownerClient, tenantTableNames } from './helpers.js'; // Guards against a future table being added without RLS. See docs/database.md. describe('schema safety net', () => { @@ -232,6 +232,40 @@ describe('schema safety net', () => { expect(readers).toEqual([]); }); + // Nor through a view: a view runs with its owner's rights (and a whole-row `u.*` view + // depends on every column), so no view or materialised view may read the hash. + const VIEWS_READING_HASH = ` + SELECT DISTINCT r.ev_class::regclass::text AS view + FROM pg_depend d + JOIN pg_rewrite r ON r.oid = d.objid + WHERE d.classid = 'pg_rewrite'::regclass + AND d.refclassid = 'pg_class'::regclass + AND d.refobjid = 'users'::regclass + AND d.refobjsubid = (SELECT attnum FROM pg_attribute + WHERE attrelid = 'users'::regclass AND attname = 'password_hash')`; + + it('no view or materialised view reads users.password_hash', async () => { + expect(await app.$queryRawUnsafe(VIEWS_READING_HASH)).toEqual([]); + }); + + it('the view check finds a whole-row view of users', async () => { + const owner = ownerClient(); + class Rollback extends Error {} + let found: unknown; + try { + await owner.$transaction(async (tx) => { + await tx.$executeRawUnsafe('CREATE VIEW p1j_probe AS SELECT u.* FROM users u'); + found = await tx.$queryRawUnsafe(VIEWS_READING_HASH); + throw new Rollback(); + }); + } catch (error) { + if (!(error instanceof Rollback)) throw error; + } finally { + await owner.$disconnect(); + } + expect(found).toEqual([{ view: 'p1j_probe' }]); + }); + // The hash must not come back through a definer function either. Every function a runtime login // may run whose owner can read password_hash is pinned by name: adding one is a deliberate change // here, after checking that it returns nothing of the hash. diff --git a/packages/db/test/users-password-hash.test.ts b/packages/db/test/users-password-hash.test.ts index eebc9ae..717ae39 100644 --- a/packages/db/test/users-password-hash.test.ts +++ b/packages/db/test/users-password-hash.test.ts @@ -1,3 +1,6 @@ +import { randomUUID } from 'node:crypto'; +import { readFileSync } from 'node:fs'; +import path from 'node:path'; import { hash } from '@node-rs/argon2'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { findOrCreateUser, withContext, withTenant, type PrismaClient } from '../src/index.js'; @@ -114,6 +117,19 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { ).toEqual([]); }); + it('finds an email whatever its case, as the login types it', async () => { + const email = `Staff.Login.${randomUUID().slice(0, 8)}@Example.COM`; + // The app may not change emails (P1-B): the owner sets it, as that user. + await withContext(owner, { userId: staff.id }, (tx) => + tx.user.update({ where: { id: staff.id }, data: { email }, select: { id: true } }), + ); + for (const typed of [email, email.toLowerCase(), email.toUpperCase()]) { + const rows = await login.$queryRaw<{ id: string; password_hash: string | null }[]>` + SELECT id::text, password_hash FROM auth_find_user_for_password_login(NULL, ${typed})`; + expect(rows, typed).toEqual([{ id: staff.id, password_hash: staff.hash }]); + } + }); + it('the login login reads no table and runs no other function', async () => { await expect(login.$queryRaw`SELECT id FROM users LIMIT 1`).rejects.toThrow( /permission denied/i, @@ -166,3 +182,81 @@ describe('users.password_hash is out of the app login’s reach (P1-J)', () => { expect(withHash.passwordHash).toBe(staff.hash); }); }); + +// ─────────── The migration itself (Prisma does not run it in one transaction) ─────────── + +const MIGRATION = path.resolve( + import.meta.dirname, + '../prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql', +); + +/** The migration's statements: comment lines dropped, split at semicolons outside `$$` bodies. */ +function statements(sql: string): string[] { + const code = sql + .split('\n') + .filter((line) => !line.trim().startsWith('--')) + .join('\n'); + const out: string[] = []; + let current = ''; + let inBody = false; + for (let i = 0; i < code.length; i++) { + if (code.startsWith('$$', i)) { + inBody = !inBody; + current += '$$'; + i++; + continue; + } + if (code[i] === ';' && !inBody) { + if (current.trim()) out.push(current.trim()); + current = ''; + continue; + } + current += code[i]; + } + if (current.trim()) out.push(current.trim()); + return out; +} + +class Rollback extends Error {} + +describe('the P1-J migration', () => { + let owner: PrismaClient; + const sql = readFileSync(MIGRATION, 'utf8'); + + beforeAll(() => { + owner = ownerClient(); + }); + + afterAll(async () => { + await owner.$disconnect(); + }); + + it('checks for jantrik_login_app before it changes anything', async () => { + const [guard] = statements(sql); + expect(guard).toMatch(/^DO \$\$/); + expect(guard).toContain("rolname = 'jantrik_login_app'"); + // The same block, for a role that does not exist: it stops with the instruction. + await expect( + owner.$executeRawUnsafe( + guard!.replace("rolname = 'jantrik_login_app'", "rolname = 'jantrik_no_such_role'"), + ), + ).rejects.toThrow(/create the role jantrik_login_app first/); + // The role exists here: it passes. + await owner.$executeRawUnsafe(guard!); + }); + + it('can run again over itself (after a failure and `migrate resolve --rolled-back`)', async () => { + const all = statements(sql); + expect(all.length).toBeGreaterThanOrEqual(15); + // Every statement once more, as the migration login, then rolled back. + await expect( + owner.$transaction( + async (tx) => { + for (const statement of all) await tx.$executeRawUnsafe(statement); + throw new Rollback(); + }, + { timeout: 30_000 }, + ), + ).rejects.toBeInstanceOf(Rollback); + }); +}); From a980a606a2d7e7e610875d16c45c3159fc580ada Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:47:32 +0600 Subject: [PATCH 31/44] The password login's database login must reach the same database, port and server (its start time) as the app login, or the API does not start; stored hashes are bounded in size (salt 8-64 bytes, output 16-64, at most 255 characters); login-isolation.spec.ts also pins who reads DATABASE_LOGIN_URL and who calls the hash lookup Co-Authored-By: Claude Opus 5.5 --- apps/api/src/auth/login-isolation.spec.ts | 18 ++++++++++ .../api/src/auth/login-prisma.service.spec.ts | 36 ++++++++++++++++--- apps/api/src/auth/login-prisma.service.ts | 29 +++++++++++++-- apps/api/src/auth/password.service.spec.ts | 7 ++++ apps/api/src/auth/password.service.ts | 13 +++++-- 5 files changed, 94 insertions(+), 9 deletions(-) diff --git a/apps/api/src/auth/login-isolation.spec.ts b/apps/api/src/auth/login-isolation.spec.ts index 9d1a1be..d92921c 100644 --- a/apps/api/src/auth/login-isolation.spec.ts +++ b/apps/api/src/auth/login-isolation.spec.ts @@ -21,8 +21,24 @@ const files = sources(SRC).map((full) => ({ const usesLoginClient = (code: string) => /login-prisma\.service/.test(code); const namesLookup = (code: string) => /\bauth_find_user_for_password_login\b/.test(code); +const namesLoginUrl = (code: string) => /\bDATABASE_LOGIN_URL\b/.test(code); +const usesLookup = (code: string) => /\bfindUserForPasswordLogin\b/.test(code); +const where = (test: (code: string) => boolean) => + files.filter((f) => test(f.code)).map((f) => f.rel); describe('the password login’s database login stays with the password login', () => { + it('only the env checks and LoginPrismaService read DATABASE_LOGIN_URL (no second client)', () => { + expect(where(namesLoginUrl)).toEqual([ + 'auth/login-prisma.service.ts', + 'config/env.ts', + 'config/production-env.ts', + ]); + }); + + it('only AuthService calls the hash lookup', () => { + expect(where(usesLookup)).toEqual(['auth/auth.service.ts', 'auth/login-lookup.ts']); + }); + it('only AuthService (and its module) use LoginPrismaService', () => { expect(files.filter((f) => usesLoginClient(f.code)).map((f) => f.rel)).toEqual([ 'auth/auth.module.ts', @@ -43,5 +59,7 @@ describe('the password login’s database login stays with the password login', ); expect(namesLookup('SELECT * FROM auth_find_user_for_password_login($1, $2)')).toBe(true); expect(namesLookup('SELECT * FROM auth_find_user_for_login($1, $2)')).toBe(false); + expect(namesLoginUrl("createPrismaClient(config.get('DATABASE_LOGIN_URL'))")).toBe(true); + expect(usesLookup('await findUserForPasswordLogin(client, { phone })')).toBe(true); }); }); diff --git a/apps/api/src/auth/login-prisma.service.spec.ts b/apps/api/src/auth/login-prisma.service.spec.ts index 2979d41..6910a02 100644 --- a/apps/api/src/auth/login-prisma.service.spec.ts +++ b/apps/api/src/auth/login-prisma.service.spec.ts @@ -18,18 +18,35 @@ const privilegeRow = (p: LoginPrivileges) => ({ can_become: p.canBecome, }); +/** Where a client is connected: its database, port and server start (one cluster, one start). */ +interface Where { + db: string; + port: number | null; + started: string; +} +const HERE: Where = { db: 'jantrik', port: 5432, started: '2026-11-16T06:00:00.000Z' }; + /** * A client whose privilege query answers `privileges` in turn (a row or a failure; the last one - * repeats) and whose role check (may it run the password lookup?) answers `ok` (or fails). + * repeats), whose role check (may it run the password lookup?) answers `ok` (or fails), and that + * says it is connected to `where`. */ -const client = (ok: boolean | Error, privileges: (LoginPrivileges | Error)[] = [SAFE]) => { +const client = ( + ok: boolean | Error, + privileges: (LoginPrivileges | Error)[] = [SAFE], + where: Where = HERE, +) => { let i = 0; return { $queryRaw: vi.fn((strings: TemplateStringsArray) => { - if (strings.join('').includes('pg_roles')) { + const sql = strings.join(''); + if (sql.includes('pg_roles')) { const p = privileges[Math.min(i++, privileges.length - 1)]!; return p instanceof Error ? Promise.reject(p) : Promise.resolve([privilegeRow(p)]); } + if (sql.includes('current_database')) { + return Promise.resolve([{ ...where, started: new Date(where.started) }]); + } return ok instanceof Error ? Promise.reject(ok) : Promise.resolve([{ ok }]); }), }; @@ -46,11 +63,12 @@ function service( loginCanRun: boolean | Error, mainCanRun: boolean | Error, privileges: (LoginPrivileges | Error)[] = [SAFE], + loginWhere: Where = HERE, ) { const warn = vi.fn(); const s = Object.create(LoginPrismaService.prototype) as LoginPrismaService; Object.assign(s, { - client: client(loginCanRun, privileges), + client: client(loginCanRun, privileges, loginWhere), main: { client: client(mainCanRun) }, logger: { warn, log: vi.fn() }, retryDelaysMs: [0, 0, 0], @@ -72,6 +90,16 @@ describe('LoginPrismaService startup check', () => { await expect(service(login, main).s.onModuleInit()).rejects.toThrow(/mixed up/); }); + it.each([ + ['another database', { ...HERE, db: 'jantrik_test' }], + ['another port', { ...HERE, port: 5433 }], + ['another server (started at another time)', { ...HERE, started: '2026-11-15T00:00:00.000Z' }], + ])('refuses to start when DATABASE_LOGIN_URL points at %s', async (_case, where) => { + await expect(service(true, false, [SAFE], where).s.onModuleInit()).rejects.toThrow( + /DATABASE_LOGIN_URL and DATABASE_URL must reach the same database/, + ); + }); + it('only warns when the role check itself fails after the privilege check passed', async () => { const { s, warn } = service(new Error('connect ECONNREFUSED'), false); await expect(s.onModuleInit()).resolves.toBeUndefined(); diff --git a/apps/api/src/auth/login-prisma.service.ts b/apps/api/src/auth/login-prisma.service.ts index 61b21fa..bf16540 100644 --- a/apps/api/src/auth/login-prisma.service.ts +++ b/apps/api/src/auth/login-prisma.service.ts @@ -46,8 +46,9 @@ export class LoginPrismaService implements OnModuleInit, OnModuleDestroy { * is asked again for about 3 minutes, then the start is refused. * * Then refuse to start when the URLs are mixed up (DATABASE_URL given the login login, or the - * other way round): the separation would silently disappear. An error in this second check only - * warns (the first has just shown the database answers); logins fail on their own then. + * other way round: the separation would silently disappear), or reach different databases (a + * password login against another database than the sessions it creates). An error in these + * checks only warns (the first has just shown the database answers); logins fail on their own. */ async onModuleInit(): Promise { await runStartupCheck({ @@ -73,10 +74,26 @@ export class LoginPrismaService implements OnModuleInit, OnModuleDestroy { 'public.auth_find_user_for_password_login(text, text)', 'EXECUTE') AS ok`.then( ([row]) => row?.ok === true, ); + // Where each login is connected: the database, the port and the server's start time (one + // cluster has one). Not the address: "localhost" may reach ::1 on one connection and + // 127.0.0.1 on the next. + const where = (client: PrismaClient) => + client.$queryRaw<{ db: string; port: number | null; started: Date }[]>` + SELECT current_database() AS db, inet_server_port() AS port, + pg_postmaster_start_time() AS started`.then(([row]) => + row ? `${row.db}:${row.port ?? 'socket'}:${new Date(row.started).toISOString()}` : '', + ); let login: boolean; let main: boolean; + let loginAt: string; + let mainAt: string; try { - [login, main] = await Promise.all([canRun(this.client), canRun(this.main.client)]); + [login, main, loginAt, mainAt] = await Promise.all([ + canRun(this.client), + canRun(this.main.client), + where(this.client), + where(this.main.client), + ]); } catch (error) { this.logger.warn(`Could not check the database roles: ${(error as Error).message}`); return; @@ -87,6 +104,12 @@ export class LoginPrismaService implements OnModuleInit, OnModuleDestroy { 'and DATABASE_URL the app login (jantrik_app). See docs/auth.md.', ); } + if (loginAt !== mainAt) { + throw new Error( + 'DATABASE_LOGIN_URL and DATABASE_URL must reach the same database on the same server ' + + `(${loginAt} and ${mainAt}). See docs/auth.md.`, + ); + } } async onModuleDestroy(): Promise { diff --git a/apps/api/src/auth/password.service.spec.ts b/apps/api/src/auth/password.service.spec.ts index 726e591..8ce3de0 100644 --- a/apps/api/src/auth/password.service.spec.ts +++ b/apps/api/src/auth/password.service.spec.ts @@ -40,12 +40,19 @@ describe('PasswordService.verify', () => { ['memory above 64 MiB', 'M_HIGH'], ['more than 10 passes', 'T_HIGH'], ['more than 4 lanes', 'P_HIGH'], + ['an output over 64 bytes', 'LONG_OUTPUT'], + ['a salt over 64 bytes', 'LONG_SALT'], + ['more than 255 characters', 'TOO_LONG'], ])('%s: refused after one full argon2 check against the dummy hash (P1-J4)', async (_, kind) => { + const salt = stored.split('$')[4]!; // 22 characters: 16 bytes const stored2 = { M_HIGH: stored.replace('m=19456', 'm=65537'), T_HIGH: stored.replace('t=2', 't=11'), P_HIGH: stored.replace('p=1', 'p=5'), + LONG_OUTPUT: `${stored}${'A'.repeat(85)}`, // a 128-character digest: 96 bytes + LONG_SALT: stored.replace(`$${salt}$`, `$${salt.repeat(4)}$`), // 88 characters: 66 bytes + TOO_LONG: `${stored}${'A'.repeat(200)}`, }[kind as string] ?? kind; expect(await service.verify(stored2, password)).toBe(false); // The time matches a real account's: one verification, at today's cost, never the stored one. diff --git a/apps/api/src/auth/password.service.ts b/apps/api/src/auth/password.service.ts index f425ad6..084cd80 100644 --- a/apps/api/src/auth/password.service.ts +++ b/apps/api/src/auth/password.service.ts @@ -12,14 +12,23 @@ const OPTIONS = { memoryCost: 19_456, timeCost: 2, parallelism: 1 }; */ const COST_CEILING = { memoryCost: 65_536, timeCost: 10, parallelism: 4 }; -/** Whether argon2 may verify against `stored` (readable, and within the cost ceiling). */ +/** + * Whether argon2 may verify against `stored`: readable, within the cost ceiling, and of a normal + * size (salt 8 to 64 bytes, output 16 to 64 bytes, at most 255 characters in all; Jantrik writes + * 16 and 32, about 100 characters). + */ function usableHash(stored: string): boolean { + if (stored.length > 255) return false; try { const o = parseOptions(stored); return ( o.memoryCost <= COST_CEILING.memoryCost && o.timeCost <= COST_CEILING.timeCost && - o.parallelism <= COST_CEILING.parallelism + o.parallelism <= COST_CEILING.parallelism && + o.saltLen >= 8 && + o.saltLen <= 64 && + o.outputLen >= 16 && + o.outputLen <= 64 ); } catch { return false; From ff673b8f2902493e7b0a7b0b1670a675e4e5194c Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 14:47:32 +0600 Subject: [PATCH 32/44] Docs after the second P1-J review: the server upgrade creates the role after the checkout and before migrate, with the recovery (migrate resolve --rolled-back); an injection can still take over an account through set_config (auth.md, database.md; P1-J8, not new, recorded for the owner); the email lookup's missing case-insensitive index (P1-J9); the worker also holds the login URL Co-Authored-By: Claude Opus 5.5 --- docs/auth.md | 18 +++++++--- docs/database.md | 7 ++-- docs/decisions-pending.md | 8 +++-- docs/deploy.md | 42 +++++++++++++++++------- docs/plans/sprint-1-p1j-password-hash.md | 6 ++++ 5 files changed, 60 insertions(+), 21 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index 852b9b1..af54c74 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -236,9 +236,13 @@ alone has its own database login: verifies with argon2 as before. - `jantrik_login_app` may run that one function and nothing else (no table, no other function), and `jantrik_app` may not run it. Only `AuthService` holds that client - (`login-isolation.spec.ts`). Its pool is small (4 connections). + (`login-isolation.spec.ts`). Its pool is small (4 connections). The queue worker builds the + same modules, so it gets `DATABASE_LOGIN_URL` and runs the start-up checks too, but never + looks a hash up; the receiver never gets it. - At start-up the API refuses a `DATABASE_LOGIN_URL` that is a superuser, has BYPASSRLS or can - become such a role (fail closed, like the other logins), and one mixed up with `DATABASE_URL`. + become such a role (fail closed, like the other logins), one mixed up with `DATABASE_URL`, and + one that reaches another database or server than `DATABASE_URL` (database, port and the + server's start time compared). - A stored hash above 64 MiB, 10 passes or 4 lanes, or one argon2 cannot read, counts as no password (the dummy check runs): a hash someone wrote into their own row cannot make each login attempt arbitrarily expensive. @@ -247,12 +251,16 @@ alone has its own database login: - It **cannot** read any password hash or salt: its own, a co-member's or a stranger's. - It **cannot** run the password lookup, or anything as `jantrik_login_app`: that login's - password is only in the API's environment. + password is only in the API's (and the worker's) environment, never in the database. - It **can** learn whether a given person has a password at all, yes or no: `auth_my_password_is_set()` (for `GET /me/password`) answers for `app.user_id`, which any SQL can set with `set_config`. It reveals nothing about the password itself. -- It can still set its own row's hash (the app login keeps UPDATE on the column, under RLS: its - own row only), as before. +- It **can still take over an account**, as before P1-J: the request's identity is + `app.user_id`, which any SQL can change with `set_config`. Set to someone else's id, the RLS + policies let it write that person's `password_hash` (then sign in with a password it chose) or + create a session for them. P1-J protects the password itself (people reuse passwords + elsewhere), not the account against an injection. Recorded for the owner: P1-J8 in + decisions-pending. The platform admins' login is separate and unchanged ([platform.md](platform.md)). diff --git a/docs/database.md b/docs/database.md index 5d0993d..8214a03 100644 --- a/docs/database.md +++ b/docs/database.md @@ -163,8 +163,11 @@ references such as `sections.shift_id`. A row can only point at rows of its own tenant A must not edit them. - **Only some columns (sprint 1 P1-B):** `jantrik_app` may update `locale`, `color_scheme`, `name_bn`, `password_hash`, `password_changed_at` and `updated_at`, and nothing else. The - login identifiers (`phone`, `email`) and the global `name` are out of the app's reach, so no - app code (or injection) can change how a person signs in. Tests that need another column set + login identifiers (`phone`, `email`) and the global `name` are out of the app's reach: no app + code (or injection) can change the phone or email a person signs in with. The password hash is + not: an injection can set `app.user_id` to anyone with `set_config` and then write their + `password_hash` (or create a session for them), which RLS allows for "your own row" + (P1-J8 in decisions-pending). Tests that need another column set it through the owner role, as that user. - **`password_changed_at`:** when the person last set their password themselves (null: never, or only by the seed). Written only by `PasswordSettingsService`, with `password_hash` diff --git a/docs/decisions-pending.md b/docs/decisions-pending.md index 2499b09..5564bbe 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -653,7 +653,7 @@ P1-I. **Open, for the owner: catch part of an institute's name too?** The rule r - To change: `passwordProblems` in `packages/shared/src/password.ts` (the server and the form share it). -P1-J. **Built (day run 2026-11-16), for the owner's review with its PR: no ordinary request can read a password hash.** Plan: [plans/sprint-1-p1j-password-hash.md](plans/sprint-1-p1j-password-hash.md), written and built while the owner was away, as asked, then changed after the database-security review (P1-J7). `jantrik_app` lost SELECT on `users.password_hash` (granted column by column; UPDATE kept), its login lookup returns no password data, and the password login looks the hash up on its own database login (`jantrik_login_app`, `DATABASE_LOGIN_URL`) through one function only that login may run. Every Prisma client omits the hash. **Setup on your machine:** create the role once (docs/database.md → Database roles, the `CREATE ROLE jantrik_login_app …` line) and add `DATABASE_LOGIN_URL` to `.env` (from `.env.example`). Decisions taken alone, each the safest option (P1-J1 to P1-J7): +P1-J. **Built (day run 2026-11-16), for the owner's review with its PR: no ordinary request can read a password hash.** Plan: [plans/sprint-1-p1j-password-hash.md](plans/sprint-1-p1j-password-hash.md), written and built while the owner was away, as asked, then changed after the database-security review (P1-J7). `jantrik_app` lost SELECT on `users.password_hash` (granted column by column; UPDATE kept), its login lookup returns no password data, and the password login looks the hash up on its own database login (`jantrik_login_app`, `DATABASE_LOGIN_URL`) through one function only that login may run. Every Prisma client omits the hash. **Setup on your machine, in this order:** create the role once (docs/database.md → Database roles, the `CREATE ROLE jantrik_login_app …` line), add `DATABASE_LOGIN_URL` to `.env` (from `.env.example`), then `pnpm db:migrate`. Decisions taken alone, each the safest option (P1-J1 to P1-J7): P1-J1. **The app's login lookup returned any user's hash, so it changed too.** `auth_find_user_for_login`, which `jantrik_app` may run, returned `password_hash` for any phone or email, whatever the institute: hiding the column alone would have closed nothing. It now returns id, name and locale only (the OTP login never needed more). @@ -667,6 +667,10 @@ P1-J5. **(Dropped after the review.)** The first version accepted only argon2id P1-J6. **Not changed: the platform admins' login** (`platform_find_admin_for_login` returns `platform_admins` hashes and TOTP secrets to `jantrik_platform_app`). It is a separate login with no tenant traffic; the same change can follow if you want it. -P1-J7. **Built after the review; you may drop these commits:** the first version kept the hash in the database and compared a digest there (`auth_my_password_matches`). The review showed that an injection could read any user's salt, set `app.user_id` to them and check 200,000 offline-computed guesses in one 6.4-second statement: close to reading the hash. Now a dedicated login, `jantrik_login_app`, is the only one that may run the hash lookup (`auth_find_user_for_password_login`); `jantrik_app` has neither the lookup nor any comparison function, and the API verifies with argon2 as before. It follows the platform and receiver logins: its own env URL (required, refused in production as the owner or superuser, never given to the receiver), its own small pool, the fail-closed privilege check and a mixed-up-URLs check at start-up, and the role in `01-roles.sh`, `create-roles.sh`, the production compose, CI, the restore check and the docs. **Upgrade gap:** between `migrate` and the restart, the old API fails whole-row reads of `users` (the refresh, `/auth/me`) and both logins; a failed refresh is retried and nobody is signed out (docs/deploy.md → Upgrades). +P1-J7. **Built after the review; you may drop these commits:** the first version kept the hash in the database and compared a digest there (`auth_my_password_matches`). The review showed that an injection could read any user's salt, set `app.user_id` to them and check 200,000 offline-computed guesses in one 6.4-second statement: close to reading the hash. Now a dedicated login, `jantrik_login_app`, is the only one that may run the hash lookup (`auth_find_user_for_password_login`); `jantrik_app` has neither the lookup nor any comparison function, and the API verifies with argon2 as before. It follows the platform and receiver logins: its own env URL (required, refused in production as the owner or superuser, never given to the receiver), its own small pool, the fail-closed privilege check and a mixed-up-URLs check at start-up, and the role in `01-roles.sh`, `create-roles.sh`, the production compose, CI, the restore check and the docs. **Upgrade:** the migration first checks that `jantrik_login_app` exists and refuses to run otherwise (Prisma does not run a migration in one transaction, so a failure half-way would leave the first statements applied); every statement can run again after `prisma migrate resolve --rolled-back`. On a server the role is created after the checkout and before `migrate` (docs/deploy.md → Upgrades). Between `migrate` and the restart, the old API fails whole-row reads of `users` (the refresh, `/auth/me`) and both logins; a failed refresh is retried and nobody is signed out. + +P1-J8. **Follow-up for the owner (not built, and not new): an SQL injection can still take over an account.** The request's identity is `app.user_id` (and `app.tenant_id`), set with `set_config`, which any SQL in the same transaction can change. Set to a victim's id, RLS lets it update the victim's `password_hash` (then sign in with a password it chose) or insert a session for them. P1-J stops reading hashes (it protects the password, which people reuse elsewhere), not this. Options, each a larger change: a verified context (e.g. the API signs the context and a definer function checks the signature before anything trusts it), or writes to `users.password_hash` and `sessions` only through definer functions that check a server-side secret or the session itself. Main has the same today. + +P1-J9. **Follow-up for the owner (not built): email login lookups are case-insensitive but not indexed.** Both login lookups compare `lower(u.email) = lower(p_email)`; `users_email_key` is case-sensitive, so that comparison scans the table (an unknown email takes longer as the table grows) and two emails differing only in case can coexist. The fix: check for such duplicates first, then a unique index on `lower(email)` (and drop the old one). Not in this PR, because existing data could hold duplicates. P1-K. **Fixed from the review** (each with a test that failed first): a code is single use even when two requests race with it (login codes too); the phone rule ignores every punctuation mark and symbol between the digits; the other sessions are revoked in one statement; the common-password list is read at start-up; password login accepts up to 512 code points (a 128-character password typed decomposed); the wrong-code message asks to check the code before sending a new one. Kept as they are: the staff check after a correct password costs one extra query (it only confirms a password the caller already has); the login page's hint sits under the password tab, which guardians do not use. diff --git a/docs/deploy.md b/docs/deploy.md index 8b22143..9f795cd 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -354,18 +354,36 @@ deploy/compose.sh ps `ALTER ROLE jantrik_ingest_app SET statement_timeout = '5s';` 3. upgrade as above (`up -d` restarts Redis with the new user), then run the Redis check (§ 10a). -- **A server set up before sprint 1's P1-J** (the password login's own database login): - 1. add `DB_LOGIN_PASSWORD` (`openssl rand -hex 24`, different from every other password) to - the settings file (`DATABASE_LOGIN_URL` needs nothing: the compose file builds it); - 2. create the role **before** the migration (the migration grants to it): recreate the - Postgres container so it gets the new password (`deploy/compose.sh up -d postgres`; the data - stays), then run the roles script again, which creates only what is missing - (`deploy/compose.sh exec -u postgres postgres sh /jantrik/postgres/create-roles.sh`); - 3. upgrade as above. **Between `migrate` and `up -d`**, the old API still running fails: every - whole-row read of `users` (the session refresh, `/auth/me`) and both logins (its login - lookup asks for a column the function no longer returns), until it restarts. Nothing is - lost: a refresh that fails is retried by the browser, and nobody is signed out. Keep the - gap short (run the two commands together). +- **A server set up before sprint 1's P1-J** (the password login's own database login, + `jantrik_login_app`). Its migration refuses to run until the role exists, and the role script + that creates it is the **new** one, so the order matters: + + ```bash + cd /srv/jantrik + deploy/compose.sh run --rm backup # a backup first + git fetch && git checkout # the new create-roles.sh and compose file + nano deploy/.env.prod # add DB_LOGIN_PASSWORD (openssl rand -hex 24, + # unlike every other password) + deploy/compose.sh up -d postgres # Postgres gets the new password; data stays + deploy/compose.sh exec -u postgres postgres sh /jantrik/postgres/create-roles.sh + # creates only what is missing + deploy/compose.sh build + deploy/compose.sh run --rm migrate + deploy/compose.sh up -d + ``` + + - `DATABASE_LOGIN_URL` needs nothing: the compose file builds it from `DB_LOGIN_PASSWORD`. + - **If `migrate` stopped with "create the role jantrik_login_app first"**, nothing was changed: + create the role as above, mark the migration rolled back, and run it again: + `deploy/compose.sh run --rm migrate node_modules/.bin/prisma migrate resolve --rolled-back 20261116000000_users_password_hash_hidden`, + then `deploy/compose.sh run --rm migrate`. (On a development machine: + `pnpm --filter @jantrik/db exec prisma migrate resolve --rolled-back 20261116000000_users_password_hash_hidden`, + then `pnpm db:deploy`.) Every statement of that migration can run again, so the same + recovery works after a failure half-way. + - **Between `migrate` and `up -d`** the old API still running fails every whole-row read of + `users` (the session refresh, `/auth/me`) and both logins (its lookup asks for a column the + function no longer returns), until it restarts. Nothing is lost: a refresh that fails is + retried by the browser, and nobody is signed out. Run the last two commands together. ## 12. Backups diff --git a/docs/plans/sprint-1-p1j-password-hash.md b/docs/plans/sprint-1-p1j-password-hash.md index a719a41..1e36112 100644 --- a/docs/plans/sprint-1-p1j-password-hash.md +++ b/docs/plans/sprint-1-p1j-password-hash.md @@ -40,6 +40,12 @@ instead, and what this plan's sections below describe only where they say so: role once (database.md → Database roles) and add `DATABASE_LOGIN_URL` to `.env`. On an existing server: deploy.md → Upgrades (create the role before the migration; the old API fails some reads between migrate and restart). +- **Second review round:** the migration checks for the role before it changes anything and every + statement can run again (a DB test runs it twice); the role step on a server comes after the + checkout; a view guard; the login client must reach the same database and server as the app + client; stored hashes bounded in size; `create-roles.sh` run twice in CI; and two follow-ups + recorded for the owner: an injection can still take over an account through `set_config` + (P1-J8, not new), and the email lookup has no case-insensitive index (P1-J9). **Goal:** an SQL injection in any institute request (which runs as `jantrik_app`) can no longer read a staff member's argon2 password hash, neither of co-members nor of anyone else. Everything From 13deed23539dc5497b55ec325dfc842d05fa7909 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 15:05:43 +0600 Subject: [PATCH 33/44] A file reference is tied to its kind (review R6): UNIQUE (tenant_id, id, kind) on stored_files and a fixed kind column in each foreign key (students.photo_file_kind always STUDENT_PHOTO; the profile's logo, signature and seal kinds), so a photo column can only hold a photo; the database tests name the rule that refuses each write (R10) Co-Authored-By: Claude Opus 5.5 --- .../migration.sql | 23 ++- .../migration.sql | 16 +- packages/db/prisma/schema.prisma | 99 ++++----- packages/db/test/files-rls.test.ts | 189 +++++++++++------- 4 files changed, 198 insertions(+), 129 deletions(-) diff --git a/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql b/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql index 096b76c..f4f25d7 100644 --- a/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql +++ b/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql @@ -54,6 +54,9 @@ CREATE TABLE "institute_profiles" ( "logo_file_id" UUID, "head_signature_file_id" UUID, "seal_file_id" UUID, + "logo_file_kind" "stored_file_kind" NOT NULL DEFAULT 'LOGO', + "head_signature_file_kind" "stored_file_kind" NOT NULL DEFAULT 'SIGNATURE', + "seal_file_kind" "stored_file_kind" NOT NULL DEFAULT 'SEAL', "created_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, "updated_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, @@ -66,6 +69,9 @@ CREATE INDEX "stored_files_tenant_id_kind_idx" ON "stored_files"("tenant_id", "k -- CreateIndex CREATE UNIQUE INDEX "stored_files_tenant_id_id_key" ON "stored_files"("tenant_id", "id"); +-- CreateIndex (what the kind-bound foreign keys point at) +CREATE UNIQUE INDEX "stored_files_tenant_id_id_kind_key" ON "stored_files"("tenant_id", "id", "kind"); + -- CreateIndex CREATE UNIQUE INDEX "stored_file_usage_tenant_id_key" ON "stored_file_usage"("tenant_id"); @@ -79,13 +85,13 @@ CREATE UNIQUE INDEX "institute_profiles_tenant_id_key" ON "institute_profiles"(" CREATE UNIQUE INDEX "institute_profiles_tenant_id_id_key" ON "institute_profiles"("tenant_id", "id"); -- CreateIndex -CREATE UNIQUE INDEX "institute_profiles_tenant_id_logo_file_id_key" ON "institute_profiles"("tenant_id", "logo_file_id"); +CREATE UNIQUE INDEX "institute_profiles_tenant_id_logo_file_id_logo_file_kind_key" ON "institute_profiles"("tenant_id", "logo_file_id", "logo_file_kind"); -- CreateIndex -CREATE UNIQUE INDEX "institute_profiles_tenant_id_head_signature_file_id_key" ON "institute_profiles"("tenant_id", "head_signature_file_id"); +CREATE UNIQUE INDEX "institute_profiles_tenant_id_head_signature_file_id_head_si_key" ON "institute_profiles"("tenant_id", "head_signature_file_id", "head_signature_file_kind"); -- CreateIndex -CREATE UNIQUE INDEX "institute_profiles_tenant_id_seal_file_id_key" ON "institute_profiles"("tenant_id", "seal_file_id"); +CREATE UNIQUE INDEX "institute_profiles_tenant_id_seal_file_id_seal_file_kind_key" ON "institute_profiles"("tenant_id", "seal_file_id", "seal_file_kind"); -- AddForeignKey ALTER TABLE "stored_files" ADD CONSTRAINT "stored_files_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT ON UPDATE RESTRICT; @@ -100,13 +106,13 @@ ALTER TABLE "stored_file_usage" ADD CONSTRAINT "stored_file_usage_tenant_id_fkey ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT ON UPDATE RESTRICT; -- AddForeignKey -ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_logo_file_id_fkey" FOREIGN KEY ("tenant_id", "logo_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_logo_file_id_logo_file_kind_fkey" FOREIGN KEY ("tenant_id", "logo_file_id", "logo_file_kind") REFERENCES "stored_files"("tenant_id", "id", "kind") ON DELETE RESTRICT ON UPDATE RESTRICT; -- AddForeignKey -ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_head_signature_file_id_fkey" FOREIGN KEY ("tenant_id", "head_signature_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_head_signature_file_id_head_s_fkey" FOREIGN KEY ("tenant_id", "head_signature_file_id", "head_signature_file_kind") REFERENCES "stored_files"("tenant_id", "id", "kind") ON DELETE RESTRICT ON UPDATE RESTRICT; -- AddForeignKey -ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_seal_file_id_fkey" FOREIGN KEY ("tenant_id", "seal_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE "institute_profiles" ADD CONSTRAINT "institute_profiles_tenant_id_seal_file_id_seal_file_kind_fkey" FOREIGN KEY ("tenant_id", "seal_file_id", "seal_file_kind") REFERENCES "stored_files"("tenant_id", "id", "kind") ON DELETE RESTRICT ON UPDATE RESTRICT; -- Row-Level Security (docs/database.md → Checklist). ALTER TABLE stored_files ENABLE ROW LEVEL SECURITY; @@ -182,6 +188,11 @@ ALTER TABLE institute_profiles ADD CONSTRAINT institute_profiles_established_year CHECK ( established_year IS NULL OR established_year BETWEEN 1800 AND 2100 ), + -- Each image column's kind is fixed; with the kind in each foreign key, a logo can only be a LOGO + -- file, the signature a SIGNATURE, the seal a SEAL (so never a student's photo). + ADD CONSTRAINT institute_profiles_file_kinds CHECK ( + logo_file_kind = 'LOGO' AND head_signature_file_kind = 'SIGNATURE' AND seal_file_kind = 'SEAL' + ), -- One file in one place: the unique indexes cover each column; this covers the row's three. ADD CONSTRAINT institute_profiles_distinct_files CHECK ( (logo_file_id IS NULL OR (logo_file_id IS DISTINCT FROM head_signature_file_id diff --git a/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql b/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql index f09501a..7894ee2 100644 --- a/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql +++ b/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql @@ -1,13 +1,17 @@ --- Sprint 1 P2: a student's photo is a stored file (kind STUDENT_PHOTO), referenced by a composite --- key so it can only be a file of the student's own institute. The old photo_url column was never --- written (always null) and goes. +-- Sprint 1 P2: a student's photo is a stored file of kind STUDENT_PHOTO, referenced by a composite +-- key with the kind (fixed by a CHECK), so it can only be a photo of the student's own institute. +-- The old photo_url column was never written (always null) and goes. -- AlterTable ALTER TABLE "students" DROP COLUMN "photo_url", -ADD COLUMN "photo_file_id" UUID; +ADD COLUMN "photo_file_id" UUID, +ADD COLUMN "photo_file_kind" "stored_file_kind" NOT NULL DEFAULT 'STUDENT_PHOTO'; + +ALTER TABLE students + ADD CONSTRAINT students_photo_file_kind CHECK (photo_file_kind = 'STUDENT_PHOTO'); -- CreateIndex (also the foreign key's index: a file belongs to one student) -CREATE UNIQUE INDEX "students_tenant_id_photo_file_id_key" ON "students"("tenant_id", "photo_file_id"); +CREATE UNIQUE INDEX "students_tenant_id_photo_file_id_photo_file_kind_key" ON "students"("tenant_id", "photo_file_id", "photo_file_kind"); -- AddForeignKey -ALTER TABLE "students" ADD CONSTRAINT "students_tenant_id_photo_file_id_fkey" FOREIGN KEY ("tenant_id", "photo_file_id") REFERENCES "stored_files"("tenant_id", "id") ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE "students" ADD CONSTRAINT "students_tenant_id_photo_file_id_photo_file_kind_fkey" FOREIGN KEY ("tenant_id", "photo_file_id", "photo_file_kind") REFERENCES "stored_files"("tenant_id", "id", "kind") ON DELETE RESTRICT ON UPDATE RESTRICT; diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma index 02dda1e..7aa3291 100644 --- a/packages/db/prisma/schema.prisma +++ b/packages/db/prisma/schema.prisma @@ -1002,36 +1002,38 @@ model Membership { } model Student { - id String @id @default(uuid(7)) @db.Uuid - tenantId String @map("tenant_id") @db.Uuid - studentCode String @map("student_code") - userId String? @map("user_id") @db.Uuid - nameBn String? @map("name_bn") - nameEn String? @map("name_en") - dateOfBirth DateTime? @map("date_of_birth") @db.Date + id String @id @default(uuid(7)) @db.Uuid + tenantId String @map("tenant_id") @db.Uuid + studentCode String @map("student_code") + userId String? @map("user_id") @db.Uuid + nameBn String? @map("name_bn") + nameEn String? @map("name_en") + dateOfBirth DateTime? @map("date_of_birth") @db.Date gender Gender? /// The student's photo (stored_files, kind STUDENT_PHOTO); replaced files are deleted. - photoFileId String? @map("photo_file_id") @db.Uuid - status StudentStatus @default(ACTIVE) + photoFileId String? @map("photo_file_id") @db.Uuid + /// Always STUDENT_PHOTO (CHECK): part of the foreign key, so the photo can only be a photo. + photoFileKind StoredFileKind @default(STUDENT_PHOTO) @map("photo_file_kind") + status StudentStatus @default(ACTIVE) // Fields required for Bangladesh education board registration. - fatherNameBn String? @map("father_name_bn") - fatherNameEn String? @map("father_name_en") - motherNameBn String? @map("mother_name_bn") - motherNameEn String? @map("mother_name_en") + fatherNameBn String? @map("father_name_bn") + fatherNameEn String? @map("father_name_en") + motherNameBn String? @map("mother_name_bn") + motherNameEn String? @map("mother_name_en") religion Religion? /// 17-digit birth registration number; unique per tenant when present. - birthRegistrationNo String? @map("birth_registration_no") - bloodGroup BloodGroup? @map("blood_group") - presentAddress String? @map("present_address") - permanentAddress String? @map("permanent_address") + birthRegistrationNo String? @map("birth_registration_no") + bloodGroup BloodGroup? @map("blood_group") + presentAddress String? @map("present_address") + permanentAddress String? @map("permanent_address") /// Soft delete. Queries must filter `deletedAt: null` themselves. - deletedAt DateTime? @map("deleted_at") @db.Timestamptz(3) - createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) - updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) + deletedAt DateTime? @map("deleted_at") @db.Timestamptz(3) + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict) user User? @relation(fields: [userId], references: [id], onDelete: SetNull) - photoFile StoredFile? @relation("StudentPhoto", fields: [tenantId, photoFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) + photoFile StoredFile? @relation("StudentPhoto", fields: [tenantId, photoFileId, photoFileKind], references: [tenantId, id, kind], onDelete: Restrict, onUpdate: Restrict) guardians StudentGuardian[] enrolments Enrolment[] @@ -1051,7 +1053,7 @@ model Student { @@unique([tenantId, studentCode]) @@unique([tenantId, birthRegistrationNo]) // A file belongs to one student (also the foreign key's index). - @@unique([tenantId, photoFileId]) + @@unique([tenantId, photoFileId, photoFileKind]) @@index([tenantId, status], where: raw("deleted_at IS NULL")) @@index([tenantId, nameEn]) // Trigram indexes for ILIKE '%…%' search (GET /students). @@ -3165,6 +3167,8 @@ model StoredFile { profileSeal InstituteProfile? @relation("InstituteProfileSeal") @@unique([tenantId, id]) + // What the kind-bound foreign keys point at. + @@unique([tenantId, id, kind]) @@index([tenantId, kind]) @@map("stored_files") } @@ -3188,39 +3192,44 @@ model StoredFileUsage { /// The institute's own profile (at most one per institute, created on the first save or image). /// tenants.name stays the name the platform registered; these are the institute's own words. model InstituteProfile { - id String @id @default(uuid(7)) @db.Uuid - tenantId String @unique @map("tenant_id") @db.Uuid - nameBn String? @map("name_bn") - nameEn String? @map("name_en") - shortName String? @map("short_name") + id String @id @default(uuid(7)) @db.Uuid + tenantId String @unique @map("tenant_id") @db.Uuid + nameBn String? @map("name_bn") + nameEn String? @map("name_en") + shortName String? @map("short_name") /// BANBEIS EIIN: 6 ASCII digits. eiin String? - addressBn String? @map("address_bn") - addressEn String? @map("address_en") + addressBn String? @map("address_bn") + addressEn String? @map("address_en") /// 5-15 ASCII digits with an optional leading + (a Bangladeshi mobile is stored as E.164). phone String? email String? website String? - headTitleBn String? @map("head_title_bn") - headTitleEn String? @map("head_title_en") - headNameBn String? @map("head_name_bn") - headNameEn String? @map("head_name_en") - establishedYear Int? @map("established_year") @db.SmallInt - logoFileId String? @map("logo_file_id") @db.Uuid - headSignatureFileId String? @map("head_signature_file_id") @db.Uuid - sealFileId String? @map("seal_file_id") @db.Uuid - createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) - updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) + headTitleBn String? @map("head_title_bn") + headTitleEn String? @map("head_title_en") + headNameBn String? @map("head_name_bn") + headNameEn String? @map("head_name_en") + establishedYear Int? @map("established_year") @db.SmallInt + logoFileId String? @map("logo_file_id") @db.Uuid + headSignatureFileId String? @map("head_signature_file_id") @db.Uuid + sealFileId String? @map("seal_file_id") @db.Uuid + /// Fixed kinds (CHECK institute_profiles_file_kinds), part of each image's foreign key, so a + /// logo is a LOGO file, the signature a SIGNATURE and the seal a SEAL. + logoFileKind StoredFileKind @default(LOGO) @map("logo_file_kind") + signatureFileKind StoredFileKind @default(SIGNATURE) @map("head_signature_file_kind") + sealFileKind StoredFileKind @default(SEAL) @map("seal_file_kind") + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3) tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Restrict, onUpdate: Restrict) - logoFile StoredFile? @relation("InstituteProfileLogo", fields: [tenantId, logoFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) - signatureFile StoredFile? @relation("InstituteProfileSignature", fields: [tenantId, headSignatureFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) - sealFile StoredFile? @relation("InstituteProfileSeal", fields: [tenantId, sealFileId], references: [tenantId, id], onDelete: Restrict, onUpdate: Restrict) + logoFile StoredFile? @relation("InstituteProfileLogo", fields: [tenantId, logoFileId, logoFileKind], references: [tenantId, id, kind], onDelete: Restrict, onUpdate: Restrict) + signatureFile StoredFile? @relation("InstituteProfileSignature", fields: [tenantId, headSignatureFileId, signatureFileKind], references: [tenantId, id, kind], onDelete: Restrict, onUpdate: Restrict) + sealFile StoredFile? @relation("InstituteProfileSeal", fields: [tenantId, sealFileId, sealFileKind], references: [tenantId, id, kind], onDelete: Restrict, onUpdate: Restrict) @@unique([tenantId, id]) // One file is used in one place (also each foreign key's index). - @@unique([tenantId, logoFileId]) - @@unique([tenantId, headSignatureFileId]) - @@unique([tenantId, sealFileId]) + @@unique([tenantId, logoFileId, logoFileKind]) + @@unique([tenantId, headSignatureFileId, signatureFileKind]) + @@unique([tenantId, sealFileId, sealFileKind]) @@map("institute_profiles") } diff --git a/packages/db/test/files-rls.test.ts b/packages/db/test/files-rls.test.ts index 22487bd..dc9ae1c 100644 --- a/packages/db/test/files-rls.test.ts +++ b/packages/db/test/files-rls.test.ts @@ -6,10 +6,15 @@ import { appClient, createStudent, createTenant } from './helpers.js'; // Sprint 1 P2 (docs/plans/sprint-1-p2-files.md): stored_files, stored_file_usage, // institute_profiles and students.photo_file_id. Tenant isolation, the grants (no UPDATE of a // file, no DELETE of usage or profile), the CHECKs that back the per-kind caps, and the composite -// foreign keys that keep a row from pointing at another institute's file. +// foreign keys that keep a row from pointing at another institute's file, or at a file of another +// kind. Each refusal names the rule that refused it. type Mime = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/gif' | 'text/plain'; +/** What refuses a write: a CHECK or foreign key by name, or RLS, or a unique index. */ +const RLS = /row-level security/; +const UNIQUE = /Unique constraint/; + function fileData( tenantId: string, kind: StoredFileKind, @@ -71,7 +76,7 @@ describe('files and the institute profile (P2)', () => { select: { id: true }, }), ), - ).rejects.toThrow(); + ).rejects.toThrow(RLS); const mine = await withTenant(app, a, (tx) => tx.storedFile.findUniqueOrThrow({ where: { id: aFile }, select: { sizeBytes: true } }), ); @@ -84,28 +89,63 @@ describe('files and the institute profile (P2)', () => { ).rejects.toThrow(/permission denied/); }); - it.each<[string, StoredFileKind, Mime, number, Parameters[4]]>([ - ['an unknown mime', 'DOCUMENT_ASSET', 'text/plain', 10, {}], - ['a GIF', 'DOCUMENT_ASSET', 'image/gif', 10, {}], - ['a PNG photo', 'STUDENT_PHOTO', 'image/png', 10, {}], - ['a JPEG signature', 'SIGNATURE', 'image/jpeg', 10, {}], - ['a JPEG logo', 'LOGO', 'image/jpeg', 10, {}], - ['a photo over 200 KB', 'STUDENT_PHOTO', 'image/jpeg', 204_801, {}], - ['an applicant photo over 200 KB', 'APPLICANT_PHOTO', 'image/jpeg', 204_801, {}], - ['a logo over 100 KB', 'LOGO', 'image/png', 102_401, {}], - ['a seal over 100 KB', 'SEAL', 'image/webp', 102_401, {}], - ['a signature over 100 KB', 'SIGNATURE', 'image/png', 102_401, {}], - ['a document asset over 256 KB', 'DOCUMENT_ASSET', 'image/png', 262_145, {}], - ['a size that is not the bytes’ length', 'STUDENT_PHOTO', 'image/jpeg', 10, { sizeBytes: 9 }], - ['a malformed sha256', 'STUDENT_PHOTO', 'image/jpeg', 10, { sha256: 'ABC' }], - ['width 0', 'STUDENT_PHOTO', 'image/jpeg', 10, { width: 0 }], - ['height over 4000', 'STUDENT_PHOTO', 'image/jpeg', 10, { height: 4001 }], - ])('refuses %s', async (_name, kind, mime, size, over) => { + it.each<[string, StoredFileKind, Mime, number, Parameters[4], string]>([ + ['an unknown mime', 'DOCUMENT_ASSET', 'text/plain', 10, {}, 'stored_files_mime'], + ['a GIF', 'DOCUMENT_ASSET', 'image/gif', 10, {}, 'stored_files_mime'], + ['a PNG photo', 'STUDENT_PHOTO', 'image/png', 10, {}, 'stored_files_mime'], + ['a JPEG signature', 'SIGNATURE', 'image/jpeg', 10, {}, 'stored_files_mime'], + ['a JPEG logo', 'LOGO', 'image/jpeg', 10, {}, 'stored_files_mime'], + ['a photo over 200 KB', 'STUDENT_PHOTO', 'image/jpeg', 204_801, {}, 'stored_files_size'], + [ + 'an applicant photo over 200 KB', + 'APPLICANT_PHOTO', + 'image/jpeg', + 204_801, + {}, + 'stored_files_size', + ], + ['a logo over 100 KB', 'LOGO', 'image/png', 102_401, {}, 'stored_files_size'], + ['a seal over 100 KB', 'SEAL', 'image/webp', 102_401, {}, 'stored_files_size'], + ['a signature over 100 KB', 'SIGNATURE', 'image/png', 102_401, {}, 'stored_files_size'], + [ + 'a document asset over 256 KB', + 'DOCUMENT_ASSET', + 'image/png', + 262_145, + {}, + 'stored_files_size', + ], + [ + 'a size that is not the bytes’ length', + 'STUDENT_PHOTO', + 'image/jpeg', + 10, + { sizeBytes: 9 }, + 'stored_files_size', + ], + [ + 'a malformed sha256', + 'STUDENT_PHOTO', + 'image/jpeg', + 10, + { sha256: 'ABC' }, + 'stored_files_sha256', + ], + ['width 0', 'STUDENT_PHOTO', 'image/jpeg', 10, { width: 0 }, 'stored_files_dimensions'], + [ + 'height over 4000', + 'STUDENT_PHOTO', + 'image/jpeg', + 10, + { height: 4001 }, + 'stored_files_dimensions', + ], + ])('refuses %s', async (_name, kind, mime, size, over, rule) => { await expect( withTenant(app, a, (tx) => tx.storedFile.create({ data: fileData(a, kind, mime, size, over), select: { id: true } }), ), - ).rejects.toThrow(); + ).rejects.toThrow(rule); }); it.each<[StoredFileKind, Mime, number]>([ @@ -132,16 +172,15 @@ describe('files and the institute profile (P2)', () => { }); await expect( withTenant(app, b, (tx) => tx.storedFileUsage.create({ data: { tenantId: a } })), - ).rejects.toThrow(); + ).rejects.toThrow(RLS); await expect( withTenant(app, a, (tx) => tx.$executeRaw`DELETE FROM stored_file_usage`), ).rejects.toThrow(/permission denied/); - await expect( - withTenant(app, a, (tx) => tx.storedFileUsage.updateMany({ data: { bytesUsed: -1 } })), - ).rejects.toThrow(); - await expect( - withTenant(app, a, (tx) => tx.storedFileUsage.updateMany({ data: { fileCount: -1 } })), - ).rejects.toThrow(); + for (const data of [{ bytesUsed: -1 }, { fileCount: -1 }]) { + await expect( + withTenant(app, a, (tx) => tx.storedFileUsage.updateMany({ data })), + ).rejects.toThrow('stored_file_usage_non_negative'); + } }); }); @@ -164,7 +203,7 @@ describe('files and the institute profile (P2)', () => { withTenant(app, b, (tx) => tx.instituteProfile.create({ data: { tenantId: c, nameEn: 'C' } }), ), - ).rejects.toThrow(); + ).rejects.toThrow(RLS); }); it('one per institute, never deleted', async () => { @@ -172,26 +211,32 @@ describe('files and the institute profile (P2)', () => { withTenant(app, a, (tx) => tx.instituteProfile.create({ data: { tenantId: a, nameEn: 'Again' } }), ), - ).rejects.toThrow(); + ).rejects.toThrow(UNIQUE); await expect( withTenant(app, a, (tx) => tx.$executeRaw`DELETE FROM institute_profiles`), ).rejects.toThrow(/permission denied/); }); it.each([ - ['no name', { nameBn: null, nameEn: null }], - ['a 5-digit EIIN', { eiin: '12345' }], - ['letters in the EIIN', { eiin: '12345a' }], - ['letters in the phone', { phone: 'abc12345' }], - ['a 4-digit phone', { phone: '1234' }], - ['an e-mail without a domain', { email: 'x@' }], - ['an ftp website', { website: 'ftp://example.com' }], - ['year 1700', { establishedYear: 1700 }], - ['a 31-character short name', { shortName: 'x'.repeat(31) }], - ])('refuses %s', async (_name, data) => { + ['no name', { nameBn: null, nameEn: null }, 'institute_profiles_name'], + ['a 5-digit EIIN', { eiin: '12345' }, 'institute_profiles_eiin'], + ['letters in the EIIN', { eiin: '12345a' }, 'institute_profiles_eiin'], + ['letters in the phone', { phone: 'abc12345' }, 'institute_profiles_phone'], + ['a 4-digit phone', { phone: '1234' }, 'institute_profiles_phone'], + ['an e-mail without a domain', { email: 'x@' }, 'institute_profiles_email'], + ['an ftp website', { website: 'ftp://example.com' }, 'institute_profiles_website'], + ['an upper-case scheme', { website: 'HTTPS://example.com' }, 'institute_profiles_website'], + ['year 1700', { establishedYear: 1700 }, 'institute_profiles_established_year'], + ['a 31-character short name', { shortName: 'x'.repeat(31) }, 'institute_profiles_lengths'], + [ + 'another kind in a kind column', + { logoFileKind: 'SEAL' as const }, + 'institute_profiles_file_kinds', + ], + ])('refuses %s', async (_name, data, rule) => { await expect( withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data })), - ).rejects.toThrow(); + ).rejects.toThrow(rule); }); it('accepts a full, valid profile', async () => { @@ -213,12 +258,22 @@ describe('files and the institute profile (P2)', () => { expect(n.count).toBe(1); }); - it("cannot point at another institute's file; a file in use cannot be deleted", async () => { + it("cannot point at another institute's file or another kind; a file in use cannot be deleted", async () => { const bLogo = await putFile(b, 'LOGO', 'image/png', 100); await expect( withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { logoFileId: bLogo } })), - ).rejects.toThrow(); + ).rejects.toThrow('institute_profiles_tenant_id_logo_file_id_logo_file_kind_fkey'); + // A photo is not a logo, and a logo is not a seal. + const aPhoto = await putFile(a, 'STUDENT_PHOTO', 'image/jpeg', 100); + await expect( + withTenant(app, a, (tx) => + tx.instituteProfile.updateMany({ data: { logoFileId: aPhoto } }), + ), + ).rejects.toThrow('institute_profiles_tenant_id_logo_file_id_logo_file_kind_fkey'); const aLogo = await putFile(a, 'LOGO', 'image/png', 100); + await expect( + withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { sealFileId: aLogo } })), + ).rejects.toThrow('institute_profiles_tenant_id_seal_file_id_seal_file_kind_fkey'); await withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { logoFileId: aLogo } }), ); @@ -226,57 +281,47 @@ describe('files and the institute profile (P2)', () => { withTenant(app, a, (tx) => tx.storedFile.delete({ where: { id: aLogo }, select: { id: true } }), ), - ).rejects.toThrow(); - // One file is used in one place only. - await expect( - withTenant(app, a, (tx) => tx.instituteProfile.updateMany({ data: { sealFileId: aLogo } })), - ).rejects.toThrow(); + ).rejects.toThrow('institute_profiles_tenant_id_logo_file_id_logo_file_kind_fkey'); }); }); describe('students.photo_file_id', () => { - it("cannot point at another institute's file, and two students cannot share one", async () => { + it("cannot point at another institute's file or a logo; two students cannot share one", async () => { const { student } = await createStudent(app, a, 'P-1'); const { student: other } = await createStudent(app, a, 'P-2'); - const bPhoto = await putFile(b); + const setPhoto = (id: string, photoFileId: string) => + withTenant(app, a, (tx) => + tx.student.update({ where: { id }, data: { photoFileId }, select: { id: true } }), + ); + const FK = 'students_tenant_id_photo_file_id_photo_file_kind_fkey'; + await expect(setPhoto(student.id, await putFile(b))).rejects.toThrow(FK); + await expect( + setPhoto(student.id, await putFile(a, 'LOGO', 'image/png', 100)), + ).rejects.toThrow(FK); + const photo = await putFile(a); + await setPhoto(student.id, photo); + await expect(setPhoto(other.id, photo)).rejects.toThrow(UNIQUE); await expect( withTenant(app, a, (tx) => - tx.student.update({ - where: { id: student.id }, - data: { photoFileId: bPhoto }, - select: { id: true }, - }), + tx.storedFile.delete({ where: { id: photo }, select: { id: true } }), ), - ).rejects.toThrow(); - const photo = await putFile(a); - await withTenant(app, a, (tx) => - tx.student.update({ - where: { id: student.id }, - data: { photoFileId: photo }, - select: { id: true }, - }), - ); + ).rejects.toThrow(FK); await expect( withTenant(app, a, (tx) => tx.student.update({ - where: { id: other.id }, - data: { photoFileId: photo }, + where: { id: student.id }, + data: { photoFileKind: 'LOGO' }, select: { id: true }, }), ), - ).rejects.toThrow(); - await expect( - withTenant(app, a, (tx) => - tx.storedFile.delete({ where: { id: photo }, select: { id: true } }), - ), - ).rejects.toThrow(); + ).rejects.toThrow('students_photo_file_kind'); }); it('students.photo_url is gone (never written; replaced by photo_file_id)', async () => { const cols = await app.$queryRaw<{ column_name: string }[]>` SELECT column_name FROM information_schema.columns WHERE table_name = 'students' AND column_name LIKE 'photo%' ORDER BY 1`; - expect(cols.map((c) => c.column_name)).toEqual(['photo_file_id']); + expect(cols.map((c) => c.column_name)).toEqual(['photo_file_id', 'photo_file_kind']); }); }); }); From cb86722ba61206d77ea1849b424cc75479a05874 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 15:05:43 +0600 Subject: [PATCH 34/44] Uploads hold no database connection while they arrive (review R1): the upload routes are @OwnTransaction, so the body is read and the image decoded first and RequestTransaction.run (the interceptor's logic, now a service) opens the same tenant transaction only for the short store; the image queue is bounded (503 IMAGE_BUSY) and hands a freed slot straight to the next waiter (R5); a replacement near the cap counts the file it replaces (R7); the first image and the first save cannot collide (R8); the code scan catches relation fields (R2); the web address's scheme is stored in lower case (R4). Each with a test that failed first Co-Authored-By: Claude Opus 5.5 --- apps/api/src/common/decorators.ts | 9 +++ apps/api/src/files/file-store-access.spec.ts | 31 ++++++++- apps/api/src/files/file-store.ts | 8 ++- apps/api/src/files/files.module.ts | 20 ++++-- apps/api/src/files/image.service.spec.ts | 55 ++++++++++++++- apps/api/src/files/image.service.ts | 51 ++++++++++++-- apps/api/src/files/postgres-file-store.ts | 12 +++- .../src/institute/institute-profile.module.ts | 69 ++++++++++++------- .../api/src/students/student-photo.service.ts | 33 ++++++--- apps/api/src/students/students.module.ts | 3 +- .../tenancy/request-transaction.service.ts | 64 +++++++++++++++++ apps/api/src/tenancy/tenancy.module.ts | 3 + .../src/tenancy/tenant-context.interceptor.ts | 69 +++++-------------- apps/api/test/files.e2e-spec.ts | 53 ++++++++++++++ apps/api/test/institute-profile.e2e-spec.ts | 22 ++++++ packages/shared/src/files.test.ts | 7 ++ packages/shared/src/files.ts | 10 ++- 17 files changed, 407 insertions(+), 112 deletions(-) create mode 100644 apps/api/src/tenancy/request-transaction.service.ts diff --git a/apps/api/src/common/decorators.ts b/apps/api/src/common/decorators.ts index 2ef1242..74d9eec 100644 --- a/apps/api/src/common/decorators.ts +++ b/apps/api/src/common/decorators.ts @@ -28,6 +28,15 @@ export const CurrentUser = createParamDecorator( export const USER_SCOPED = 'jantrik:userScoped'; +export const OWN_TRANSACTION = 'jantrik:ownTransaction'; +/** + * The route opens its request transaction itself (`RequestTransaction.run`), after its slow part: + * an upload's body is read and its image decoded before any database connection is taken, so a + * slow phone line never holds one (docs/auth.md → Request pipeline). Guards (token, module, + * roles, rate limits) still run first; everything that touches the database goes inside `run`. + */ +export const OwnTransaction = () => SetMetadata(OWN_TRANSACTION, true); + export const PLATFORM = 'jantrik:platform'; /** diff --git a/apps/api/src/files/file-store-access.spec.ts b/apps/api/src/files/file-store-access.spec.ts index bb07317..2fb9192 100644 --- a/apps/api/src/files/file-store-access.spec.ts +++ b/apps/api/src/files/file-store-access.spec.ts @@ -7,8 +7,25 @@ import path from 'node:path'; const SRC = path.resolve(import.meta.dirname, '..'); const THE_STORE = 'files/postgres-file-store.ts'; +/** Prisma relation fields that reach the files (include, select or nested writes). */ +const RELATIONS = [ + 'photoFile', + 'logoFile', + 'signatureFile', + 'sealFile', + 'storedFiles', + 'storedFileUsage', + 'storedFilesCreated', + 'profileLogo', + 'profileSignature', + 'profileSeal', +]; + export function touchesFileTables(code: string): boolean { - return /\.storedFile(Usage)?\b|\bstored_file(s|_usage)\b/.test(code); + return ( + /\.storedFile(Usage)?\b|\bstored_file(s|_usage)\b/.test(code) || + new RegExp(String.raw`\b(${RELATIONS.join('|')})\s*:`).test(code) + ); } function sources(dir: string): string[] { @@ -35,10 +52,22 @@ describe('who touches stored_files', () => { 'SELECT bytes FROM stored_files WHERE id = $1', 'DELETE FROM stored_files', 'UPDATE stored_file_usage SET bytes_used = 0', + // Through a relation (review): these read bytes or change files past the usage total. + 'tx.student.findMany({ include: { photoFile: true } })', + 'tx.student.update({ where: { id }, data: { photoFile: { delete: true } } })', + 'tx.instituteProfile.findFirst({ include: { logoFile: true } })', + 'select: { signatureFile: { select: { bytes: true } } }', + 'include: { sealFile: true }', + 'tx.tenant.findFirst({ include: { storedFiles: true } })', + 'include: { storedFileUsage: true }', + 'tx.user.findFirst({ select: { storedFilesCreated: true } })', + 'include: { profileLogo: true, student: true }', ]; for (const sample of caught) expect(touchesFileTables(sample), sample).toBe(true); const fine = [ 'await this.files.get(id)', + 'data: { photoFileId: stored.id }', + 'select: { photoFileId: true, logoFileKind: true }', 'tx.student.update({ data: { photoFileId } })', 'const storedFiles = 3;', "'stored-files:' advisory lock name", diff --git a/apps/api/src/files/file-store.ts b/apps/api/src/files/file-store.ts index ccae1e3..0f74ef1 100644 --- a/apps/api/src/files/file-store.ts +++ b/apps/api/src/files/file-store.ts @@ -34,8 +34,12 @@ export interface FileStore { * changes of one image cannot both see the same old file (one would be left behind). */ lock(): Promise; - /** Stores a file; 413 STORAGE_FULL when the institute's total would pass its cap. */ - put(file: PutFile): Promise; + /** + * Stores a file; 413 STORAGE_FULL when the institute's total would pass its cap. `replaces`: + * the file this one replaces (the caller deletes it in the same transaction), so a same-size + * replacement is never refused near the cap. + */ + put(file: PutFile, opts?: { replaces?: string | null }): Promise; /** The file with its bytes, or null (unknown here). */ get(id: string): Promise<(StoredFileMeta & { bytes: Buffer }) | null>; /** The file without its bytes, or null. */ diff --git a/apps/api/src/files/files.module.ts b/apps/api/src/files/files.module.ts index 9665f16..f1a7c94 100644 --- a/apps/api/src/files/files.module.ts +++ b/apps/api/src/files/files.module.ts @@ -13,7 +13,7 @@ import { apiError } from '../common/api-error.js'; import { RequestContext } from '../common/request-context.js'; import { RateLimiter } from '../redis/rate-limiter.service.js'; import { FILE_STORE, type FileStore, type StoredFileMeta } from './file-store.js'; -import { ImageService } from './image.service.js'; +import { ImageService, type ProcessedImage } from './image.service.js'; import { PostgresFileStore } from './postgres-file-store.js'; /** What multer hands over for the `file` field (memory storage). */ @@ -35,7 +35,14 @@ export const ImageUpload = () => ), ); -/** Upload → ImageService → FileStore, with the per-person limit. */ +/** An upload ready to store: re-encoded, its kind known. */ +export type PreparedImage = ProcessedImage & { kind: StoredFileKind }; + +/** + * Upload → ImageService → FileStore, with the per-person limit. In two steps (from the review): + * `prepare` touches no database (routes marked @OwnTransaction call it before opening their + * transaction); `store` puts the file in the request's transaction. + */ @Injectable() export class ImageUploads { constructor( @@ -45,7 +52,7 @@ export class ImageUploads { private readonly context: RequestContext, ) {} - async store(kind: StoredFileKind, upload: UploadedImage | undefined): Promise { + async prepare(kind: StoredFileKind, upload: UploadedImage | undefined): Promise { if (!upload?.buffer?.length) { throw apiError(400, 'FILE_REQUIRED', 'Choose an image to upload', { field: 'file' }); } @@ -54,8 +61,11 @@ export class ImageUploads { limit: UPLOADS_PER_USER, windowSec: 600, }); - const image = await this.images.process(kind, upload.buffer); - return this.files.put({ kind, ...image }); + return { kind, ...(await this.images.process(kind, upload.buffer)) }; + } + + store(image: PreparedImage, replaces: string | null): Promise { + return this.files.put(image, { replaces }); } } diff --git a/apps/api/src/files/image.service.spec.ts b/apps/api/src/files/image.service.spec.ts index 5402d68..1dfce5c 100644 --- a/apps/api/src/files/image.service.spec.ts +++ b/apps/api/src/files/image.service.spec.ts @@ -1,7 +1,7 @@ import { randomBytes } from 'node:crypto'; import { crc32, deflateSync } from 'node:zlib'; import sharp from 'sharp'; -import { ImageService, processImage, sniffImage } from './image.service.js'; +import { ImageService, Slots, processImage, sniffImage } from './image.service.js'; // docs/files.md: what an upload becomes before it is stored. Test images are made with sharp. @@ -157,6 +157,57 @@ describe('processImage', () => { }); }); +describe('PNG metadata', () => { + it('strips EXIF from a PNG too (the eXIf chunk), whatever it becomes', async () => { + const input = await noise(300, 300) + .png() + .withExif({ + IFD0: { Make: 'PhoneCo' }, + IFD3: { GPSLatitudeRef: 'N', GPSLatitude: '23/1 48/1 0/1' }, + }) + .toBuffer(); + expect(input.includes(Buffer.from('PhoneCo'))).toBe(true); + for (const kind of ['STUDENT_PHOTO', 'LOGO', 'SIGNATURE'] as const) { + const out = await processImage(kind, input); + expect(out.bytes.includes(Buffer.from('PhoneCo'))).toBe(false); + expect((await sharp(out.bytes).metadata()).exif).toBeUndefined(); + } + }); +}); + +describe('Slots (the image queue)', () => { + it('hands a freed slot to the first waiter: never more than the maximum at once', async () => { + const slots = new Slots(2, 8); + await slots.acquire(); + await slots.acquire(); + const third = slots.acquire(); + expect([slots.active, slots.waiting]).toEqual([2, 1]); + slots.release(); // the slot goes to the third, not back to the pool + const fourth = slots.acquire(); // so a newcomer waits + await third; + expect([slots.active, slots.waiting]).toEqual([2, 1]); + slots.release(); + await fourth; + expect([slots.active, slots.waiting]).toEqual([2, 0]); + }); + + it('refuses with 503 IMAGE_BUSY when the queue is full', async () => { + const slots = new Slots(1, 2); + await slots.acquire(); + const queued = [slots.acquire(), slots.acquire()]; + const refused = await slots + .acquire() + .catch((e: { getStatus(): number; getResponse(): object }) => e); + expect((refused as { getStatus(): number }).getStatus()).toBe(503); + expect((refused as { getResponse(): object }).getResponse()).toMatchObject({ + code: 'IMAGE_BUSY', + }); + for (let i = 0; i < 3; i++) slots.release(); + await Promise.all(queued); + expect([slots.active, slots.waiting]).toEqual([0, 0]); + }); +}); + describe('ImageService', () => { it('runs at most two images at once', async () => { const service = new ImageService(); @@ -164,7 +215,7 @@ describe('ImageService', () => { let peak = 0; // Watch the service's own counter while five run. const watch = setInterval(() => { - peak = Math.max(peak, (service as unknown as { running: number }).running); + peak = Math.max(peak, (service as unknown as { slots: Slots }).slots.active); }, 1); const results = await Promise.all( Array.from({ length: 5 }, () => service.process('STUDENT_PHOTO', input)), diff --git a/apps/api/src/files/image.service.ts b/apps/api/src/files/image.service.ts index 73c4c9f..82249a9 100644 --- a/apps/api/src/files/image.service.ts +++ b/apps/api/src/files/image.service.ts @@ -20,6 +20,48 @@ export interface ProcessedImage { /** At most this many images are decoded at once per process (memory: a 48 MP photo is ~150 MB). */ const MAX_PARALLEL = 2; +/** At most this many wait for a slot; more get 503 IMAGE_BUSY instead of queueing without end. */ +const MAX_WAITING = 8; + +/** + * A counting semaphore with a bounded queue. A freed slot is handed straight to the first waiter + * (the count never drops in between), so a newcomer cannot slip in and make it MAX + 1. + */ +export class Slots { + private running = 0; + private readonly queue: (() => void)[] = []; + + constructor( + private readonly max: number, + private readonly maxWaiting: number, + ) {} + + get active(): number { + return this.running; + } + + get waiting(): number { + return this.queue.length; + } + + async acquire(): Promise { + if (this.running < this.max) { + this.running++; + return; + } + if (this.queue.length >= this.maxWaiting) { + throw apiError(503, 'IMAGE_BUSY', 'Many images are being prepared; try again in a moment'); + } + await new Promise((go) => this.queue.push(go)); + } + + release(): void { + const next = this.queue.shift(); + if (next) + next(); // the slot passes on: running stays the same + else this.running--; + } +} /** * Turns an upload into what is stored (docs/files.md, decision S7): only JPEG, PNG or WebP by @@ -29,17 +71,14 @@ const MAX_PARALLEL = 2; */ @Injectable() export class ImageService { - private running = 0; - private readonly queue: (() => void)[] = []; + private readonly slots = new Slots(MAX_PARALLEL, MAX_WAITING); async process(kind: StoredFileKind, input: Buffer): Promise { - if (this.running >= MAX_PARALLEL) await new Promise((go) => this.queue.push(go)); - this.running++; + await this.slots.acquire(); try { return await processImage(kind, input); } finally { - this.running--; - this.queue.shift()?.(); + this.slots.release(); } } } diff --git a/apps/api/src/files/postgres-file-store.ts b/apps/api/src/files/postgres-file-store.ts index 724cd53..2129e5f 100644 --- a/apps/api/src/files/postgres-file-store.ts +++ b/apps/api/src/files/postgres-file-store.ts @@ -45,7 +45,7 @@ export class PostgresFileStore implements FileStore { .$executeRaw`SELECT pg_advisory_xact_lock(hashtextextended('stored-files:' || app_current_tenant_id()::text, 0))`; } - async put(file: PutFile): Promise { + async put(file: PutFile, opts: { replaces?: string | null } = {}): Promise { const limit = FILE_LIMITS[file.kind]; const size = file.bytes.length; // ImageService guarantees these; reaching here otherwise is a bug, not a user error. @@ -63,7 +63,15 @@ export class PostgresFileStore implements FileStore { }); const capBytes = this.capBytes; const bytesUsed = Number(usage.bytesUsed); - if (bytesUsed + size > capBytes) { + const replaced = opts.replaces + ? (( + await tx.storedFile.findUnique({ + where: { id: opts.replaces }, + select: { sizeBytes: true }, + }) + )?.sizeBytes ?? 0) + : 0; + if (bytesUsed - replaced + size > capBytes) { throw apiError(413, 'STORAGE_FULL', "The institute's storage for images is full", { bytesUsed, capBytes, diff --git a/apps/api/src/institute/institute-profile.module.ts b/apps/api/src/institute/institute-profile.module.ts index 948a864..73bb2b7 100644 --- a/apps/api/src/institute/institute-profile.module.ts +++ b/apps/api/src/institute/institute-profile.module.ts @@ -25,7 +25,7 @@ import { } from '@jantrik/shared'; import type { Request, Response } from 'express'; import { AuditService } from '../audit/audit.module.js'; -import { RequireModule, Roles } from '../common/decorators.js'; +import { OwnTransaction, RequireModule, Roles } from '../common/decorators.js'; import { RequestContext } from '../common/request-context.js'; import { zodDto } from '../common/zod.js'; import { FILE_STORE, type FileStore, type StoredFileMeta } from '../files/file-store.js'; @@ -36,6 +36,7 @@ import { type UploadedImage, } from '../files/files.module.js'; import { Db } from '../tenancy/db.service.js'; +import { RequestTransaction } from '../tenancy/request-transaction.service.js'; class InstituteProfileDto extends zodDto(instituteProfileSchema) {} @@ -77,6 +78,7 @@ export class InstituteProfileService { private readonly context: RequestContext, private readonly audit: AuditService, private readonly uploads: ImageUploads, + private readonly transaction: RequestTransaction, @Inject(FILE_STORE) private readonly files: FileStore, ) {} @@ -135,27 +137,33 @@ export class InstituteProfileService { } /** - * Sets (or replaces) one image; the replaced file is deleted in the same transaction (F10). The - * store holds the institute's file lock from here to commit, so the old id read below is final. + * Sets (or replaces) one image; the replaced file is deleted in the same transaction (F10). + * PUT /institute/profile/:slot is an @OwnTransaction route: the image is decoded first, holding + * no database connection, then one short request transaction stores it. Inside it the + * institute's file lock comes before reading the old id, and the cap counts the file replaced. */ async setImage(slot: InstituteImageSlot, upload: UploadedImage | undefined) { - const stored = await this.uploads.store(INSTITUTE_IMAGE_KIND[slot], upload); - const profile = await this.ensureRow(); - const oldId = profile[COLUMN[slot]]; - await this.db.tx.instituteProfile.update({ - where: { id: profile.id }, - data: { [COLUMN[slot]]: stored.id }, - select: { id: true }, - }); - if (oldId) await this.files.delete(oldId); - await this.audit.record({ - entity: 'institute_profile', - entityId: profile.id, - action: 'UPDATE', - oldValues: { image: slot, fileId: oldId }, - newValues: { image: slot, fileId: stored.id }, + const image = await this.uploads.prepare(INSTITUTE_IMAGE_KIND[slot], upload); + return this.transaction.run(async () => { + await this.files.lock(); + const profile = await this.ensureRow(); + const oldId = profile[COLUMN[slot]]; + const stored = await this.uploads.store(image, oldId); + await this.db.tx.instituteProfile.update({ + where: { id: profile.id }, + data: { [COLUMN[slot]]: stored.id }, + select: { id: true }, + }); + if (oldId) await this.files.delete(oldId); + await this.audit.record({ + entity: 'institute_profile', + entityId: profile.id, + action: 'UPDATE', + oldValues: { image: slot, fileId: oldId }, + newValues: { image: slot, fileId: stored.id }, + }); + return this.get(); }); - return this.get(); } async removeImage(slot: InstituteImageSlot): Promise { @@ -187,7 +195,9 @@ export class InstituteProfileService { /** * The profile row, created for an image uploaded before the first save (F6) with the - * registered name in the matching script, so the "one name" CHECK holds. + * registered name in the matching script, so the "one name" CHECK holds. Created with + * ON CONFLICT DO NOTHING (createMany skipDuplicates): a first save at the same moment (PUT + * /institute/profile, an upsert) wins or loses the race without an error either way. */ private async ensureRow() { const existing = await this.row(); @@ -200,13 +210,19 @@ export class InstituteProfileService { const names = BANGLA.test(name) ? { nameBn: name.slice(0, 200) } : { nameEn: name.slice(0, 200) }; - const row = await this.db.tx.instituteProfile.create({ data: { tenantId, ...names } }); - await this.audit.record({ - entity: 'institute_profile', - entityId: row.id, - action: 'CREATE', - newValues: names, + const { count } = await this.db.tx.instituteProfile.createMany({ + data: [{ tenantId, ...names }], + skipDuplicates: true, }); + const row = await this.db.tx.instituteProfile.findFirstOrThrow(); + if (count === 1) { + await this.audit.record({ + entity: 'institute_profile', + entityId: row.id, + action: 'CREATE', + newValues: names, + }); + } return row; } } @@ -264,6 +280,7 @@ export class InstituteProfileController { /** multipart/form-data with `file` (JPEG, PNG or WebP, at most 5 MB). */ @Put(':slot') @Roles('OWNER', 'ADMIN') + @OwnTransaction() @ImageUpload() setImage( @Slot() slot: InstituteImageSlot, diff --git a/apps/api/src/students/student-photo.service.ts b/apps/api/src/students/student-photo.service.ts index 11fb80b..d02b68b 100644 --- a/apps/api/src/students/student-photo.service.ts +++ b/apps/api/src/students/student-photo.service.ts @@ -5,6 +5,7 @@ import { apiError } from '../common/api-error.js'; import { FILE_STORE, type FileStore } from '../files/file-store.js'; import { ImageUploads, type UploadedImage } from '../files/files.module.js'; import { Db } from '../tenancy/db.service.js'; +import { RequestTransaction } from '../tenancy/request-transaction.service.js'; import { StudentAccess } from './student-access.service.js'; import { StudentAdminService } from './student-admin.service.js'; @@ -21,6 +22,7 @@ export class StudentPhotoService { private readonly access: StudentAccess, private readonly uploads: ImageUploads, private readonly audit: AuditService, + private readonly transaction: RequestTransaction, @Inject(FILE_STORE) private readonly files: FileStore, ) {} @@ -46,19 +48,28 @@ export class StudentPhotoService { return s.photoFileId; } + /** + * PUT /students/:id/photo, an @OwnTransaction route: the image is decoded and re-encoded first, + * holding no database connection, then one short request transaction stores it (docs/auth.md → + * Request pipeline). Inside it the institute's file lock comes before reading the old id, and + * the cap counts the photo being replaced. + */ async set(studentId: string, upload: UploadedImage | undefined): Promise { - await this.writable(studentId); - // The store holds the institute's file lock from here to commit: the old id read next is final. - const stored = await this.uploads.store('STUDENT_PHOTO', upload); - const old = await this.current(studentId); - await this.db.tx.student.update({ - where: { id: studentId }, - data: { photoFileId: stored.id }, - select: { id: true }, + const image = await this.uploads.prepare('STUDENT_PHOTO', upload); + return this.transaction.run(async () => { + await this.writable(studentId); + await this.files.lock(); + const old = await this.current(studentId); + const stored = await this.uploads.store(image, old); + await this.db.tx.student.update({ + where: { id: studentId }, + data: { photoFileId: stored.id }, + select: { id: true }, + }); + if (old) await this.files.delete(old); + await this.record(studentId, old, stored.id); + return this.admin.view(studentId); }); - if (old) await this.files.delete(old); - await this.record(studentId, old, stored.id); - return this.admin.view(studentId); } async remove(studentId: string): Promise { diff --git a/apps/api/src/students/students.module.ts b/apps/api/src/students/students.module.ts index 0f0e660..074e031 100644 --- a/apps/api/src/students/students.module.ts +++ b/apps/api/src/students/students.module.ts @@ -43,7 +43,7 @@ import { type StudentsSummary, } from '@jantrik/shared'; import type { Request, Response } from 'express'; -import { RequireModule, Roles } from '../common/decorators.js'; +import { OwnTransaction, RequireModule, Roles } from '../common/decorators.js'; import { zodDto } from '../common/zod.js'; import { FILE_STORE, type FileStore } from '../files/file-store.js'; import { ImageUpload, sendStoredImage, type UploadedImage } from '../files/files.module.js'; @@ -401,6 +401,7 @@ export class StudentsController { /** multipart/form-data with `file` (JPEG, PNG or WebP, at most 5 MB); stored as a JPEG. */ @Put(':id/photo') @Roles('OWNER', 'ADMIN') + @OwnTransaction() @ImageUpload() setPhoto( @Id() id: string, diff --git a/apps/api/src/tenancy/request-transaction.service.ts b/apps/api/src/tenancy/request-transaction.service.ts new file mode 100644 index 0000000..4d982b9 --- /dev/null +++ b/apps/api/src/tenancy/request-transaction.service.ts @@ -0,0 +1,64 @@ +import { ForbiddenException, Injectable } from '@nestjs/common'; +import { withContext, type TenantTx } from '@jantrik/db'; +import { RequestContext } from '../common/request-context.js'; +import { PrismaService } from '../prisma/prisma.service.js'; + +export const REQUEST_TX_TIMEOUT_MS = 15_000; + +/** + * The authenticated request's RLS transaction (docs/auth.md → Request pipeline): + * withContext({ tenantId, userId }) → the tenant re-check → fn → commit → afterCommit callbacks. + * A thrown error rolls the transaction back and drops the afterCommit callbacks. Services reach + * the transaction through `Db.tx`. + * + * TenantContextInterceptor runs every authenticated route inside it. A route marked + * `@OwnTransaction()` (uploads) runs without one and calls `run` itself once its slow part is + * done (reading the body, decoding the image), so no database connection waits on a client. + */ +@Injectable() +export class RequestTransaction { + constructor( + private readonly prisma: PrismaService, + private readonly context: RequestContext, + ) {} + + async run(fn: () => Promise, opts: { userScoped?: boolean } = {}): Promise { + const principal = this.context.requirePrincipal(); + const tenantId = opts.userScoped ? null : (principal.tenantId ?? null); + let committed: (() => unknown)[] = []; + const result = await withContext( + this.prisma.client, + { tenantId, userId: principal.userId }, + async (tx) => { + if (tenantId) await assertTenantAccess(tx); + this.context.beginTransaction(tx); + try { + const value = await fn(); + committed = this.context.endTransaction(); + return value; + } catch (error) { + this.context.endTransaction(); // rollback: drop side effects + throw error; + } + }, + { timeout: REQUEST_TX_TIMEOUT_MS, maxWait: 5_000 }, + ); + await this.context.runAfterCommit(committed); + return result; + } +} + +/** + * Re-checked on every tenant request (not just at switch-tenant), so suspending a tenant or + * removing a membership takes effect immediately rather than when the access token expires. + */ +async function assertTenantAccess(tx: TenantTx): Promise { + const [row] = await tx.$queryRaw<{ status: string; member: boolean }[]>` + SELECT t.status::text AS status, + EXISTS (SELECT 1 FROM memberships m + WHERE m.user_id = app_current_user_id() AND m.status = 'ACTIVE') AS member + FROM tenants t`; + if (!row || !['ACTIVE', 'TRIAL'].includes(row.status) || !row.member) { + throw new ForbiddenException('No access to this tenant'); + } +} diff --git a/apps/api/src/tenancy/tenancy.module.ts b/apps/api/src/tenancy/tenancy.module.ts index 89d30bc..7917736 100644 --- a/apps/api/src/tenancy/tenancy.module.ts +++ b/apps/api/src/tenancy/tenancy.module.ts @@ -3,6 +3,7 @@ import { Clock } from '../common/clock.js'; import { RequestContext } from '../common/request-context.js'; import { Db } from './db.service.js'; import { InstituteProvisioning } from './institute-provisioning.service.js'; +import { RequestTransaction } from './request-transaction.service.js'; import { TenantAccessService } from './tenant-access.service.js'; import { TenantContextInterceptor } from './tenant-context.interceptor.js'; import { TenantJobRunner } from './tenant-job-runner.service.js'; @@ -13,6 +14,7 @@ import { TenantJobRunner } from './tenant-job-runner.service.js'; RequestContext, Clock, Db, + RequestTransaction, TenantAccessService, TenantContextInterceptor, TenantJobRunner, @@ -22,6 +24,7 @@ import { TenantJobRunner } from './tenant-job-runner.service.js'; RequestContext, Clock, Db, + RequestTransaction, TenantAccessService, TenantContextInterceptor, TenantJobRunner, diff --git a/apps/api/src/tenancy/tenant-context.interceptor.ts b/apps/api/src/tenancy/tenant-context.interceptor.ts index 66f6fb6..1ba520b 100644 --- a/apps/api/src/tenancy/tenant-context.interceptor.ts +++ b/apps/api/src/tenancy/tenant-context.interceptor.ts @@ -1,79 +1,42 @@ import { - ForbiddenException, Injectable, type CallHandler, type ExecutionContext, type NestInterceptor, } from '@nestjs/common'; import { Reflector } from '@nestjs/core'; -import { withContext, type TenantTx } from '@jantrik/db'; import { from, lastValueFrom, type Observable } from 'rxjs'; -import { USER_SCOPED } from '../common/decorators.js'; +import { OWN_TRANSACTION, USER_SCOPED } from '../common/decorators.js'; import { RequestContext } from '../common/request-context.js'; -import { PrismaService } from '../prisma/prisma.service.js'; - -const REQUEST_TX_TIMEOUT_MS = 15_000; +import { RequestTransaction } from './request-transaction.service.js'; /** - * Runs every authenticated request inside one RLS transaction: + * Runs every authenticated request inside one RLS transaction (RequestTransaction): * withContext({ tenantId: tid, userId: sub }) → handler → commit → afterCommit callbacks. * A thrown error rolls the transaction back and drops the afterCommit callbacks. * Services reach the transaction through `Db.tx`. + * + * Except a route marked `@OwnTransaction()` (uploads): it gets no transaction here, so reading + * its body and decoding the image hold no database connection; its handler opens the same + * transaction itself with `RequestTransaction.run` afterwards (docs/auth.md → Request pipeline). */ @Injectable() export class TenantContextInterceptor implements NestInterceptor { constructor( - private readonly prisma: PrismaService, + private readonly transaction: RequestTransaction, private readonly context: RequestContext, private readonly reflector: Reflector, ) {} intercept(ctx: ExecutionContext, next: CallHandler): Observable { - const principal = this.context.principal; - if (!principal) return next.handle(); // public route: no request transaction - const userScoped = this.reflector.getAllAndOverride(USER_SCOPED, [ - ctx.getHandler(), - ctx.getClass(), - ]); - const tenantId = userScoped ? null : (principal.tenantId ?? null); - return from(this.run(principal.userId, tenantId, next)); - } - - private async run(userId: string, tenantId: string | null, next: CallHandler): Promise { - let committed: (() => unknown)[] = []; - const result = await withContext( - this.prisma.client, - { tenantId, userId }, - async (tx) => { - if (tenantId) await assertTenantAccess(tx); - this.context.beginTransaction(tx); - try { - const value = await lastValueFrom(next.handle(), { defaultValue: undefined }); - committed = this.context.endTransaction(); - return value; - } catch (error) { - this.context.endTransaction(); // rollback: drop side effects - throw error; - } - }, - { timeout: REQUEST_TX_TIMEOUT_MS, maxWait: 5_000 }, + if (!this.context.principal) return next.handle(); // public route: no request transaction + const targets = [ctx.getHandler(), ctx.getClass()]; + if (this.reflector.getAllAndOverride(OWN_TRANSACTION, targets)) return next.handle(); + const userScoped = this.reflector.getAllAndOverride(USER_SCOPED, targets); + return from( + this.transaction.run(() => lastValueFrom(next.handle(), { defaultValue: undefined }), { + userScoped, + }), ); - await this.context.runAfterCommit(committed); - return result; - } -} - -/** - * Re-checked on every tenant request (not just at switch-tenant), so suspending a tenant or - * removing a membership takes effect immediately rather than when the access token expires. - */ -async function assertTenantAccess(tx: TenantTx): Promise { - const [row] = await tx.$queryRaw<{ status: string; member: boolean }[]>` - SELECT t.status::text AS status, - EXISTS (SELECT 1 FROM memberships m - WHERE m.user_id = app_current_user_id() AND m.status = 'ACTIVE') AS member - FROM tenants t`; - if (!row || !['ACTIVE', 'TRIAL'].includes(row.status) || !row.member) { - throw new ForbiddenException('No access to this tenant'); } } diff --git a/apps/api/test/files.e2e-spec.ts b/apps/api/test/files.e2e-spec.ts index 7fa7d09..0a0bca6 100644 --- a/apps/api/test/files.e2e-spec.ts +++ b/apps/api/test/files.e2e-spec.ts @@ -1,3 +1,5 @@ +import { request as httpRequest, type Server } from 'node:http'; +import type { AddressInfo } from 'node:net'; import { crc32, deflateSync } from 'node:zlib'; import { withTenant } from '@jantrik/db'; import type { GuardianChild, StudentProfile } from '@jantrik/shared'; @@ -239,6 +241,57 @@ describe('student photos', () => { // Full now: a third is refused. const third = await put(t.admin, t.b[0]!.id, image).expect(413); expect(third.body).toMatchObject({ code: 'STORAGE_FULL', capBytes: CAP }); + // Replacing a photo with one of the same size does not grow the total: allowed (review). + await put(t.admin, t.a[0]!.id, image).expect(200); + expect((await usage(t.tenantId)).bytesUsed).toBe(now.bytesUsed); + }); + + it('a slow upload holds no database transaction while its body arrives (review)', async () => { + const server = h.app.getHttpServer() as Server; + if (!server.listening) await new Promise((r) => server.listen(0, '127.0.0.1', r)); + const { port } = server.address() as AddressInfo; + const image = await photo(400, 500, '#aa6633'); + const boundary = 'jantrik-slow-upload'; + const head = Buffer.from( + `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="slow.jpg"\r\n` + + 'Content-Type: image/jpeg\r\n\r\n', + ); + const tail = Buffer.from(`\r\n--${boundary}--\r\n`); + const openTransactions = async () => + ( + await h.prisma.$queryRaw<{ n: number }[]>` + SELECT count(*)::int AS n FROM pg_stat_activity + WHERE usename = current_user AND datname = current_database() + AND state LIKE 'idle in transaction%'` + )[0]!.n; + const status = new Promise((resolve, reject) => { + const req = httpRequest( + { + host: '127.0.0.1', + port, + method: 'PUT', + path: `/students/${s.a[0]!.id}/photo`, + headers: { + Authorization: `Bearer ${s.admin}`, + 'Content-Type': `multipart/form-data; boundary=${boundary}`, + 'Content-Length': head.length + image.length + tail.length, + }, + }, + (res) => { + res.resume(); + res.on('end', () => resolve(res.statusCode!)); + }, + ); + req.on('error', reject); + req.write(head); + req.write(image.subarray(0, 64)); + // The rest arrives 2 s later, as from a phone on a slow line. + setTimeout(() => req.end(Buffer.concat([image.subarray(64), tail])), 2_000); + }); + await new Promise((r) => setTimeout(r, 1_000)); + const whileReading = await openTransactions(); + expect(await status).toBe(200); + expect(whileReading).toBe(0); }); it('at most 60 uploads per person in 10 minutes (F8)', async () => { diff --git a/apps/api/test/institute-profile.e2e-spec.ts b/apps/api/test/institute-profile.e2e-spec.ts index 53850af..38518f7 100644 --- a/apps/api/test/institute-profile.e2e-spec.ts +++ b/apps/api/test/institute-profile.e2e-spec.ts @@ -98,6 +98,28 @@ describe('institute profile', () => { expect(rows[0]!.newValues).toMatchObject({ eiin: '108123' }); }); + it('an upper-case web address is stored with a lower-case scheme, never a 500 (review)', async () => { + const t = await institute(); + const res = await http(h) + .put('/institute/profile') + .set(bearer(t.owner)) + .send({ nameEn: 'X', website: 'HTTPS://Shapla.edu.bd' }) + .expect(200); + expect(res.body.website).toBe('https://Shapla.edu.bd'); + }); + + it('the first logo and the first save at the same moment both succeed (review)', async () => { + for (let i = 0; i < 3; i++) { + const t = await institute(); + const logo = await png(64, 64); + const [up, save] = await Promise.all([ + upload(t.admin, 'logo', logo), + http(h).put('/institute/profile').set(bearer(t.owner)).send({ nameBn: 'শাপলা' }), + ]); + expect([up.status, save.status]).toEqual([200, 200]); + } + }); + it('refuses bad values (400) and non-admins (403)', async () => { const t = await institute(); for (const bad of [ diff --git a/packages/shared/src/files.test.ts b/packages/shared/src/files.test.ts index bd3dd07..95dd0de 100644 --- a/packages/shared/src/files.test.ts +++ b/packages/shared/src/files.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from 'vitest'; import { FILE_LIMITS, + INSTITUTE_PROFILE_PATTERNS, normalizeInstitutePhone, normalizeWebsite, STORED_FILE_KINDS, @@ -82,4 +83,10 @@ describe('instituteProfileSchema', () => { expect(normalizeWebsite('http://shapla.edu.bd')).toBe('http://shapla.edu.bd'); expect(parse({ website: 'shapla.edu.bd' }).data?.website).toBe('https://shapla.edu.bd'); }); + + it('lower-cases the scheme, as the database CHECK is case-sensitive (review)', () => { + expect(normalizeWebsite('Http://Shapla.edu.bd')).toBe('http://Shapla.edu.bd'); + expect(parse({ website: 'HTTPS://shapla.edu.bd' }).data?.website).toBe('https://shapla.edu.bd'); + expect(INSTITUTE_PROFILE_PATTERNS.website.test('HTTPS://shapla.edu.bd')).toBe(false); + }); }); diff --git a/packages/shared/src/files.ts b/packages/shared/src/files.ts index 377aa26..b8ea489 100644 --- a/packages/shared/src/files.ts +++ b/packages/shared/src/files.ts @@ -128,7 +128,7 @@ export const INSTITUTE_PROFILE_PATTERNS = { eiin: /^\d{6}$/, phone: /^\+?\d{5,15}$/, email: /^[^@\s]+@[^@\s]+\.[^@\s]+$/, - website: /^https?:\/\/\S+$/i, + website: /^https?:\/\/\S+$/, } as const; /** A mobile is stored as E.164; anything else as its digits (a landline), with an optional +. */ @@ -141,8 +141,12 @@ export function normalizeInstitutePhone(input: string): string { ); } -/** `shapla.edu.bd` → `https://shapla.edu.bd`; a given scheme is kept (and then checked). */ +/** + * `shapla.edu.bd` → `https://shapla.edu.bd`; a given scheme is kept (and then checked) in lower + * case (`HTTP://` → `http://`), as the database CHECK compares it case-sensitively. + */ export function normalizeWebsite(input: string): string { const v = input.trim(); - return /^[a-z][a-z0-9+.-]*:/i.test(v) ? v : `https://${v}`; + const scheme = /^[a-z][a-z0-9+.-]*:/i.exec(v); + return scheme ? scheme[0].toLowerCase() + v.slice(scheme[0].length) : `https://${v}`; } From 459bcf718a17b03eae5fa84886c61292f9ea2211 Mon Sep 17 00:00:00 2001 From: omerFixesBugs Date: Mon, 16 Nov 2026 15:05:43 +0600 Subject: [PATCH 35/44] Web after the review: a chosen image is shrunk in the browser to 1600 px before upload (JPEG for photos, PNG otherwise; the original when it cannot be decoded), the guardian's report card shows the photo through the guardian's own route (R3, checked in the exams spec), and the IMAGE_BUSY message Co-Authored-By: Claude Opus 5.5 --- apps/web/e2e/exams.spec.ts | 10 +++ apps/web/e2e/helpers.ts | 18 ++++++ apps/web/messages/bn.json | 3 +- apps/web/messages/en.json | 3 +- apps/web/src/app/(app)/setup/profile/page.tsx | 1 + apps/web/src/components/exams/guardian.tsx | 2 +- apps/web/src/components/exams/report-card.tsx | 22 ++++++- apps/web/src/components/image-upload.tsx | 18 ++++-- apps/web/src/components/student-photo.tsx | 4 +- .../src/components/students/photo-dialog.tsx | 1 + apps/web/src/lib/authed-image.ts | 1 + apps/web/src/lib/image-shrink.test.ts | 29 +++++++++ apps/web/src/lib/image-shrink.ts | 61 +++++++++++++++++++ 13 files changed, 161 insertions(+), 12 deletions(-) create mode 100644 apps/web/src/lib/image-shrink.test.ts create mode 100644 apps/web/src/lib/image-shrink.ts diff --git a/apps/web/e2e/exams.spec.ts b/apps/web/e2e/exams.spec.ts index 2155e48..9236a74 100644 --- a/apps/web/e2e/exams.spec.ts +++ b/apps/web/e2e/exams.spec.ts @@ -13,6 +13,7 @@ import { api, API_URL, apiLogin, + apiUploadPhoto, apiOtpLogin, DEMO, otpLoginWithBanglaDigits, @@ -266,6 +267,12 @@ for (const c of CASES) { ); await admin.emulateMedia({ media: 'screen' }); + // The child gets a photo; the guardian's report card shows it through the guardian's own + // route (/me/children/:id/photo), checked once (sprint 1 P2, from the review). + const office = await apiLogin(DEMO.shaplaOwner); + const photoChild = (await api(office, `/students?q=${c.child}`)).items[0]!.id; + if (c.lang === 'bn') await apiUploadPhoto(office, photoChild); + // ── The guardian, 390 px ── const guardian = await newPage(browser, baseURL, GUARDIAN_PHONE); await otpLoginWithBanglaDigits(guardian, c.guardian); @@ -282,12 +289,15 @@ for (const c of CASES) { const reportCard = guardian.getByTestId('report-card'); await expect(reportCard).toBeVisible(); await expect(reportCard.getByTestId('report-card-summary')).toBeVisible(); + if (c.lang === 'bn') await expect(reportCard.getByTestId('student-photo')).toBeVisible(); expect(await findLayoutProblems(guardian)).toEqual([]); await guardian.emulateMedia({ media: 'print' }); const pdf = (await guardian.pdf({ preferCSSPageSize: true })).toString('latin1'); expect(pdf.match(/\/Type\s*\/Page[^s]/g)?.length).toBe(1); expect(pdf).toMatch(/\/MediaBox\s*\[\s*0\s+0\s+(594|595)(\.\d+)?\s+(841|842)(\.\d+)?\s*\]/); await guardian.emulateMedia({ media: 'screen' }); + // The photo goes again, so the other specs see the demo data as seeded. + if (c.lang === 'bn') await api(office, `/students/${photoChild}/photo`, { method: 'DELETE' }); const [, childId, examClassId] = /\/children\/([^/]+)\/results\/([^/?]+)/.exec(guardian.url())!; expect(examClassId).toBe(ids.examClassId); diff --git a/apps/web/e2e/helpers.ts b/apps/web/e2e/helpers.ts index a3c243c..d0dd305 100644 --- a/apps/web/e2e/helpers.ts +++ b/apps/web/e2e/helpers.ts @@ -193,3 +193,21 @@ export async function api( expect(res.ok, `${init.method ?? 'GET'} ${path} → ${res.status}`).toBe(true); return (await res.json()) as T; } + +/** A 1 × 1 PNG: the API re-encodes it like any upload (sprint 1 P2). */ +export const TINY_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', + 'base64', +); + +/** Gives a student a photo through the API (multipart), as an admin would. */ +export async function apiUploadPhoto(token: string, studentId: string): Promise { + const form = new FormData(); + form.append('file', new Blob([TINY_PNG], { type: 'image/png' }), 'photo.png'); + const res = await fetch(`${API_URL}/students/${studentId}/photo`, { + method: 'PUT', + headers: { Authorization: `Bearer ${token}` }, + body: form, + }); + expect(res.ok, `PUT /students/${studentId}/photo → ${res.status}`).toBe(true); +} diff --git a/apps/web/messages/bn.json b/apps/web/messages/bn.json index b4de4a1..996900d 100644 --- a/apps/web/messages/bn.json +++ b/apps/web/messages/bn.json @@ -25,7 +25,8 @@ "imageTooBig": "ছবিটিতে পিক্সেল খুব বেশি (সর্বোচ্চ ৫০ মেগাপিক্সেল)। আরেকটু ছোট ছবি দিন।", "imageCannotShrink": "ছবিটি যথেষ্ট ছোট করা গেল না। অন্য একটি ছবি দিন।", "fileTooLarge": "ফাইলটি ৫ MB-এর বেশি বড়। ছোট একটি ফাইল দিন।", - "storageFull": "প্রতিষ্ঠানের ছবি রাখার জায়গা পূর্ণ। পুরোনো ছবি সরান বা জান্ত্রিককে জানান।" + "storageFull": "প্রতিষ্ঠানের ছবি রাখার জায়গা পূর্ণ। পুরোনো ছবি সরান বা জান্ত্রিককে জানান।", + "imageBusy": "এই মুহূর্তে অনেক ছবি প্রস্তুত হচ্ছে। একটু পরে আবার চেষ্টা করুন।" }, "login": { "title": "লগইন করুন", diff --git a/apps/web/messages/en.json b/apps/web/messages/en.json index b659afa..1905ec1 100644 --- a/apps/web/messages/en.json +++ b/apps/web/messages/en.json @@ -25,7 +25,8 @@ "imageTooBig": "The image has too many pixels (at most 50 megapixels). Choose a smaller one.", "imageCannotShrink": "This image could not be made small enough. Choose another one.", "fileTooLarge": "The file is larger than 5 MB. Choose a smaller one.", - "storageFull": "The institute's storage for images is full. Remove old images or contact Jantrik." + "storageFull": "The institute's storage for images is full. Remove old images or contact Jantrik.", + "imageBusy": "Many images are being prepared right now. Try again in a moment." }, "login": { "title": "Sign in", diff --git a/apps/web/src/app/(app)/setup/profile/page.tsx b/apps/web/src/app/(app)/setup/profile/page.tsx index 3518401..ca04f22 100644 --- a/apps/web/src/app/(app)/setup/profile/page.tsx +++ b/apps/web/src/app/(app)/setup/profile/page.tsx @@ -281,6 +281,7 @@ function ImageSlot({ slot, file }: { slot: InstituteImageSlot; file: FileRef | n disabled={pending} onChoose={(f) => upload.mutate(f)} onTooLarge={() => toast.error(tErrors('fileTooLarge'))} + opaque={false} testId={`image-${slot}-choose`} > {file ? t('imageReplace') : t('imageUpload')} diff --git a/apps/web/src/components/exams/guardian.tsx b/apps/web/src/components/exams/guardian.tsx index 1fdcd99..334e5b1 100644 --- a/apps/web/src/components/exams/guardian.tsx +++ b/apps/web/src/components/exams/guardian.tsx @@ -154,7 +154,7 @@ export function ChildReportCard({

    {t('publishedOn', { date: formatDate(q.data.publishedAt, locale) })}

    - + )} diff --git a/apps/web/src/components/exams/report-card.tsx b/apps/web/src/components/exams/report-card.tsx index 39ffa41..8f1f0ff 100644 --- a/apps/web/src/components/exams/report-card.tsx +++ b/apps/web/src/components/exams/report-card.tsx @@ -25,17 +25,32 @@ const WIDE = 'hidden sm:table-cell print:table-cell'; * Bangla first. What a card may show is decided by the API (parents' names only under decision * #19). Black on white in print whatever the theme. */ -export function ReportCardsPrint({ data }: { data: ReportCards }) { +export function ReportCardsPrint({ + data, + as = 'staff', +}: { + data: ReportCards; + /** Whose view: a guardian's photos come from their own route (/me/children/:id/photo). */ + as?: 'staff' | 'guardian'; +}) { return (
    {data.cards.map((card) => ( - + ))}
    ); } -function ReportCardPage({ data, card }: { data: ReportCards; card: ReportCard }) { +function ReportCardPage({ + data, + card, + as, +}: { + data: ReportCards; + card: ReportCard; + as: 'staff' | 'guardian'; +}) { const t = useTranslations('exams.print'); const locale = useLocale() as Locale; const label = useLabel(); @@ -95,6 +110,7 @@ function ReportCardPage({ data, card }: { data: ReportCards; card: ReportCard }) diff --git a/apps/web/src/components/image-upload.tsx b/apps/web/src/components/image-upload.tsx index 285a0b5..145b97c 100644 --- a/apps/web/src/components/image-upload.tsx +++ b/apps/web/src/components/image-upload.tsx @@ -4,14 +4,18 @@ import { UPLOAD_ACCEPT, UPLOAD_MAX_BYTES } from '@jantrik/shared'; import { ImageUpIcon } from 'lucide-react'; import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from 'react'; import { Button } from '@/components/ui/button'; +import { shrinkForUpload } from '@/lib/image-shrink'; /** - * A "choose image" button around a hidden file input. A file over 5 MB is refused here with the - * server's own message, before anything is sent; the server decides the rest by content. + * A "choose image" button around a hidden file input. The chosen image is shrunk in the browser + * first (image-shrink.ts: a phone photo becomes about 300 KB); a file still over 5 MB is refused + * here with the server's own message, before anything is sent. The server decides the rest by + * content. `opaque`: a photo (sent as JPEG); otherwise transparency is kept (PNG). */ export function ChooseImageButton({ onChoose, onTooLarge, + opaque, children, variant = 'outline', size, @@ -20,6 +24,7 @@ export function ChooseImageButton({ }: { onChoose: (file: File) => void; onTooLarge: () => void; + opaque: boolean; children: ReactNode; variant?: 'outline' | 'default' | 'ghost'; size?: 'sm' | 'default'; @@ -28,6 +33,7 @@ export function ChooseImageButton({ }) { const input = useRef(null); const id = useId(); + const [shrinking, setShrinking] = useState(false); return ( <> UPLOAD_MAX_BYTES) onTooLarge(); - else onChoose(file); + setShrinking(true); + void shrinkForUpload(file, opaque) + .then((ready) => (ready.size > UPLOAD_MAX_BYTES ? onTooLarge() : onChoose(ready))) + .finally(() => setShrinking(false)); }} />