Skip to content

Docs only: staff guide draft and DRAFT legal texts (for lawyer review) - #30

Draft
omerFixesBugs wants to merge 48 commits into
mainfrom
docs/staff-guide-and-legal-drafts
Draft

omerFixesBugs wants to merge 48 commits into
mainfrom
docs/staff-guide-and-legal-drafts

Conversation

@omerFixesBugs

Copy link
Copy Markdown
Owner

Docs only: no code, no migrations. Written during the unattended run of 2026-11-18/19 while the owner was away. Everything here is a draft.

The legal texts are drafts for lawyer review and are NOT legal advice. Each starts with the banner "DRAFT FOR LAWYER REVIEW — NOT LEGAL ADVICE. Not for publication or signature until reviewed by a lawyer qualified in Bangladesh." Placeholders ([Company legal name], [address], [governing court], [fee schedule], [hosting provider]) are left unfilled; unchecked law is marked [to verify].

Files

Depends on

#16, #18 and #17 through integration/sprint-1 (this branch starts there). Rebase after they merge. The guide's section 15 describes #21-#27; update it as those merge or change.

Bangladeshi law (web-checked, secondary sources, not the gazette texts)

  • The Personal Data Protection Ordinance, 2025 (Nov 2025) and its February 2026 amendment (localisation narrowed); Parliament passed the Personal Data Protection Bill, 2026 on 9 April 2026 (an Act from mid-April). Act number, commencement, rules, authority and breach duties: to verify.
  • Cyber Security Act 2023 → Cyber Security Ordinance 2025 (May 2025) → a cyber security law passed by Parliament in April 2026, amended June 2026: exact name and dates to verify.
  • ICT Act 2006, Payment and Settlement Systems Act 2024, Consumer Rights Protection Act 2009, BTRC A2P SMS licensing: named with sources; how they apply is to verify. Children Act 2013 and others: not checked.

Open questions for the lawyer (top ones; full list in docs/legal/README.md)

  1. Is the Personal Data Protection Act, 2026 in force, and do "data fiduciary / processor" fit this model?
  2. Consent for children's data: from whom, in what form, must the software record it?
  3. Must data (or a synchronised copy) stay in Bangladesh? Is hosting or backup in Singapore or Mumbai allowed?
  4. Breach notification: who notifies whom, how fast?
  5. SMS logs, audit logs, attendance and payments are kept with no end date: which need one, and does erasure require a permanent-delete feature before go-live?
  6. Which authorities may demand data directly, and may Jantrik tell the institute?
  7. BTRC rules for an institute's SMS to its own guardians; fees collected into personal bKash/Nagad numbers.
  8. Liability cap, contract form (click-through vs signed, Bangla vs English), courts or arbitration.

Open questions for the owner

Company details, hosting region, SMS provider (no gateway yet: nobody can receive a sign-in code until one is connected), off-site backups, fee schedule, export and deletion tools (not built), the breach notice period (drafts say 48 hours), and the guide's "To check" list.

🤖 Generated with Claude Code

omerFixesBugs and others added 30 commits November 16, 2026 13:01
…only the whole name (P1-I, the owner's answer): the name is split at spaces, punctuation and symbols, generic words are dropped (school, college, madrasa, academy, coaching, high, model, বিদ্যালয়, উচ্চ, স্কুল, মাদ্রাসা, কলেজ, কোচিং… and their spellings, GENERIC_NAME_WORDS), and every remaining word of 4 or more code points is refused. Generic words glued to the end of a word count without them too (শাপলাউচ্চবিদ্যালয় → শাপলা). Zero-width joiners are ignored on both sides. So শাপলা২০২৬১২৩৪ is refused for "শাপলা উচ্চ বিদ্যালয়" and kodomtola@2026 for "Kodom Tola School"; বিদ্যালয়২০২৬১২ and school2026xyz are not. The form and its messages say "the institute's name or a word from it"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…p 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 <noreply@anthropic.com>
…, 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…n 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 <noreply@anthropic.com>
…): 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 <noreply@anthropic.com>
…iles (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 <noreply@anthropic.com>
…ase 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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…lication 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 <noreply@anthropic.com>
…word 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 <noreply@anthropic.com>
…-J), and the password login test reads the stored hash through the owner login

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…n of the image in use here), in the production compose, the development compose and both CI jobs, and a test checks the four agree and are exact (P0 review leftover: the image floated and the upgrade steps never pulled it). deploy.md § 11 says how a new version is taken: a release changes the three together and `up -d` pulls it; a patched rebuild of the same tag with `compose.sh pull redis`. The deploy checklist mentions the login check's new refusals. How Redis starts is unchanged (it still runs as root)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…llow-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 <noreply@anthropic.com>
…e 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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…oto (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 <noreply@anthropic.com>
…head, logo, signature, seal, storage used), the photo dialog on the student page, the photo on the student page, the side peek, the guardian's child card and the report card through authenticated object URLs; lists keep initials (the 3 s budget); Playwright spec for both screens

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…he head's name label) and a student link with an id (the first /students/ link was the new-student button); found by CI's first run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…antrik_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 <noreply@anthropic.com>
…PrismaService, 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…: 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 <noreply@anthropic.com>
…ule (review of PR #17): NFKC (full-width letters and digits), lower case, ASCII digits, khanda ta's old encoding (ত + ্ + ZWJ) read as ৎ, and without spaces, punctuation, symbols or any invisible character (soft hyphen, zero-width space, word joiner…, not only ZWJ/ZWNJ). Names also split at zero-width spaces. So ko.dom2026xyzw, k-o-d-o-m-2026, full-width kodom, ko<soft hyphen>dom and a name typed "Kodom<ZWSP>Tola" are caught. Words of digits only are not distinctive ("Udvash 2026 Batch" no longer refuses mypass2026abc; the whole name still counts). More generic words in English letters and Bangla: balika, uchcha, bidyalay, madhyamik, prathomik, adarsha, sarkari, pilot, memorial, smriti, shaheed, shishu, ebtedayee, nursery and their spellings. Glued generic endings are cut only when they are 6 or more code points together, so "Australia" no longer yields the fragment "austr"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rigin (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 <noreply@anthropic.com>
…ere (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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
omerFixesBugs and others added 18 commits November 16, 2026 14:47
…t 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 <noreply@anthropic.com>
…e 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…e 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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…ion), files.md, database.md (kind-bound references), the plan (F1 corrected, Changed after the review R1-R10) and decisions-pending (the same, and the CSV imports as a backlog item)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…process, 2 per person, 503 IMAGE_BUSY at once, the slot given back when the response closes, a body not received in 60 s dropped); RequestTransaction.run refuses to nest; the store's transaction re-checks the session and the route's roles; the target is checked before decoding (no decode or quota for a wrong, deactivated or suspended target); sharp's 10 s timeout as 422 IMAGE_TIMEOUT; a replacement no bigger than the old file is never refused; a profile save takes the file lock first. Each with a test that failed first; plus tests for a suspended institute and a disabled member, the slow body on both routes, the ON CONFLICT path and the signature column's kind

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…itly when shrinking an image (an engine without it sends the original); the exams spec removes the demo child's photo in an afterEach, also when a check fails

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dGuard, no nesting), files.md, the plan and decisions-pending (Changed after the review, round 2: R11-R18, and the migrations edited in place)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…und): it is the outermost by definition, and a request made from inside a running job (the devices-attendance cutoff race tests) inherits that job's request context, which run()'s new nesting check turned into a 500. run() keeps the check for services; found by CI

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…adGuard ran (a client already gone gets no slot, on-finished's test; every slot comes back after 5 minutes at the latest); the revoked-session check runs before the transaction with Redis's 2 s deadline; a browser without imageOrientation decodes without it when the photo needs no turning (a small EXIF reader checks) and sends the original otherwise; the timeout test uses sharp's real message. Each code fix with a test that failed first; docs (round 3 in the plan and decisions-pending, files.md, auth.md)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…IN_URL, which PR #16 (P1-J) makes required: merged after #16 they failed with a missing variable (found by the day run's merge check of #16, #18 and #17 together). The schema ignores the key before #16, so the tests pass either way

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n for merging #17 after #16

Three additive conflicts, both sides kept: docs/database.md and docs/deploy.md list the password login (jantrik_login_app, DATABASE_LOGIN_URL) among the checked logins and the REPLICATION/CREATEROLE refusal; packages/db/test/helpers.ts imports LOGIN_URL and phoneSource. One semantic fix: #16's new login-prisma.service.spec.ts builds a LoginPrivileges without #17's replication and createRole (typecheck failed only when both are merged), now added as #17 did in the platform, ingest and prisma specs. Checked: typecheck of api, db, web and shared; the five login-check and env specs (83) and the login-privileges, users-password-hash and schema-safety DB tests (48)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… service, privacy policy, school data custody agreement) for lawyer review. Docs only, not formatted yet

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ardians, attendance with devices, fees, exams, staff, profile, appearance, and the features waiting in PRs #21-#27) and three legal drafts for lawyer review (terms of service, privacy policy, school data custody agreement with security, sub-processor and retention annexes that describe only what is built), plus docs/legal/README.md with the law checked (with sources), what is left to verify and the open questions. Formatted with Prettier. Not legal advice; a Bangla translation is needed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant