diff --git a/.env.example b/.env.example index 91a09eea..fd59550f 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 @@ -108,6 +115,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/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d3f60ec..e6525f6f 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 @@ -71,7 +74,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 +159,7 @@ jobs: --health-timeout 5s --health-retries 10 redis: - image: redis:7-alpine + image: redis:7.4.11-alpine ports: - 6379:6379 options: >- @@ -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 @@ -325,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/apps/api/package.json b/apps/api/package.json index 1cc212f2..c4baa455 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/app.module.ts b/apps/api/src/app.module.ts index 83434653..e447db31 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/auth/auth.module.ts b/apps/api/src/auth/auth.module.ts index 78e2c2e4..8c4c0a24 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 ec75be88..a883375b 100644 --- a/apps/api/src/auth/auth.service.ts +++ b/apps/api/src/auth/auth.service.ts @@ -16,11 +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, 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'; @@ -34,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, @@ -79,10 +81,12 @@ export class AuthService { }, ); - const user = await findUserForLogin(this.prisma.client, { phone, email }); + // 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(user?.password_hash, password); - if (!user || !ok) throw invalidCredentials(); + 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 00000000..d92921c0 --- /dev/null +++ b/apps/api/src/auth/login-isolation.spec.ts @@ -0,0 +1,65 @@ +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); +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', + '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); + 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-lookup.ts b/apps/api/src/auth/login-lookup.ts index 5a89856f..6b999f77 100644 --- a/apps/api/src/auth/login-lookup.ts +++ b/apps/api/src/auth/login-lookup.ts @@ -5,20 +5,37 @@ export interface LoginUser { id: string; name: string; locale: 'bn' | 'en'; - password_hash: 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_hash + SELECT id::text, name, locale::text AS locale FROM auth_find_user_for_login(${by.phone ?? null}, ${by.email ?? null})`; return rows[0]; } +/** + * 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 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 { tenant_id: string; tenant_slug: string; 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 00000000..c5a83dee --- /dev/null +++ b/apps/api/src/auth/login-prisma.service.spec.ts @@ -0,0 +1,141 @@ +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, + replication: false, + createRole: 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, + replication: p.replication, + create_role: p.createRole, + 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), 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], + where: Where = HERE, +) => { + let i = 0; + return { + $queryRaw: vi.fn((strings: TemplateStringsArray) => { + 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 }]); + }), + }; +}; + +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], + loginWhere: Where = HERE, +) { + const warn = vi.fn(); + const s = Object.create(LoginPrismaService.prototype) as LoginPrismaService; + Object.assign(s, { + client: client(loginCanRun, privileges, loginWhere), + 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.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(); + 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 00000000..bf165409 --- /dev/null +++ b/apps/api/src/auth/login-prisma.service.ts @@ -0,0 +1,118 @@ +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), 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({ + 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, + ); + // 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, 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; + } + 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.', + ); + } + 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 { + await this.client.$disconnect(); + } +} diff --git a/apps/api/src/auth/password-settings.service.ts b/apps/api/src/auth/password-settings.service.ts index faadf2a8..4a8469be 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/src/auth/password.service.spec.ts b/apps/api/src/auth/password.service.spec.ts new file mode 100644 index 00000000..8ce3de0e --- /dev/null +++ b/apps/api/src/auth/password.service.spec.ts @@ -0,0 +1,64 @@ +import { hash, verify } from '@node-rs/argon2'; +import { PasswordService } from './password.service.js'; + +// 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, verify: vi.fn(real.verify) }; +}); + +describe('PasswordService.verify', () => { + const service = new PasswordService(); + const password = 'correct horse battery staple'; + let stored: string; + + beforeAll(async () => { + stored = await service.hash(password); + }); + + beforeEach(() => { + vi.mocked(verify).mockClear(); + }); + + 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 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.verify(costly, password)).toBe(true); + }); + + it.each([ + ['no user', undefined], + ['no password', null], + ['not a hash', 'not-a-real-hash'], + ['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. + 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 bd952230..084cd800 100644 --- a/apps/api/src/auth/password.service.ts +++ b/apps/api/src/auth/password.service.ts @@ -1,10 +1,40 @@ 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 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 COST_CEILING = { memoryCost: 65_536, timeCost: 10, parallelism: 4 }; + +/** + * 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.saltLen >= 8 && + o.saltLen <= 64 && + o.outputLen >= 16 && + o.outputLen <= 64 + ); + } catch { + return false; + } +} + /** * 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,12 +49,12 @@ 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. 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; diff --git a/apps/api/src/common/decorators.ts b/apps/api/src/common/decorators.ts index 2ef1242a..74d9eec1 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/config/dev-lan.spec.ts b/apps/api/src/config/dev-lan.spec.ts index 6d138c2a..050f2659 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 7ee964a8..2f19f97d 100644 --- a/apps/api/src/config/env.ts +++ b/apps/api/src/config/env.ts @@ -26,7 +26,13 @@ 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 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() .default('http://localhost:3000') @@ -34,7 +40,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/* @@ -52,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); @@ -67,6 +77,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 @@ -140,6 +155,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/config/production-env.spec.ts b/apps/api/src/config/production-env.spec.ts index 807884e8..6684244e 100644 --- a/apps/api/src/config/production-env.spec.ts +++ b/apps/api/src/config/production-env.spec.ts @@ -1,10 +1,12 @@ 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, DATABASE_ADMIN_SECRETS, + normaliseOrigin, trustsAnyClient, unsafeOrigin, } from './production-env.js'; @@ -17,6 +19,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 +159,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), @@ -169,6 +173,97 @@ 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('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', + // Required once PR #16 (P1-J) is merged; ignored by the schema before that. + 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), + }; + 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', + DATABASE_PLATFORM_URL: 'postgresql://jantrik_platform_app:x@localhost:5432/jantrik', + // Required once PR #16 (P1-J) is merged; ignored by the schema before that. + 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), + }; + 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)); @@ -209,7 +304,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 +443,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 +463,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 88f98fc5..46816e83 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'; @@ -152,6 +157,7 @@ export const DATABASE_ADMIN_SECRETS = [ 'DB_APP_PASSWORD', 'DB_PLATFORM_PASSWORD', 'DB_INGEST_PASSWORD', + 'DB_LOGIN_PASSWORD', ] as const; /** @@ -188,6 +194,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; } @@ -237,7 +244,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) { @@ -263,7 +270,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 +300,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 +337,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/src/exams/results/exam-results.service.ts b/apps/api/src/exams/results/exam-results.service.ts index f33f0ea2..12200a95 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 d76a9fc9..0e7b2498 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/files/file-store-access.spec.ts b/apps/api/src/files/file-store-access.spec.ts new file mode 100644 index 00000000..2fb91925 --- /dev/null +++ b/apps/api/src/files/file-store-access.spec.ts @@ -0,0 +1,77 @@ +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'; + +/** 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) || + new RegExp(String.raw`\b(${RELATIONS.join('|')})\s*:`).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', + // 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", + ]; + 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 00000000..9c8a420c --- /dev/null +++ b/apps/api/src/files/file-store.ts @@ -0,0 +1,55 @@ +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. `replaces`: + * the file this one replaces, counted as freed, so a replacement that does not grow the total + * is allowed near the cap, and one no bigger than the old file even over it. The caller MUST + * then delete that file in the same transaction (after pointing the row at the new one), or + * the total ends above the cap. Take `lock()` before reading which file is replaced. + */ + 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. */ + 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 00000000..21840941 --- /dev/null +++ b/apps/api/src/files/files.module.ts @@ -0,0 +1,113 @@ +import { + Global, + Inject, + Injectable, + Module, + UseGuards, + 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, type ProcessedImage } from './image.service.js'; +import { PostgresFileStore } from './postgres-file-store.js'; +import { UploadGuard, UploadLimits } from './upload-limits.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. UploadGuard + * runs first: a bounded number of uploads in flight per process and per person, a slot given + * back when the response closes, and a body that has not arrived in 60 s dropped. + */ +export const ImageUpload = () => + applyDecorators( + UseGuards(UploadGuard), + UseInterceptors( + FileInterceptor('file', { limits: { fileSize: UPLOAD_MAX_BYTES, files: 1, fields: 0 } }), + ), + ); + +/** 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( + @Inject(FILE_STORE) private readonly files: FileStore, + private readonly images: ImageService, + private readonly limiter: RateLimiter, + private readonly context: RequestContext, + ) {} + + async prepare(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, + }); + return { kind, ...(await this.images.process(kind, upload.buffer)) }; + } + + store(image: PreparedImage, replaces: string | null): Promise { + return this.files.put(image, { replaces }); + } +} + +/** + * 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, + UploadLimits, + UploadGuard, + { provide: FILE_STORE, useClass: PostgresFileStore }, + ], + exports: [ImageService, ImageUploads, UploadLimits, UploadGuard, FILE_STORE], +}) +export class FilesModule {} 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 00000000..0f503e7b --- /dev/null +++ b/apps/api/src/files/image.service.spec.ts @@ -0,0 +1,241 @@ +import { randomBytes } from 'node:crypto'; +import { crc32, deflateSync } from 'node:zlib'; +import sharp from 'sharp'; +import { ImageService, Slots, imageFailure, 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('imageFailure (review round 2)', () => { + it("maps sharp's timeout to 422 IMAGE_TIMEOUT and anything else to IMAGE_INVALID", () => { + // sharp 0.35.5's own message (src/common.cc): "timeout: N% complete". + const timeout = imageFailure(new Error('timeout: 37% complete')); + expect([timeout.getStatus(), (timeout.getResponse() as { code: string }).code]).toEqual([ + 422, + 'IMAGE_TIMEOUT', + ]); + const other = imageFailure(new Error('Input buffer contains unsupported image format')); + expect((other.getResponse() as { code: string }).code).toBe('IMAGE_INVALID'); + }); +}); + +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(); + 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 { slots: Slots }).slots.active); + }, 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 00000000..ffdbe780 --- /dev/null +++ b/apps/api/src/files/image.service.ts @@ -0,0 +1,237 @@ +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; +/** 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 + * 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 readonly slots = new Slots(MAX_PARALLEL, MAX_WAITING); + + async process(kind: StoredFileKind, input: Buffer): Promise { + await this.slots.acquire(); + try { + return await processImage(kind, input); + } finally { + this.slots.release(); + } + } +} + +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'); + +/** Seconds a decode or an encode may take (sharp's own timer), well inside the queue's turn. */ +const SHARP_TIMEOUT = { seconds: 10 }; + +/** sharp's error as the API's: its timeout → 422 IMAGE_TIMEOUT, anything else IMAGE_INVALID. */ +export function imageFailure(error: unknown) { + return /timeout/i.test((error as Error)?.message ?? '') + ? apiError(422, 'IMAGE_TIMEOUT', 'The image took too long to process; try a simpler one') + : invalid(); +} + +/** 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().timeout(SHARP_TIMEOUT).toBuffer({ resolveWithObject: true }); + } catch (error) { + throw imageFailure(error); + } + + 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' }); + let encoded: RawImage; + try { + encoded = await encoder + .apply(sized) + .timeout(SHARP_TIMEOUT) + .toBuffer({ resolveWithObject: true }); + } catch (error) { + throw imageFailure(error); + } + const { data, info } = encoded; + 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/apps/api/src/files/postgres-file-store.ts b/apps/api/src/files/postgres-file-store.ts new file mode 100644 index 00000000..e0293620 --- /dev/null +++ b/apps/api/src/files/postgres-file-store.ts @@ -0,0 +1,146 @@ +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, 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. + 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); + const replaced = opts.replaces + ? (( + await tx.storedFile.findUnique({ + where: { id: opts.replaces }, + select: { sizeBytes: true }, + }) + )?.sizeBytes ?? 0) + : 0; + // A replacement no bigger than the file it replaces is never refused, even when the total is + // over a lowered cap: it cannot make it worse (the caller deletes the old file). + if (size > replaced && bytesUsed - replaced + 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 }; +} diff --git a/apps/api/src/files/upload-limits.spec.ts b/apps/api/src/files/upload-limits.spec.ts new file mode 100644 index 00000000..fd19886b --- /dev/null +++ b/apps/api/src/files/upload-limits.spec.ts @@ -0,0 +1,123 @@ +import { EventEmitter } from 'node:events'; +import type { Request, Response } from 'express'; +import { + UPLOAD_BODY_TIMEOUT_MS, + UPLOAD_SLOT_BACKSTOP_MS, + UPLOADS_IN_FLIGHT, + UPLOADS_IN_FLIGHT_PER_USER, + UploadLimits, +} from './upload-limits.js'; + +// Review round 2: uploads in flight are capped per process and per person before multer reads a +// byte, and every slot is given back when the response closes (finished, aborted or failed). + +function exchange() { + const req = Object.assign(new EventEmitter(), { destroy: vi.fn(), destroyed: false }); + const res = Object.assign(new EventEmitter(), { + destroyed: false, + writableFinished: false, + socket: { writable: true } as { writable: boolean } | null, + }); + return { req, res, asReq: req as unknown as Request, asRes: res as unknown as Response }; +} + +const code = (fn: () => void) => { + try { + fn(); + } catch (e) { + const err = e as { getStatus(): number; getResponse(): { code: string } }; + return `${err.getStatus()} ${err.getResponse().code}`; + } + return 'ok'; +}; + +describe('UploadLimits', () => { + afterEach(() => vi.useRealTimers()); + + it(`lets a person have ${UPLOADS_IN_FLIGHT_PER_USER} uploads in flight; the next gets 503 IMAGE_BUSY`, () => { + const limits = new UploadLimits(); + const a = exchange(); + const b = exchange(); + limits.enter('u1', a.asReq, a.asRes); + limits.enter('u1', b.asReq, b.asRes); + const c = exchange(); + expect(code(() => limits.enter('u1', c.asReq, c.asRes))).toBe('503 IMAGE_BUSY'); + // Someone else is not affected. + expect(code(() => limits.enter('u2', c.asReq, c.asRes))).toBe('ok'); + expect(limits.inFlight).toBe(3); + }); + + it(`caps the process at ${UPLOADS_IN_FLIGHT} uploads in flight`, () => { + const limits = new UploadLimits(); + for (let i = 0; i < UPLOADS_IN_FLIGHT; i++) { + const x = exchange(); + limits.enter(`user-${i}`, x.asReq, x.asRes); + } + const x = exchange(); + expect(code(() => limits.enter('one-more', x.asReq, x.asRes))).toBe('503 IMAGE_BUSY'); + }); + + it('gives the slot back when the response closes, once, whatever ended it', () => { + const limits = new UploadLimits(); + const a = exchange(); + limits.enter('u1', a.asReq, a.asRes); + const b = exchange(); + limits.enter('u1', b.asReq, b.asRes); + a.res.emit('close'); // finished + b.res.emit('close'); // aborted by the client: the same event + a.res.emit('close'); // a second close changes nothing + expect(limits.inFlight).toBe(0); + const c = exchange(); + limits.enter('u1', c.asReq, c.asRes); + limits.enter('u1', exchange().asReq, exchange().asRes); + expect(limits.inFlight).toBe(2); + }); + + it('takes no slot for a client already gone (its one close event was before the guard ran)', () => { + const limits = new UploadLimits(); + // The socket closed while the global guards awaited Redis: Node destroyed the response and + // emitted its only 'close' before enter() could listen for it. + const gone = exchange(); + gone.res.emit('close'); + gone.res.destroyed = true; + gone.res.socket = null; + gone.req.destroyed = true; + expect(() => limits.enter('u1', gone.asReq, gone.asRes)).toThrow(); + const ended = exchange(); + ended.res.writableFinished = true; + expect(() => limits.enter('u1', ended.asReq, ended.asRes)).toThrow(); + expect(limits.inFlight).toBe(0); + // The person can still upload twice. + limits.enter('u1', exchange().asReq, exchange().asRes); + limits.enter('u1', exchange().asReq, exchange().asRes); + expect(limits.inFlight).toBe(2); + }); + + it('a slot whose close never comes is given back after the backstop', () => { + vi.useFakeTimers(); + const limits = new UploadLimits(); + const lost = exchange(); + limits.enter('u1', lost.asReq, lost.asRes); + lost.req.emit('end'); + vi.advanceTimersByTime(UPLOAD_SLOT_BACKSTOP_MS); + expect(limits.inFlight).toBe(0); + lost.res.emit('close'); // a late close changes nothing + expect(limits.inFlight).toBe(0); + }); + + it(`drops a body that has not arrived within ${UPLOAD_BODY_TIMEOUT_MS / 1000} s; one that has is left alone`, () => { + vi.useFakeTimers(); + const limits = new UploadLimits(); + const slow = exchange(); + const quick = exchange(); + limits.enter('u1', slow.asReq, slow.asRes); + limits.enter('u2', quick.asReq, quick.asRes); + quick.req.emit('end'); // its body arrived + vi.advanceTimersByTime(UPLOAD_BODY_TIMEOUT_MS); + expect(slow.req.destroy).toHaveBeenCalledTimes(1); + expect(quick.req.destroy).not.toHaveBeenCalled(); + slow.res.emit('close'); + quick.res.emit('close'); + expect(limits.inFlight).toBe(0); + }); +}); diff --git a/apps/api/src/files/upload-limits.ts b/apps/api/src/files/upload-limits.ts new file mode 100644 index 00000000..edfb8bf9 --- /dev/null +++ b/apps/api/src/files/upload-limits.ts @@ -0,0 +1,89 @@ +import { HttpException, Injectable, type CanActivate, type ExecutionContext } from '@nestjs/common'; +import type { Request, Response } from 'express'; +import { apiError } from '../common/api-error.js'; +import { RequestContext } from '../common/request-context.js'; + +/** Uploads whose body may be in memory at once, per API process (5 MB each at most). */ +export const UPLOADS_IN_FLIGHT = 16; +/** Per person: an admin's second tab is fine; a script holding many bodies is not. */ +export const UPLOADS_IN_FLIGHT_PER_USER = 2; +/** A body not fully received by then is dropped (5 MB at 0.75 Mbps takes about 55 s). */ +export const UPLOAD_BODY_TIMEOUT_MS = 60_000; +/** A slot whose response somehow never closes is given back after this anyway (a backstop). */ +export const UPLOAD_SLOT_BACKSTOP_MS = 5 * 60_000; + +/** + * The client is gone, or the answer was sent: on-finished's own test (Express's dependency). + * Then the response's one 'close' event may already be past, and a slot taken now would never + * be given back. + */ +function finished(req: Request, res: Response): boolean { + return ( + req.destroyed || res.destroyed || res.writableFinished || !res.socket || !res.socket.writable + ); +} + +const busy = () => apiError(503, 'IMAGE_BUSY', 'Too many uploads at once; try again in a moment'); + +/** + * Bounds what uploads can hold in memory (review round 2). The upload routes read their body + * with no request transaction (@OwnTransaction), into memory (multer), so nothing else limited + * how many bodies could be in flight. A slot is taken before multer reads a byte, refused at once + * with 503 IMAGE_BUSY when the process or the person has too many, and given back when the + * response closes, however it ends (sent, failed, or the client went away), or after + * UPLOAD_SLOT_BACKSTOP_MS at the latest; a client already gone gets no slot. A body that has not + * arrived within UPLOAD_BODY_TIMEOUT_MS is dropped, which closes the response too. + */ +@Injectable() +export class UploadLimits { + private total = 0; + private readonly perUser = new Map(); + + get inFlight(): number { + return this.total; + } + + enter(userId: string, req: Request, res: Response): void { + // The client left while the global guards awaited Redis (review round 3): no slot at all. + if (finished(req, res)) throw new HttpException('Client closed the request', 499); + const mine = this.perUser.get(userId) ?? 0; + if (this.total >= UPLOADS_IN_FLIGHT || mine >= UPLOADS_IN_FLIGHT_PER_USER) throw busy(); + this.total++; + this.perUser.set(userId, mine + 1); + const timer = setTimeout(() => req.destroy(), UPLOAD_BODY_TIMEOUT_MS); + req.once('end', () => clearTimeout(timer)); + let released = false; + const release = () => { + if (released) return; + released = true; + clearTimeout(timer); + clearTimeout(backstop); + this.total--; + const left = (this.perUser.get(userId) ?? 1) - 1; + if (left > 0) this.perUser.set(userId, left); + else this.perUser.delete(userId); + }; + const backstop = setTimeout(release, UPLOAD_SLOT_BACKSTOP_MS); + backstop.unref?.(); + res.once('close', release); + } +} + +/** The guard of the upload routes: runs after the token and roles guards, before multer. */ +@Injectable() +export class UploadGuard implements CanActivate { + constructor( + private readonly limits: UploadLimits, + private readonly context: RequestContext, + ) {} + + canActivate(ctx: ExecutionContext): boolean { + const http = ctx.switchToHttp(); + this.limits.enter( + this.context.requirePrincipal().userId, + http.getRequest(), + http.getResponse(), + ); + return true; + } +} diff --git a/apps/api/src/ingest/ingest-prisma.service.spec.ts b/apps/api/src/ingest/ingest-prisma.service.spec.ts index 38b36854..e7a0d4ef 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/institute/institute-profile.module.ts b/apps/api/src/institute/institute-profile.module.ts new file mode 100644 index 00000000..8d47a212 --- /dev/null +++ b/apps/api/src/institute/institute-profile.module.ts @@ -0,0 +1,311 @@ +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 { 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'; +import { + ImageUpload, + ImageUploads, + sendStoredImage, + 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) {} + +/** 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 = /[ঀ-৿]/; + +/** Who may change the profile (the routes' @Roles), checked again when an image is stored. */ +const EDITORS = ['OWNER', 'ADMIN'] as const; + +/** + * 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, + private readonly transaction: RequestTransaction, + @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(); + // The file lock (an image upload holds it from before it creates the row to its commit), so a + // first image racing this first save is seen here and the save is audited as an UPDATE. + await this.files.lock(); + 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). + * 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) { + // A suspended institute or a lost role costs no decoding and no quota. + await this.transaction.run(async () => undefined, { roles: EDITORS }); + 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(); + }, + { roles: EDITORS }, + ); + } + + 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. 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(); + 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 { 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; + } +} + +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') + @OwnTransaction() + @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 feea0a27..d4114da2 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/platform/platform-prisma.service.spec.ts b/apps/api/src/platform/platform-prisma.service.spec.ts index 94978120..75407991 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 c3fdb98a..80fb6a6f 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/apps/api/src/students/student-admin.service.ts b/apps/api/src/students/student-admin.service.ts index 7cdaf83f..8a88db28 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 00000000..b3a57a25 --- /dev/null +++ b/apps/api/src/students/student-photo.service.ts @@ -0,0 +1,126 @@ +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 { RequestTransaction } from '../tenancy/request-transaction.service.js'; +import { StudentAccess } from './student-access.service.js'; +import { StudentAdminService } from './student-admin.service.js'; + +/** Who may change a photo (the route's @Roles), checked again when the photo is stored. */ +const WRITERS = ['OWNER', 'ADMIN'] as const; + +/** + * 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, + private readonly transaction: RequestTransaction, + @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; + } + + /** + * 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 { + // A wrong or deactivated student, or a suspended institute, costs no decoding and no quota. + await this.transaction.run(() => this.writable(studentId), { roles: WRITERS }); + 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); + }, + { roles: WRITERS }, + ); + } + + 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 6b0ca9f5..074e0316 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 { RequireModule, Roles } from '../common/decorators.js'; +import type { Request, Response } from 'express'; +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'; 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,30 @@ 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') + @OwnTransaction() + @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 +481,7 @@ export class GuardiansController { StudentsService, StudentAdminService, StudentCodesService, + StudentPhotoService, GuardianLinker, StudentAccess, ], diff --git a/apps/api/src/tenancy/request-transaction.service.spec.ts b/apps/api/src/tenancy/request-transaction.service.spec.ts new file mode 100644 index 00000000..d2de29f4 --- /dev/null +++ b/apps/api/src/tenancy/request-transaction.service.spec.ts @@ -0,0 +1,38 @@ +import type { RequestContext } from '../common/request-context.js'; +import type { PrismaService } from '../prisma/prisma.service.js'; +import { RequestTransaction } from './request-transaction.service.js'; + +// Review round 2: run() inside a request that already has its transaction would replace the +// outer transaction and its afterCommit queue in the request context (and wait on the outer +// transaction's locks from a second connection). It refuses instead. + +describe('RequestTransaction.run', () => { + it('refuses to run inside a request transaction (nothing is started)', async () => { + const withContext = vi.fn(); + const prisma = { client: { $transaction: withContext } } as unknown as PrismaService; + const context = { + tx: {}, + requirePrincipal: () => ({ userId: 'u', sessionId: 's', tenantId: 't' }), + } as unknown as RequestContext; + const tx = new RequestTransaction(prisma, context, {} as never); + const fn = vi.fn(); + await expect(tx.run(fn)).rejects.toThrow(/already/); + expect(fn).not.toHaveBeenCalled(); + expect(withContext).not.toHaveBeenCalled(); + }); + + it('checks the session in Redis before opening the transaction, with a deadline (review round 3)', async () => { + const transaction = vi.fn(); + const prisma = { client: { $transaction: transaction } } as unknown as PrismaService; + const context = { + tx: undefined, + requirePrincipal: () => ({ userId: 'u', sessionId: 's', tenantId: 't' }), + } as unknown as RequestContext; + // A Redis that never answers: 503 after the deadline, and no connection was taken. + const silent = { exists: () => new Promise(() => undefined) }; + const tx = new RequestTransaction(prisma, context, silent as never); + const failure = await tx.run(vi.fn(), { roles: ['ADMIN'] }).catch((e: unknown) => e); + expect((failure as { getStatus(): number }).getStatus()).toBe(503); + expect(transaction).not.toHaveBeenCalled(); + }); +}); 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 00000000..c13f54d9 --- /dev/null +++ b/apps/api/src/tenancy/request-transaction.service.ts @@ -0,0 +1,127 @@ +import { + ForbiddenException, + Inject, + Injectable, + InternalServerErrorException, + UnauthorizedException, +} from '@nestjs/common'; +import { withContext, type Role, type TenantTx } from '@jantrik/db'; +import type { Redis } from 'ioredis'; +import { RequestContext, type Principal } from '../common/request-context.js'; +import { revokedSessionKey } from '../common/revocation.js'; +import { PrismaService } from '../prisma/prisma.service.js'; +import { REDIS_CALL_TIMEOUT_MS, withRedisDeadline } from '../redis/redis-deadline.js'; +import { REDIS } from '../redis/redis.constants.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. + * Such a route passes `roles`: the guards checked the session and the roles when the request + * arrived, which can be a minute before the store, so they are checked again in the transaction. + */ +@Injectable() +export class RequestTransaction { + constructor( + private readonly prisma: PrismaService, + private readonly context: RequestContext, + @Inject(REDIS) private readonly redis: Redis, + ) {} + + /** For services on @OwnTransaction routes. */ + async run( + fn: () => Promise, + opts: { userScoped?: boolean; roles?: readonly Role[] } = {}, + ): Promise { + // Inside a request transaction this would replace it (and its afterCommit queue) in the + // request context, and wait on its locks from a second connection. + if (this.context.tx) { + throw new InternalServerErrorException( + 'RequestTransaction.run: a transaction is already open', + ); + } + return this.around(fn, opts); + } + + /** + * TenantContextInterceptor's entry: the outermost transaction by definition, so no nesting + * check. (A request made from inside a running job, as some tests do, inherits the job's + * request context; the interceptor's transaction replaces it there, as it always has.) + */ + async around( + fn: () => Promise, + opts: { userScoped?: boolean; roles?: readonly Role[] } = {}, + ): Promise { + const principal = this.context.requirePrincipal(); + // The session first, outside the transaction and with Redis's deadline (review round 3): a + // slow Redis never holds a pooled connection. + if (opts.roles) { + await withRedisDeadline( + () => this.sessionLive(principal), + REDIS_CALL_TIMEOUT_MS, + 'SERVICE_UNAVAILABLE', + ); + } + 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); + if (opts.roles) await this.recheckRoles(tx, opts.roles); + 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; + } + + /** The session not revoked since the guards checked it. */ + private async sessionLive(principal: Principal): Promise { + if (await this.redis.exists(revokedSessionKey(principal.sessionId))) { + throw new UnauthorizedException(); + } + } + + /** The person still holding one of `roles` here, read in the transaction. */ + private async recheckRoles(tx: TenantTx, roles: readonly Role[]) { + const held = await tx.$queryRaw<{ role: Role }[]>` + SELECT role FROM memberships + WHERE user_id = app_current_user_id() AND status = 'ACTIVE'`; + if (!held.some((m) => roles.includes(m.role))) { + throw new ForbiddenException('Your role here has changed'); + } + } +} + +/** + * 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 89d30bc8..79177366 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 66f6fb6c..55317abb 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.around(() => 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/devices-ingest-env.e2e-spec.ts b/apps/api/test/devices-ingest-env.e2e-spec.ts index 961b95b8..b3cd1d12 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/test/files.e2e-spec.ts b/apps/api/test/files.e2e-spec.ts new file mode 100644 index 00000000..d1269f82 --- /dev/null +++ b/apps/api/test/files.e2e-spec.ts @@ -0,0 +1,420 @@ +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'; +import sharp from 'sharp'; +import { + addMember, + bearer, + createHarness, + createTenant, + http, + otpLogin, + type Harness, +} from './support/harness.js'; +import { platform, platformAdminCookie } from './support/platform.js'; +import { school, type School } from './support/school.js'; +import { UploadLimits } from '../src/files/upload-limits.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); + // Checked before the upload is decoded (review round 2): not a 422 for a non-image. + await put(admin, student, Buffer.from('not an image'), 'x.jpg').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'); + // Before decoding: a non-image gets the same 409, not a 422 (review round 2). + const garbage = await put(t.admin, student, Buffer.from('not an image'), 'x.jpg').expect(409); + expect(garbage.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 }); + // 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); + // Even when the total is over the cap (a lowered cap): a replacement no bigger than the old + // file is allowed; a new photo is not (review round 2). + await withTenant(h.prisma, t.tenantId, (tx) => + tx.storedFileUsage.updateMany({ data: { bytesUsed: { increment: size } } }), + ); + await put(t.admin, t.a[0]!.id, image).expect(200); + await put(t.admin, t.b[0]!.id, image).expect(413); + }); + + describe('uploads in flight (reviews)', () => { + let port: number; + const boundary = 'jantrik-slow-upload'; + + beforeAll(async () => { + const server = h.app.getHttpServer() as Server; + if (!server.listening) await new Promise((r) => server.listen(0, '127.0.0.1', r)); + port = (server.address() as AddressInfo).port; + }); + + /** + * A multipart upload whose body stalls after 64 bytes for `stallMs`, then completes (or is + * dropped by the client with `abort`). Resolves with the status (0 when aborted). + */ + const slowUpload = ( + path: string, + token: string, + image: Buffer, + opts: { stallMs: number; abort?: boolean }, + ) => + new Promise((resolve, reject) => { + 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 req = httpRequest( + { + host: '127.0.0.1', + port, + method: 'PUT', + path, + headers: { + Authorization: `Bearer ${token}`, + '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', (e) => (opts.abort ? resolve(0) : reject(e))); + req.write(head); + req.write(image.subarray(0, 64)); + setTimeout(() => { + if (opts.abort) req.destroy(); + else req.end(Buffer.concat([image.subarray(64), tail])); + }, opts.stallMs); + }); + 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 limits = () => h.app.get(UploadLimits); + + it.each([ + ['a student photo', () => `/students/${s.a[0]!.id}/photo`], + ['the institute logo', () => '/institute/profile/logo'], + ])('%s: no database transaction is open while the body arrives', async (_n, path) => { + const image = await photo(400, 500, '#aa6633'); + const status = slowUpload(path(), s.admin, image, { stallMs: 2_500 }); + // Sampled every 100 ms while the body is stalled (review round 2); the short store + // transaction after it is allowed, so sampling stops before the body completes. + let most = 0; + const until = Date.now() + 1_900; + while (Date.now() < until) { + most = Math.max(most, await openTransactions()); + await new Promise((r) => setTimeout(r, 100)); + } + expect(await status).toBe(200); + expect(most).toBe(0); + }); + + it('a person has at most two uploads in flight; the third gets 503 IMAGE_BUSY at once', async () => { + const image = await photo(300, 300, '#336655'); + const first = slowUpload(`/students/${s.a[1]!.id}/photo`, owner, image, { stallMs: 1_500 }); + const second = slowUpload(`/students/${s.a[2]!.id}/photo`, owner, image, { + stallMs: 1_500, + }); + await vi.waitFor(() => expect(limits().inFlight).toBe(2)); + const third = await put(owner, s.b[0]!.id, image).expect(503); + expect(third.body.code).toBe('IMAGE_BUSY'); + expect(await Promise.all([first, second])).toEqual([200, 200]); + await vi.waitFor(() => expect(limits().inFlight).toBe(0)); + }); + + it('an upload the client drops gives its slot back', async () => { + const image = await photo(300, 300, '#665533'); + const dropped = slowUpload(`/students/${s.b[0]!.id}/photo`, owner, image, { + stallMs: 500, + abort: true, + }); + await vi.waitFor(() => expect(limits().inFlight).toBe(1)); + expect(await dropped).toBe(0); + await vi.waitFor(() => expect(limits().inFlight).toBe(0)); + }); + + it('an admin downgraded while the body arrives gets 403, and nothing is stored', async () => { + const t = await school(h); + const m = await addMember(h, t.tenantId, { roles: ['ADMIN'] }); + const token = (await otpLogin(h, m.phone)).accessToken; + const before = await usage(t.tenantId); + const status = slowUpload(`/students/${t.a[0]!.id}/photo`, token, await photo(), { + stallMs: 1_500, + }); + await vi.waitFor(() => expect(limits().inFlight).toBe(1)); + await h.access.setMemberRoles(t.tenantId, m.userId, ['TEACHER']); + expect(await status).toBe(403); + const logo = slowUpload('/institute/profile/signature', token, await photo(), { + stallMs: 10, + }); + expect(await logo).toBe(403); + expect(await usage(t.tenantId)).toEqual(before); + }); + }); + + it('a suspended institute or a disabled member stores nothing (403)', async () => { + const t = await school(h); + const m = await addMember(h, t.tenantId, { roles: ['ADMIN'] }); + const token = (await otpLogin(h, m.phone)).accessToken; + const before = await usage(t.tenantId); + // A disabled membership (the roles cache still says ADMIN: the transaction's re-check refuses). + await withTenant(h.prisma, t.tenantId, (tx) => + tx.membership.updateMany({ where: { userId: m.userId }, data: { status: 'DISABLED' } }), + ); + await put(token, t.a[0]!.id, await photo()).expect(403); + await http(h) + .put('/institute/profile/logo') + .set(bearer(token)) + .attach('file', await photo(), { filename: 'logo.jpg', contentType: 'image/jpeg' }) + .expect(403); + // The whole institute suspended by the platform. + await platform(h, await platformAdminCookie(h)) + .post(`/platform/institutes/${t.tenantId}/suspend`) + .send({ reason: 'invoice unpaid' }) + .expect(200); + await put(t.admin, t.a[0]!.id, await photo()).expect(403); + await http(h) + .put('/institute/profile/logo') + .set(bearer(t.admin)) + .attach('file', await photo(), { filename: 'logo.jpg', contentType: 'image/jpeg' }) + .expect(403); + expect(await usage(t.tenantId)).toEqual(before); + }); + + 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 00000000..1fd55118 --- /dev/null +++ b/apps/api/test/institute-profile.e2e-spec.ts @@ -0,0 +1,205 @@ +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('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]); + const created = (await audits(t.id)).filter((r) => r.action === 'CREATE'); + expect(created).toHaveLength(1); + } + }); + + 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/apps/api/test/password-set.e2e-spec.ts b/apps/api/test/password-set.e2e-spec.ts index 6c9cdff0..4faa482d 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/api/test/password.e2e-spec.ts b/apps/api/test/password.e2e-spec.ts index 6ba9c30a..f7620478 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 () => { diff --git a/apps/api/test/support/harness.ts b/apps/api/test/support/harness.ts index 03c0d48d..8d39e1a6 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 00000000..d200eed1 --- /dev/null +++ b/apps/api/test/support/test-phones.ts @@ -0,0 +1,149 @@ +import { randomUUID } from 'node:crypto'; +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). 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). + */ + +/** 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 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 = 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)); + +const pause = (ms: number): void => { + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); +}; + +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 { + f.mkdirSync(lockDir); + f.writeFileSync(path.join(lockDir, 'owner'), token); + break; + } catch (error) { + 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); + } + } + try { + return fn(); + } finally { + if (ownerOf(f, lockDir) === token) f.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++; + 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/apps/api/vitest.config.ts b/apps/api/vitest.config.ts index b43283a8..401931cd 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/e2e/exams.spec.ts b/apps/web/e2e/exams.spec.ts index 2155e488..cc3bf094 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, @@ -102,6 +103,12 @@ async function annualFor(classCode: string, subjectCode: string, otherCode: stri }; } +/** Undone after each test, passed or failed (the demo child's photo), so other specs see the seed. */ +const cleanups: (() => Promise)[] = []; +test.afterEach(async () => { + for (const undo of cleanups.splice(0)) await undo(); +}); + for (const c of CASES) { test(`${c.lang}: a teacher enters marks on a phone, the office publishes, a guardian sees the report card`, async ({ browser, @@ -266,6 +273,15 @@ 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); + cleanups.push(() => api(office, `/students/${photoChild}/photo`, { method: 'DELETE' })); + } + // ── The guardian, 390 px ── const guardian = await newPage(browser, baseURL, GUARDIAN_PHONE); await otpLoginWithBanglaDigits(guardian, c.guardian); @@ -282,6 +298,7 @@ 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'); diff --git a/apps/web/e2e/files.spec.ts b/apps/web/e2e/files.spec.ts new file mode 100644 index 00000000..9a6068d5 --- /dev/null +++ b/apps/web/e2e/files.spec.ts @@ -0,0 +1,73 @@ +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 (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.locator('#profile-eiin')).toHaveValue('108123'); + await expect(page.locator('#profile-establishedYear')).toHaveValue('1965'); + + 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'); + // 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(); + + 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/e2e/helpers.ts b/apps/web/e2e/helpers.ts index a3c243cd..d0dd3057 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/account/password.bn.json b/apps/web/messages/account/password.bn.json index 3f3066c1..b26d3bb5 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 29e55bfd..d3318383 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/apps/web/messages/bn.json b/apps/web/messages/bn.json index b1717951..996900d4 100644 --- a/apps/web/messages/bn.json +++ b/apps/web/messages/bn.json @@ -20,7 +20,13 @@ "rateLimited": "অনেকবার চেষ্টা করা হয়েছে। {seconds} সেকেন্ড পরে আবার চেষ্টা করুন।", "network": "সার্ভারের সাথে সংযোগ করা যাচ্ছে না। ইন্টারনেট সংযোগ দেখে আবার চেষ্টা করুন।", "generic": "কিছু একটা সমস্যা হয়েছে। আবার চেষ্টা করুন।", - "forbidden": "এই অংশ দেখার অনুমতি আপনার নেই।" + "forbidden": "এই অংশ দেখার অনুমতি আপনার নেই।", + "imageInvalid": "ফাইলটি JPEG, PNG বা WebP ছবি নয়, অথবা নষ্ট। অন্য একটি ছবি দিন।", + "imageTooBig": "ছবিটিতে পিক্সেল খুব বেশি (সর্বোচ্চ ৫০ মেগাপিক্সেল)। আরেকটু ছোট ছবি দিন।", + "imageCannotShrink": "ছবিটি যথেষ্ট ছোট করা গেল না। অন্য একটি ছবি দিন।", + "fileTooLarge": "ফাইলটি ৫ MB-এর বেশি বড়। ছোট একটি ফাইল দিন।", + "storageFull": "প্রতিষ্ঠানের ছবি রাখার জায়গা পূর্ণ। পুরোনো ছবি সরান বা জান্ত্রিককে জানান।", + "imageBusy": "এই মুহূর্তে অনেক ছবি প্রস্তুত হচ্ছে। একটু পরে আবার চেষ্টা করুন।" }, "login": { "title": "লগইন করুন", @@ -703,7 +709,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 +928,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 cd131dcb..1905ec14 100644 --- a/apps/web/messages/en.json +++ b/apps/web/messages/en.json @@ -20,7 +20,13 @@ "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.", + "imageBusy": "Many images are being prepared right now. Try again in a moment." }, "login": { "title": "Sign in", @@ -703,7 +709,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 +928,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/playwright.config.ts b/apps/web/playwright.config.ts index 7f6b4dc6..4bfaf37a 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', diff --git a/apps/web/src/app/(app)/dashboard/page.tsx b/apps/web/src/app/(app)/dashboard/page.tsx index eff643c7..74878bae 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 00000000..ca04f226 --- /dev/null +++ b/apps/web/src/app/(app)/setup/profile/page.tsx @@ -0,0 +1,313 @@ +'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'))} + opaque={false} + 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 1c9c8e3c..c70c9441 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 00000000..145b97ce --- /dev/null +++ b/apps/web/src/components/image-upload.tsx @@ -0,0 +1,103 @@ +'use client'; + +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. 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, + disabled, + testId, +}: { + onChoose: (file: File) => void; + onTooLarge: () => void; + opaque: boolean; + children: ReactNode; + variant?: 'outline' | 'default' | 'ghost'; + size?: 'sm' | 'default'; + disabled?: boolean; + testId?: string; +}) { + const input = useRef(null); + const id = useId(); + const [shrinking, setShrinking] = useState(false); + return ( + <> + { + const file = e.target.files?.[0]; + e.target.value = ''; // the same file can be chosen again after an error + if (!file) return; + setShrinking(true); + void shrinkForUpload(file, opaque) + .then((ready) => (ready.size > UPLOAD_MAX_BYTES ? onTooLarge() : onChoose(ready))) + .finally(() => setShrinking(false)); + }} + /> + + + ); +} + +/** + * 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. */ +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 5060704a..4a99c89d 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 00000000..edbf31fb --- /dev/null +++ b/apps/web/src/components/student-photo.tsx @@ -0,0 +1,55 @@ +'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, + as = 'staff', + className, +}: { + studentId: string; + photoId: string | null; + as?: 'staff' | 'guardian'; + className?: string; +}) { + const url = useAuthedImage(studentPhotoPath(studentId, photoId, as), 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 00000000..75d2df06 --- /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, useFilePreview } 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, preview, choose: setFile } = useFilePreview(); + const [error, setError] = useState(null); + + 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'))} + opaque + 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 00000000..5fa3481a --- /dev/null +++ b/apps/web/src/lib/authed-image.ts @@ -0,0 +1,73 @@ +'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.code === 'IMAGE_BUSY') return t('imageBusy'); + if (error.status === 413) return t('fileTooLarge'); + } + return describe(error); + }, + [t, describe], + ); +} diff --git a/apps/web/src/lib/image-shrink.test.ts b/apps/web/src/lib/image-shrink.test.ts new file mode 100644 index 00000000..4ec01fc1 --- /dev/null +++ b/apps/web/src/lib/image-shrink.test.ts @@ -0,0 +1,104 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { + decodeUpright, + fitWithin, + jpegOrientation, + shrinkForUpload, + UPLOAD_LONG_SIDE, +} from './image-shrink'; + +/** A JPEG start with an EXIF APP1 segment holding only the Orientation tag. */ +function jpegWithOrientation( + orientation: number, + order: 'MM' | 'II' = 'MM', +): Uint8Array { + const be = order === 'MM'; + const u16 = (n: number) => (be ? [n >> 8, n & 255] : [n & 255, n >> 8]); + const u32 = (n: number) => + be + ? [n >>> 24, (n >> 16) & 255, (n >> 8) & 255, n & 255] + : [n & 255, (n >> 8) & 255, (n >> 16) & 255, n >>> 24]; + const tiff = [ + ...(be ? [0x4d, 0x4d] : [0x49, 0x49]), + ...u16(42), + ...u32(8), + ...u16(1), // one IFD entry + ...u16(0x0112), // Orientation + ...u16(3), // SHORT + ...u32(1), + ...u16(orientation), + 0, + 0, + ...u32(0), + ]; + const app1 = [...[0x45, 0x78, 0x69, 0x66, 0, 0], ...tiff]; // "Exif\0\0" + const len = app1.length + 2; + return new Uint8Array([0xff, 0xd8, 0xff, 0xe1, len >> 8, len & 255, ...app1, 0xff, 0xd9]); +} + +describe('fitWithin (the browser-side shrink before upload)', () => { + it('scales the long side down to the limit, keeping the shape', () => { + expect(fitWithin(4000, 3000, UPLOAD_LONG_SIDE)).toEqual({ + width: 1600, + height: 1200, + scaled: true, + }); + expect(fitWithin(3024, 4032, 1600)).toEqual({ width: 1200, height: 1600, scaled: true }); + }); + + it('never enlarges a small image', () => { + expect(fitWithin(600, 800, 1600)).toEqual({ width: 600, height: 800, scaled: false }); + expect(fitWithin(1, 1, 1600)).toEqual({ width: 1, height: 1, scaled: false }); + }); + + it('keeps at least one pixel a side', () => { + expect(fitWithin(100_000, 10, 1600)).toEqual({ width: 1600, height: 1, scaled: true }); + }); +}); + +describe('jpegOrientation', () => { + it('reads the EXIF orientation of a JPEG (both byte orders), null without one', () => { + expect(jpegOrientation(jpegWithOrientation(6).buffer as ArrayBuffer)).toBe(6); + expect(jpegOrientation(jpegWithOrientation(3, 'II').buffer as ArrayBuffer)).toBe(3); + expect(jpegOrientation(jpegWithOrientation(1).buffer as ArrayBuffer)).toBe(1); + expect(jpegOrientation(new Uint8Array([0xff, 0xd8, 0xff, 0xd9]).buffer)).toBeNull(); + expect(jpegOrientation(new Uint8Array([0x89, 0x50, 0x4e, 0x47]).buffer)).toBeNull(); + }); +}); + +describe('decodeUpright (an engine without imageOrientation, review round 3)', () => { + afterEach(() => vi.unstubAllGlobals()); + const oldEngine = () => { + const decoded = { width: 10, height: 10, close: () => undefined }; + const decode = vi.fn((_file: Blob, options?: object) => + options ? Promise.reject(new TypeError('unknown option')) : Promise.resolve(decoded), + ); + vi.stubGlobal('createImageBitmap', decode); + return { decode, decoded }; + }; + + it('decodes without the option when nothing needs turning', async () => { + const { decode, decoded } = oldEngine(); + const upright = new File([jpegWithOrientation(1)], 'a.jpg', { type: 'image/jpeg' }); + expect(await decodeUpright(upright)).toBe(decoded); + const png = new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], 'a.png', { + type: 'image/png', + }); + expect(await decodeUpright(png)).toBe(decoded); + expect(decode).toHaveBeenCalledTimes(4); + }); + + it('gives up (the original is sent; the server turns it) when the photo needs turning', async () => { + const { decode } = oldEngine(); + const sideways = new File([jpegWithOrientation(6)], 'a.jpg', { type: 'image/jpeg' }); + expect(await decodeUpright(sideways)).toBeNull(); + expect(decode).toHaveBeenCalledTimes(1); + }); +}); + +describe('shrinkForUpload', () => { + it('sends the original when the browser cannot decode images (no createImageBitmap)', async () => { + const file = new File([new Uint8Array(10)], 'a.jpg', { type: 'image/jpeg' }); + expect(await shrinkForUpload(file, true)).toBe(file); + }); +}); diff --git a/apps/web/src/lib/image-shrink.ts b/apps/web/src/lib/image-shrink.ts new file mode 100644 index 00000000..5696d0fe --- /dev/null +++ b/apps/web/src/lib/image-shrink.ts @@ -0,0 +1,110 @@ +// Shrinking a chosen image in the browser before upload (review of P2): a phone's 3-8 MB photo +// becomes about 300 KB, so it uploads in seconds on slow 4G and fits the 5 MB limit. The server +// still decodes, resizes and re-encodes whatever arrives (docs/files.md); this only saves time. + +/** The longest side sent: well above every stored box (600 × 800 at most), so nothing is lost. */ +export const UPLOAD_LONG_SIDE = 1600; +/** Files at or under this size and within the long side are sent as they are. */ +const SMALL_ENOUGH_BYTES = 1_000_000; + +/** The size of a width × height image scaled to fit `max` on its longest side (never enlarged). */ +export function fitWithin( + width: number, + height: number, + max: number, +): { width: number; height: number; scaled: boolean } { + const scale = Math.min(1, max / Math.max(width, height)); + return { + width: Math.max(1, Math.round(width * scale)), + height: Math.max(1, Math.round(height * scale)), + scaled: scale < 1, + }; +} + +/** + * The EXIF orientation (1-8) of a JPEG from its first bytes, or null (not a JPEG, or no EXIF + * orientation before the image data). + */ +export function jpegOrientation(buffer: ArrayBuffer): number | null { + const v = new DataView(buffer); + if (v.byteLength < 4 || v.getUint16(0) !== 0xffd8) return null; + let at = 2; + while (at + 4 <= v.byteLength) { + const marker = v.getUint16(at); + if ((marker & 0xff00) !== 0xff00 || marker === 0xffda || marker === 0xffd9) return null; + const size = v.getUint16(at + 2); + const exif = marker === 0xffe1 && at + 18 <= v.byteLength && v.getUint32(at + 4) === 0x45786966; + if (exif) { + const tiff = at + 10; + const little = v.getUint16(tiff) === 0x4949; + const ifd = tiff + v.getUint32(tiff + 4, little); + if (ifd + 2 > v.byteLength) return null; + const count = v.getUint16(ifd, little); + for (let i = 0; i < count; i++) { + const entry = ifd + 2 + i * 12; + if (entry + 12 > v.byteLength) return null; + if (v.getUint16(entry, little) === 0x0112) return v.getUint16(entry + 8, little); + } + return null; + } + at += 2 + size; + } + return null; +} + +/** + * The image decoded upright. An engine that predates `imageOrientation` throws a TypeError for + * it (review round 3): then it is decoded without the option when nothing needs turning (no EXIF + * orientation, or 1), and otherwise not at all (null: the original is sent, and the server turns + * it upright). + */ +export async function decodeUpright(file: File): Promise { + try { + return await createImageBitmap(file, { imageOrientation: 'from-image' }); + } catch (error) { + if (!(error instanceof TypeError)) throw error; + const orientation = jpegOrientation(await file.slice(0, 128 * 1024).arrayBuffer()); + if (orientation !== null && orientation !== 1) return null; + return createImageBitmap(file); + } +} + +/** + * A smaller copy of `file` to upload: JPEG (quality 0.85) on white for photos (`opaque`), PNG + * otherwise (logos, signatures and seals keep their transparency). The original is returned when + * the browser cannot decode it (the server then says why), when it is small already, or when the + * copy would not be smaller. + */ +export async function shrinkForUpload(file: File, opaque: boolean): Promise { + try { + if (typeof createImageBitmap !== 'function') return file; + const bitmap = await decodeUpright(file); + if (!bitmap) return file; + const size = fitWithin(bitmap.width, bitmap.height, UPLOAD_LONG_SIDE); + if (!size.scaled && file.size <= SMALL_ENOUGH_BYTES) { + bitmap.close(); + return file; + } + const canvas = document.createElement('canvas'); + canvas.width = size.width; + canvas.height = size.height; + const ctx = canvas.getContext('2d'); + if (!ctx) { + bitmap.close(); + return file; + } + if (opaque) { + ctx.fillStyle = '#ffffff'; + ctx.fillRect(0, 0, size.width, size.height); + } + ctx.drawImage(bitmap, 0, 0, size.width, size.height); + bitmap.close(); + const type = opaque ? 'image/jpeg' : 'image/png'; + const blob = await new Promise((done) => canvas.toBlob(done, type, 0.85)); + if (!blob || blob.size >= file.size) return file; + const name = file.name.replace(/\.[^.]*$/, '') + (opaque ? '.jpg' : '.png'); + return new File([blob], name, { type }); + } catch { + return file; + } +} diff --git a/deploy/.env.prod.example b/deploy/.env.prod.example index beed8cce..e48082f7 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 --- @@ -50,6 +51,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/backup/restore.sh b/deploy/backup/restore.sh index a792be6e..f3e00a6d 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 e8d4f565..0ea28c58 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:?} @@ -37,6 +39,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:?} @@ -58,6 +62,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 +79,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') @@ -88,7 +93,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/deploy/postgres/create-roles.sh b/deploy/postgres/create-roles.sh index 01b5a2c8..e9c13e6e 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 57dfe9b5..8f2b4859 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' @@ -27,7 +28,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/docker/postgres/init/01-roles.sh b/docker/postgres/init/01-roles.sh index 8810391a..bcc560b1 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/docs/auth.md b/docs/auth.md index 7c0a45cc..e7415e14 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 argon2, against a dummy hash 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 @@ -200,7 +201,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), ignoring case and spaces; names under 4 characters (code points) are skipped; + 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 @@ -222,6 +232,47 @@ 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 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). 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), 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. + +**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 (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 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)). + ## Tenants - `GET /auth/memberships` lists the user's tenants with their roles. `selectable` means the @@ -260,7 +311,8 @@ JwtAuthGuard @Public() skips; verify JWT + session not revoked → RateLimitGuard per user (authenticated) or per IP RolesGuard @Roles(...) → current roles from Redis (tenant:{tid}:user:{uid}:roles:v{n}) ModuleGuard @RequireModule(…) → enabled modules from Redis (tenant:{tid}:modules) -TenantContextInterceptor withContext({ tenantId: tid, userId: sub }) around the handler: +TenantContextInterceptor withContext({ tenantId: tid, userId: sub }) around the handler + (RequestTransaction.run; @OwnTransaction routes call it themselves): - re-checks tenant ACTIVE/TRIAL + active membership (immediate suspension) - handler runs inside the transaction (services use Db.tx) - error → rollback; success → commit → afterCommit callbacks @@ -284,6 +336,27 @@ TenantContextInterceptor withContext({ tenantId: tid, userId: sub }) around the - **`@UserScoped()`** runs a route with the user context only. Used by `/auth/*`, so account routes such as logout work even when the selected tenant is suspended. - **`@Public()`** routes get no request transaction. +- **`@OwnTransaction()`** routes (sprint 1 P2: the image uploads `PUT /students/:id/photo` and + `PUT /institute/profile/:slot`) get no transaction from `TenantContextInterceptor`, which runs + before a route's own interceptors. Otherwise the transaction, and one of the pool's 10 + connections, would be held while multer reads a slow upload and sharp decodes it: on slow 4G a + 5 MB photo outlives the 15 s transaction (a 500 every time), and ten of them would hold every + connection and fail all other institutes' requests after the 5 s `maxWait`. + - The guards above still run first (token, rate limits, roles, module). + - The handler reads the body, applies the upload limit and decodes the image without the + database, then calls `RequestTransaction.run(fn)`: the same transaction the interceptor opens + (`withContext` with the same tenant and user, the tenant and membership re-check, `Db.tx`, + rollback on error, afterCommit after commit), just later and short. + - Everything that touches the database goes inside `run`. Nothing outside it may use `Db.tx` + (it throws: no request transaction), and `run` refuses to start inside one. + - The guards' checks can be a minute old by then (a slow body, the image queue), so the upload + routes pass `roles` to `run`: it re-checks the session (not revoked; in Redis, before the + transaction opens, with the 2 s deadline) and, in the transaction, that the person still holds + one of the route's roles, besides the institute's status and the membership. A short `run` before decoding refuses a lost role or a wrong target early. + - `UploadGuard` bounds the bodies in memory: 16 uploads in flight per process, 2 per person + (503 `IMAGE_BUSY`), a body not received within 60 s dropped. + - The CSV imports (student import, device people) still read their uploads inside the request + transaction; they are small (≤ 1–5 MB) and in the backlog to move the same way. ### Writing a service @@ -456,6 +529,12 @@ 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. +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/database.md b/docs/database.md index 936ba88f..1092b08f 100644 --- a/docs/database.md +++ b/docs/database.md @@ -35,13 +35,16 @@ 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 -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 +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, 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 @@ -66,6 +69,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" @@ -161,12 +165,35 @@ 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` ([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). 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. @@ -176,7 +203,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)` + - `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)` @@ -498,6 +532,41 @@ 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 with the kind** + (`(tenant_id, x, x_kind) → stored_files (tenant_id, id, kind)`, `ON DELETE RESTRICT ON UPDATE +RESTRICT`) and unique. The kind column is fixed by a CHECK (`students.photo_file_kind` = + `STUDENT_PHOTO`; `institute_profiles.logo_file_kind`, `head_signature_file_kind`, + `seal_file_kind` = `LOGO`, `SIGNATURE`, `SEAL`). So a row can only point at its own institute's + file of the right kind, 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 453bd242..f4caafe9 100644 --- a/docs/decisions-pending.md +++ b/docs/decisions-pending.md @@ -593,12 +593,89 @@ 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, 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, 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 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 +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 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) Plan: [plans/fix-refresh-race.md](plans/fix-refresh-race.md), approved by the owner with conditions. @@ -649,10 +726,147 @@ 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). -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: 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). + +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 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, 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. **(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:** 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. + +## 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. + +Changed after the review (each code fix with a test that failed first; R3 is checked by Playwright +in CI; R9 and R10 are docs and tests only; details in the plan → "Changed after the review"): + +- **R1. Uploads no longer run inside the request transaction** (must-fix). `TenantContextInterceptor` + (a global interceptor) opened the 15 s transaction and took a pool connection before multer read + the body: a 2–5 MB photo on slow 4G took longer than 15 s (a 500 every time), and ten slow + uploads could hold all 10 connections (every other institute failing). The two upload routes + are now `@OwnTransaction()`: the body is read, the upload limit applied and the image decoded + with no connection; then `RequestTransaction.run` (the interceptor's own logic, moved into a + service) opens the same tenant transaction for the short store. The image queue is bounded (8 + waiting; more get 503 `IMAGE_BUSY`), and the browser shrinks a chosen image to 1600 px on the + long side (JPEG 0.85 for photos, PNG for the others) before sending, so a phone sends about + 300 KB. Test: while a slow body arrives, no session of the app login is idle in a transaction. +- **R2. The code scan also catches Prisma relation fields** (`photoFile`, `logoFile`, + `signatureFile`, `sealFile`, `storedFiles`, `storedFileUsage`, `storedFilesCreated`, the + `profile*` back-relations). +- **R3. The guardian's report card shows the photo** through `/me/children/:id/photo` + (`ReportCardsPrint as="guardian"`); Playwright checks it in the exams spec. +- **R4. The web address's scheme is stored in lower case** (`HTTPS://x` → `https://x`), as the + database CHECK is case-sensitive; it was a 500. +- **R5. The image queue hands a freed slot straight to the next waiter**, so it can never run + three at once. +- **R6. A file reference is tied to its kind in the database.** `stored_files` has + `UNIQUE (tenant_id, id, kind)`; `students.photo_file_kind` (always `STUDENT_PHOTO`) and + `institute_profiles.logo_file_kind`, `head_signature_file_kind`, `seal_file_kind` (always + `LOGO`, `SIGNATURE`, `SEAL`, by CHECK) are part of each foreign key, so a photo column can only + hold a photo, a logo column a logo, and so on. +- **R7. Replacing an image near the cap is allowed** when the total would not grow: `put` takes the + id it replaces (read under the file lock) and counts it. +- **R8. The first image and the first save cannot collide:** the row an image creates is inserted + with `ON CONFLICT DO NOTHING`. +- **R9.** F1 above now says what the code does (a teacher sees photos of their own sections only). +- **R10.** The database tests name the rule that refuses each write; a PNG `eXIf` GPS case was + added to the image tests. + +- **For the owner (backlog): the CSV imports read their uploads inside the request transaction + too** (student import up to 5 MB, device people up to 1 MB). Smaller and rarer than photos, so + not changed here; they can move to `@OwnTransaction()` the same way. + +Changed after the review, round 2 (each code fix with a test that failed first): + +- **R11. Uploads in flight are bounded.** With R1 nothing limited how many upload bodies could be + in memory. `UploadGuard` (before multer) allows 16 per process and 2 per person, refuses more at + once with 503 `IMAGE_BUSY`, gives the slot back when the response closes (sent, failed or + dropped by the client), and drops a body not received within 60 s. +- **R12. `RequestTransaction.run` refuses to nest** inside a request transaction (it would replace + the outer one in the request context). The interceptor itself uses an unchecked entry (`around`): it is the outermost transaction, and a request made from inside a running job (as some tests do) inherits that job\'s request context. +- **R13. The upload's transaction re-checks the session and the route's roles** (OWNER/ADMIN), + read in the transaction, besides the institute's status and the membership: an admin + downgraded, or a session revoked, while the body arrives stores nothing (403 / 401). +- **R14. The target is checked before decoding:** a student photo for an unknown or deactivated + student, or any upload in a suspended institute or by someone who lost the role, is refused + before the image is decoded or the upload quota is used. +- **R15. sharp's own 10 s timeout** on the decode and each encode → 422 `IMAGE_TIMEOUT`. +- **R16. A replacement no bigger than the old file is never refused**, even when the total is over + a lowered cap; `FileStore.put`'s contract says the caller deletes the replaced file in the same + transaction. +- **R17. A profile save takes the file lock before reading the row**, so a first save racing a + first image is audited as an UPDATE (one CREATE per institute). +- **R18. The browser asks for the EXIF orientation explicitly** (`imageOrientation: +'from-image'`); an engine without it sends the original, which the server turns upright. +- **Tests:** a deterministic database test of the ON CONFLICT path (an insert held uncommitted); + the slow-body check sampled every 100 ms, for the logo route too; suspended institute and + disabled member → 403 with nothing stored; the signature column's wrong kind; the exams spec + removes the demo child's photo in an `afterEach`. +- **Migrations edited in place:** both migrations of this PR changed after it was first pushed + (R6). Nothing outside this run's scratch databases applied them; any database that did needs + a fresh one (or a reset) before applying the final versions. + +Changed after the review, round 3 (each code fix with a test that failed first): + +- **R19. No upload slot leaks when the client leaves early** (must-fix). If the socket closed while + the global guards awaited Redis, the response's one 'close' event was already past when + `UploadGuard` listened for it, so the slot was never given back. A client already gone (the + test on-finished uses: the request or response destroyed, the answer sent, or the socket no + longer writable) now gets no slot, and every slot is given back after 5 minutes at the latest + (a backstop). +- **R20. The revoked-session check runs before the transaction**, with Redis's 2 s deadline (503 + `SERVICE_UNAVAILABLE`), so a slow Redis never holds a pooled connection; the roles are still + read in the transaction. +- **R21. A browser that predates `imageOrientation`** (a TypeError) decodes without it when the + photo needs no turning (no EXIF orientation, or 1; a small JPEG reader checks), and sends the + original otherwise (the server turns it upright). +- **R22.** The timeout test uses sharp 0.35.5's real message (`timeout: N% complete`). + +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/demo-accounts.md b/docs/demo-accounts.md index 48ae7ab2..b85d8230 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/docs/deploy.md b/docs/deploy.md index e4744f3a..50b43f9d 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,11 +100,14 @@ 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 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. @@ -153,7 +156,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 +164,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 +- **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`), 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 +207,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 +247,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:** @@ -340,6 +345,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`. @@ -352,6 +363,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, + `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 @@ -362,6 +403,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: @@ -491,7 +538,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 ``` @@ -533,7 +581,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); diff --git a/docs/devices.md b/docs/devices.md index 1381efe3..f2fc51e7 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 @@ -169,7 +170,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/docs/files.md b/docs/files.md new file mode 100644 index 00000000..dc38d775 --- /dev/null +++ b/docs/files.md @@ -0,0 +1,118 @@ +# 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; at most 8 more wait (more get 503 +`IMAGE_BUSY`), and a freed slot goes straight to the next one. sharp's own timer stops a decode or +an encode after 10 s (422 `IMAGE_TIMEOUT`). + +**Uploads in flight** (`UploadGuard`, before multer reads a byte): at most 16 per API process and +2 per person; more get 503 `IMAGE_BUSY` at once. The slot is given back when the response closes, +however it ends (or after 5 minutes at the latest); a client already gone when the guard runs gets +no slot. A body not received within 60 s is dropped. + +**No database connection while an upload arrives.** The upload routes are `@OwnTransaction()` +([auth.md](auth.md) → Request pipeline): multer reads the body and `ImageService` decodes it +before any transaction is opened; then one short request transaction stores the file and changes +the row. That transaction re-checks what the guards checked when the request arrived (the +session, the institute's status, the membership and the route's roles), and a short one before +decoding refuses an unknown or deactivated student, a suspended institute or a lost role without +decoding anything. The browser also shrinks a chosen image to 1600 px on the long side before sending +(`apps/web/src/lib/image-shrink.ts`: JPEG 0.85 for photos, PNG otherwise; the original when the +browser cannot decode it or the copy is not smaller), so a phone photo is about 300 KB. + +| 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()` **before** reading which file a row points + at, so two changes of one image cannot both delete or keep the same old file. A replacement + passes the old id to `put(file, { replaces })`, which counts it: a replacement that does not + grow the total is allowed near the cap, and one no bigger than the old file even over a + lowered cap. The caller deletes the old file in the same transaction. +- **Each reference is tied to its kind:** `UNIQUE (tenant_id, id, kind)` on `stored_files`, and a + fixed kind column in each foreign key (`students.photo_file_kind` is always `STUDENT_PHOTO`, + `institute_profiles.logo_file_kind` `LOGO`, and so on), so a logo can never be used as a photo. + +## 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`, + 422 `IMAGE_TIMEOUT`, 413 `STORAGE_FULL`, 409 `DEACTIVATED`, 503 `IMAGE_BUSY`, 403 when the + role was lost while the upload arrived. +- 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, from + the staff route or, with `as="guardian"`, the guardian's own (the guardian's report card). 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. diff --git a/docs/guide/staff-guide.md b/docs/guide/staff-guide.md new file mode 100644 index 00000000..ab267a25 --- /dev/null +++ b/docs/guide/staff-guide.md @@ -0,0 +1,1049 @@ +# Jantrik School: staff guide (DRAFT) + +> **DRAFT for the owner's review. Not for institutes yet.** +> +> - Written in plain English from the code and the project docs on 2026-11-18, while the owner +> was away. Nobody has yet walked through these steps on the running app to check them. +> - Institutes read Bangla first. **An owner-approved Bangla translation is needed** before this +> guide goes to any institute. +> - It describes the app on the branch `integration/sprint-1`: `main` plus PRs #16 (password +> login hardening), #17 (small follow-ups) and #18 (institute profile, photos). Section 15 +> describes features that are built in **open PRs, not merged yet**. Each says which PR. +> - Places where the writer was not sure are marked **To check**. They are collected in +> section 16. + +**Before the first institute goes live (owner).** The app sends every SMS through an SMS +gateway, and no gateway is connected yet (`docs/deploy.md` → What needs the owner). Until one +is, no SMS reaches anyone: not the sign-in codes, not the absent alerts, not the fee receipts. +Everything in this guide that mentions an SMS assumes the gateway is working. + +--- + +## Contents + +1. How to read this guide +2. Who can do what +3. Signing in +4. The dashboard +5. Institute setup +6. The institute profile: logo, signature and seal +7. Appearance +8. Staff and invitations +9. Students +10. Guardians +11. Attendance +12. Fees +13. Exams and results +14. SMS: the daily limit +15. Coming soon: features in open PRs +16. To check + +--- + +## 1. How to read this guide + +- **Bangla screen names** are in square brackets, as the app shows them, for example Dashboard + [ড্যাশবোর্ড]. Buttons are in **bold**. +- **Your institute's own words.** Some words change with the institute type and can be changed + by the owner or an admin (section 5.6). A school sees "Class" [শ্রেণি] and "Section" [শাখা]; + a coaching centre may see "Course" and "Batch". This guide uses the school words: class, + section, academic year [শিক্ষাবর্ষ], student [শিক্ষার্থী], roll [রোল]. +- **Modules.** Attendance, Fees and Exams are separate modules. Jantrik switches them on or off + for each institute (it is part of the plan). If your institute does not have a module, its + menu item is not shown. If you open such a page anyway you see "Not available" [দেখা যাচ্ছে + না]: "This section is not enabled for your institute, or you don't have permission." +- **Digits.** You can type Bangla or English digits anywhere you type a number. Phone numbers, + student IDs, rolls and receipt numbers are always shown in English digits so they can be + copied into a phone. +- **Phone or computer.** Every screen works on a phone. Teachers mostly use a phone; the office + mostly uses a computer. + +## 2. Who can do what + +Each person has one or more **roles** in an institute. One person can hold several roles, for +example a teacher who also collects fees. + +| Role (Bangla) | In short | +| ------------------------- | ----------------------------------------------------------------------------------------------- | +| Owner [প্রতিষ্ঠান প্রধান] | Everything an admin can do, plus: owners' roles, the institute's look, the bKash/Nagad numbers. | +| Admin [প্রশাসক] | Runs the office: setup, students, staff, attendance settings, fee setup, exams. | +| Accountant [হিসাবরক্ষক] | The fee counter: collect, receipts, bKash/Nagad checks, own daily closing, fee reports. | +| Teacher [শিক্ষক] | Attendance and marks for the sections and subjects they are given. | +| Staff [কর্মী] | Today: the dashboard and their own password only. **To check** what this role is for. | +| Guardian [অভিভাবক] | Not staff. Sees their own children only (section 10.4). | + +| Area | Owner | Admin | Accountant | Teacher | +| ------------------------------------ | ----- | --------------------------------- | ---------- | ---------------------------------------- | +| Dashboard | yes | yes | yes | yes | +| Institute setup, profile | yes | yes | no | no | +| Appearance (the institute's look) | yes | no | no | no | +| Staff list and invitations | yes | yes (not owners) | no | no | +| Student list | yes | yes | no | yes (full details only for own sections) | +| Admit, import, edit students, photos | yes | yes | no | no | +| Take attendance | yes | yes | no | own sections, within the edit window | +| Attendance settings, devices | yes | yes | no | no | +| Fee setup | yes | yes (not the bKash/Nagad numbers) | no | no | +| Collect fees, receipts | yes | yes | yes | only if also given "fee collection" | +| Void a receipt, waive a fine | yes | yes | no | no | +| Fee reminders (SMS) | yes | yes | no | no | +| Exam setup, lock, publish, print | yes | yes | no | no | +| Enter marks | yes | yes | no | own subject and section | + +If a button or page you need is missing, your role does not include it. **Ask your +institute's admin.** Admins: if something is missing for you, ask your institute's owner, or +Jantrik if a whole module is missing. + +## 3. Signing in + +There is no sign-up page. You can sign in only after your institute (or Jantrik, for the first +owner) has added your mobile number. + +### 3.1 The first time: with a code + +1. Open the app's address in a browser (phone or computer). +2. Choose **OTP code** [ওটিপি কোড]. +3. Type your mobile number [মোবাইল নম্বর], for example 01712345678, and tap **Send code** + [কোড পাঠান]. +4. An SMS brings a 6-digit code. Type it in **Verification code** [যাচাই কোড] and tap **Sign + in** [লগইন]. The code works for 5 minutes and only once. +5. If your institute has invited you, you now see the invitation: " added you as + " with **Accept** [গ্রহণ করুন] and **Decline** [প্রত্যাখ্যান]. You get access only + after you accept. An invitation can be accepted for 14 days. + +### 3.2 Set a password (staff) + +A password lets you sign in without waiting for an SMS each time. Only staff can have one; +guardians always sign in with a code. + +1. Sign in with a code (3.1). +2. Open your menu (your name, top corner) and choose **Password** [পাসওয়ার্ড]. +3. Tap **Send code** [কোড পাঠান]. A code comes to your own phone. It works for 5 minutes. +4. Type the code, your new password, and the password again. Tap **Set password** + [পাসওয়ার্ড সেট করুন]. + +Password rules [পাসওয়ার্ডের নিয়ম]: + +- 10 to 128 characters. Bangla, English, digits and symbols all count. +- Not your mobile number, in any form. +- Not the institute's name or a distinctive word from it. General words like "school", + "বিদ্যালয়" or "coaching" are fine. +- Not a very common password. + +Setting a password **signs you out on every other device**. This browser stays signed in. + +### 3.3 Sign in with a password + +1. Choose **Password** [পাসওয়ার্ড]. +2. Type your mobile number or email, and your password. Tap **Sign in** [লগইন]. + +### 3.4 Forgot your password + +There is no "reset by the admin" yet. Do this yourself: + +1. Sign in with a code (3.1). +2. Set a new password (3.2). + +If you no longer have the phone with your number, **ask your institute's admin**. **To check:** +what an admin can do then (they cannot change your number or password today). + +### 3.5 More than one institute + +- If you work in more than one institute (or are also a guardian somewhere), you see **Choose + an institute** [প্রতিষ্ঠান নির্বাচন করুন] after signing in. Tap the one you want. +- To move to another one later: your menu → **Switch institute** [প্রতিষ্ঠান পরিবর্তন]. +- If you switch in one browser tab, your other tabs show "Institute changed" and reload. This + is on purpose: a page never mixes two institutes' data. + +### 3.6 Signing out + +Your menu → **Log out** [লগআউট]. Every tab of that browser signs out. Sign out on shared +office computers. + +### 3.7 Messages you may see + +| Message | What it means and what to do | +| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| "The phone number, code or password is not correct." [ফোন নম্বর, কোড বা পাসওয়ার্ড সঠিক নয়।] | Wrong code or password, an expired code, or a number the institute has not added. For safety the app never says which. Check and try again. | +| "Too many attempts. Try again in N seconds." | You (or someone) tried too often. Wait. A phone gets at most one code a minute and 10 codes a day; 5 wrong passwords lock it for 15 minutes. | +| "No password yet? Sign in with a code, then set one from your menu." | You have no password. Use a code (3.1), then 3.2. | +| "You don't have access to any active institute." | Your invitation is not accepted, has expired, or your access was turned off. Ask your institute's admin. | +| "Temporarily unavailable" [সাময়িকভাবে বন্ধ] next to an institute | Jantrik has paused that institute's account. The owner should contact Jantrik. | +| "Can't reach the server" [সার্ভারের সাথে সংযোগ হচ্ছে না] | Weak internet. You are not signed out. The app keeps trying by itself; attendance and marks kept on the phone are sent later. | +| "The code is wrong or has expired." (password page) | Send a new code. A refused password does not use the code up, so fix the password first. | + +## 4. The dashboard + +Dashboard [ড্যাশবোর্ড] is the first page after signing in. What it shows depends on your roles +and your institute's modules. Some cards: + +- **Today's figures** [আজকের হিসাব]: total students, present today, registers taken, SMS sent + today against the daily limit. +- **Needs attention** [নজর দিন]: students absent several days running (call their guardians), + registers not taken yet, SMS held back by the daily limit. +- **Absent today** [আজ অনুপস্থিত], with a call button per guardian. +- **Fees** [ফি আদায়]: collected this month against the same days last month, overdue amounts, + bKash/Nagad payments waiting to be checked. +- **Exams**: mark sheets submitted and locked; for a teacher, "N of yours to finish". +- **Quick actions** [দ্রুত কাজ]: admit a student, take attendance, collect a fee. +- **Getting started** [শুরু করার ধাপ] (owner, admin): the setup steps still open, with + **Continue setup** [সেটআপ চালিয়ে যান] for an institute Jantrik created with the setup + wizard. +- **"N attendance lists not sent yet"**: registers kept on this phone. Open them; they send by + themselves when the internet is back (11.2). +- **"N SMS held back today"** (owner, admin): see 14. +- **Jantrik's invoice** (owner only): an unpaid Jantrik invoice past its due date. Contact + Jantrik to pay. It disappears once Jantrik records the payment. + +## 5. Institute setup + +Who: owner and admin. Menu: **Institute setup** [প্রতিষ্ঠান সেটআপ]. The tabs are: academic +year, classes and sections, shifts, subjects, groups, names and words, student ID, institute +profile, and (owner only) appearance. + +Things that are in use cannot be deleted, only **deactivated** [নিষ্ক্রিয় করুন]. "In use, so +it can't be deleted; deactivate it" means exactly that. + +### 5.1 The setup wizard (new institutes) + +When Jantrik creates your institute, the owner is invited. After the owner accepts, a short +wizard opens: academic year, classes and sections, shifts, inviting teachers, importing +students, attendance. Each step can be skipped [এই ধাপ বাদ দিন] and done later; **Continue +later** [পরে করব] goes to the dashboard, which keeps a **Continue setup** button until the +wizard is finished. + +### 5.2 Academic year [শিক্ষাবর্ষ] + +One academic year is always **current** [চলতি]. Attendance, admissions and lists use the +current one. + +1. Check the year Jantrik made for you: name, start and end date. **Edit** [সম্পাদনা] if needed. +2. For the next year: **Open the next year** [পরের শিক্ষাবর্ষ খুলুন]. You can copy every + section of the current year into it. Only the structure is copied, not the students. +3. **Make current** [চলতি করুন] switches the whole institute to that year. Do this only when + the new year really starts. (After PR #22 there is a guided way to do this: 15.4.) + +### 5.3 Classes and sections [শ্রেণি ও শাখা] + +- The list of classes comes from your institute type. You can add, rename, reorder (**Order** + [ক্রম]: smaller numbers come first) or deactivate classes. +- Each section belongs to one class **and one academic year**. Add a section with **New + section in ** [-এ নতুন শাখা]: a name (for example ক, খ, A or "Morning + batch"), optionally a shift and a number of seats [আসন সংখ্যা] (empty means no limit). +- "More students than that are already enrolled" means you set fewer seats than the students + already in that section. + +### 5.4 Shifts [শিফট] + +Optional. Add morning and day shifts with their start and end times if you have them, and give +each section one. Device attendance (11.8) uses the shift's start time. + +### 5.5 Subjects [বিষয়] and groups [বিভাগ] + +- Subjects belong to a class. Each has a name in Bangla and English and a short code (English + letters, for example MATH). +- Tick **Optional subject (4th subject)** [ঐচ্ছিক বিষয় (৪র্থ বিষয়)] for subjects students + may choose. +- Groups are Science, Business Studies, Humanities and so on. A subject can belong to one group + or to all. + +### 5.6 Names and words [নাম ও শব্দ] + +The words your institute uses (for example Batch instead of Section), in Bangla and English. +Write both. **Preview** [যেমন দেখাবে] shows them before you save; the app then uses them +everywhere. + +### 5.7 Student ID [শিক্ষার্থী আইডি] + +How IDs are made for **new** admissions. Existing IDs never change. + +- **Prefix** [শুরুর অংশ]: 1 to 10 English letters or digits, for example SHS. +- **Pattern** [গঠন]: keep exactly one `{NNNN}` (the running number); you may add `{PREFIX}`, + `{YEAR}` or `{YY}`, letters, digits, `-`, `/` and `_`. The page shows the next ID. + +### 5.8 Messages + +| Message | What to do | +| ------------------------------------------------------------------------------- | ------------------------------------------------- | +| "This name or code already exists." | Use another name or code. | +| "It is deactivated; activate it first." | **Activate again** [আবার চালু করুন], then use it. | +| "It is linked to something else, or what you picked no longer exists." | Someone changed it meanwhile. Reload the page. | +| "There is no current academic year. Make one current in institute setup first." | 5.2. | + +## 6. The institute profile: logo, signature and seal + +Who: owner and admin. Setup → **Institute profile** [প্রতিষ্ঠানের প্রোফাইল]. + +1. **Names** [নাম]: the name in Bangla and English, a short name, the EIIN (6 digits, if you + have one), the year established. +2. **Address and contact** [ঠিকানা ও যোগাযোগ]: address in Bangla and English, phone, email, + website. +3. **Head of institute** [প্রতিষ্ঠান প্রধান]: title (for example প্রধান শিক্ষক) and name in + both languages. +4. **Save** [সংরক্ষণ করুন]. +5. **Logo, signature and seal** [লোগো, স্বাক্ষর ও সিল]: **Upload** [আপলোড], **Replace** + [বদলান] or **Remove** [সরান] each image. + - Logo: a PNG with a transparent background looks best. + - Head's signature: sign in black ink on white paper and take a photo. + - Seal: stamp it on white paper and take a photo. + +Images: JPEG, PNG or WebP, at most 5 MB each. The app shrinks them and removes hidden details +(such as the place a photo was taken). The page shows how much image space the institute has +used. Everyone in the institute (guardians too) can see the logo; only the owner and admins +can see the signature and seal. + +The profile is meant for admission forms, ID cards and certificates. **To check:** which +printouts already use the logo, signature and seal today (the admission test admit cards in +PR #27 use the logo). + +Image messages: + +| Message | What to do | +| ------------------------------------------------------------------ | ------------------------------------------------------------- | +| "This file is not a JPEG, PNG or WebP image, or it is damaged." | Use another image (other formats, such as HEIC, are refused). | +| "The file is larger than 5 MB." | Choose a smaller one. | +| "The image has too many pixels (at most 50 megapixels)." | Choose a smaller one. | +| "This image could not be made small enough." | Choose another image. | +| "Many images are being prepared right now. Try again in a moment." | Wait a moment and try again. | +| "The institute's storage for images is full." | Remove old images, or contact Jantrik. | + +## 7. Appearance + +**The institute's look** (owner only): Setup → **Appearance** [চেহারা]. + +1. Pick one of four looks: School [স্কুল], Madrasa [মাদ্রাসা], Coaching [কোচিং], English + medium [ইংলিশ মিডিয়াম]. Your type's default is marked. +2. Optionally pick an **Accent colour** [মূল রং] for buttons, links and charts. If text would + be hard to read, the app adjusts the colour or refuses it and says so. +3. **Save** [সংরক্ষণ করুন]. **Back to the default for your type** undoes it. + +**Your own view** (everyone): your menu → + +- **Appearance** [রং]: Light [আলো], Dark [অন্ধকার] or Same as the device [ডিভাইসের মতো]. It is + kept on your account. +- **Layout** [বিন্যাস]: Compact (desktop) [ঘন] or Comfortable (larger) [আরামদায়ক]. + +## 8. Staff and invitations + +Who: owner and admin. Menu: **Staff** [কর্মী ও শিক্ষক]. + +### 8.1 Add a person + +1. **Add staff** [নতুন কর্মী যোগ করুন]. +2. Type their mobile number, their name in English (and in Bangla if you like), and tick one or + more roles. +3. **Add** [যোগ করুন]. + +**No SMS is sent.** Tell the person yourself: "Sign in with an OTP code on this number and +accept the invitation within 14 days." Until they accept, the list shows "Invited, waiting for +an answer" [আমন্ত্রিত, উত্তরের অপেক্ষায়]. + +- **Cancel invitation** [আমন্ত্রণ বাতিল করুন]: for example if you typed a wrong number. +- **Invite again** [আবার আমন্ত্রণ পাঠান]: after it expired or was declined. + +### 8.2 Change what a person does + +From the menu beside their name: + +- **Change roles** [দায়িত্ব বদলান]. +- **Assign sections** [শাখা দিন]: the current year's sections they teach and take attendance + for. (Also possible from Attendance → Settings → Teachers per section, 11.7.) +- **Give fee collection** [ফি আদায়ের দায়িত্ব দিন] / **Remove fee collection**: lets a teacher + collect fees too, without other office rights. Receipts they gave stay as they are. +- **Deactivate** [নিষ্ক্রিয় করুন]: they lose access to this institute at once. Nothing is + deleted; **Activate again** brings back their old roles. + +### 8.3 Rules about owners + +- Only an owner can add an owner, or change an owner's roles or status. +- The institute must always keep at least one active owner. +- Nobody can change their own roles or status. + +### 8.4 Messages + +| Message | What to do | +| ------------------------------------------------------------------- | ----------------------------------------------------- | +| "The person with this number is already on the staff list." | Find them in the list and change their roles instead. | +| "Only an owner can make changes involving owners." | Ask the owner. | +| "The institute must keep at least one active owner." | Make someone else owner first. | +| "You cannot change your own roles or status." | Ask another admin or the owner. | +| "Only active teachers or admins can be given sections." | Give them the teacher role first. | +| "Many staff were added in the last hour. Try again a little later." | A safety limit (30 an hour). Wait and continue. | + +## 9. Students + +Menu: **Student list** [শিক্ষার্থী তালিকা]. Owner, admin and teachers see the list; only the +owner and admins can add or change students. + +### 9.1 Find a student + +Search by name, ID or phone number [নাম, আইডি বা ফোন নম্বর দিয়ে খুঁজুন], and filter by class, +section and status. Open a student to see their page. + +**What a teacher sees:** every student's name, ID, class, section, roll and status. The full +record (date of birth, birth registration number, addresses, parents and guardians with their +phones, the photo) only for students of the sections they are assigned to this year. + +### 9.2 Admit one student + +1. **Admit a student** [নতুন শিক্ষার্থী ভর্তি]. +2. **Student details** [শিক্ষার্থীর তথ্য]: at least one name (Bangla or English); date of + birth, gender, religion, blood group, birth registration number (17 digits), parents' names + and addresses as you have them. +3. **Class** [ভর্তির শ্রেণি]: the academic year, class, section and group. **Roll** may be left + empty and given later. +4. **Student ID**: leave empty to make one from the pattern (5.7). +5. **Guardians** [অভিভাবক]: name, mobile number and relation. Add more with **Another + guardian** [আরেকজন অভিভাবক]. Mark one as **Primary guardian** [প্রধান অভিভাবক]: they get the + attendance SMS. +6. **Board registration** [বোর্ড নিবন্ধনের তথ্য] can be filled in later. +7. **Admit** [ভর্তি করুন]. The app shows the new ID. + +If a guardian's number is already in the institute (a brother or sister studies here), the app +asks **who this is**: pick the existing guardian, or **Add as a new guardian**. Everyone on one +number shares one login: whoever holds that phone sees all those children in the app. + +No SMS is sent on admission. + +### 9.3 Import many students from Excel or CSV + +Who: owner and admin. Student list → **Import from Excel** [এক্সেল থেকে আনুন]. + +1. **Download a template** [টেমপ্লেট নামান] (Excel or CSV), or use your own sheet. + - One student per row. Name, class and guardian phone are required. + - At most 5 MB and 5000 rows per file. + - Students are enrolled in the **current** academic year. +2. **Upload and check** [আপলোড ও যাচাই]. Nothing is saved yet. +3. **Match the columns** [কলাম মেলান]: the app matches them by itself; fix any wrong ones and + **Check again** [আবার যাচাই করুন]. +4. Look at the rows: OK, Errors, Already here, Possible duplicates. Each error says what is + wrong in that row. Fix them in your file and upload again, or leave them out. + - **Possible duplicate**: same name, class and guardian phone as a student already here or + another row. Such rows are skipped unless you switch on **Import anyway** for that row. +5. **Add N students** [N জন শিক্ষার্থী যোগ করুন], then confirm. Rows with errors and + students already here are skipped. +6. Download the **Report** [রিপোর্ট] (Bangla or English) to see each row's result. + +Uploading the same file again adds nobody twice (it matches on student ID or birth +registration number). An unfinished import older than a week loses its file data; upload it +again. Common row errors: "no such class (or deactivated)", "already taken in the section" +(roll), "not a valid mobile number", "must be 17 digits" (birth registration), "unreadable +date (e.g. 17/05/2014)", "no seats left in the section". + +### 9.4 The student's page + +Owner and admin can: + +- **Edit** [সম্পাদনা]: change the details. +- **Photo** [ছবি]: **Add photo** / **Change photo** / **Remove photo**. JPEG, PNG or WebP up to + 5 MB. It is kept at passport size; the location and other hidden details are removed. The + photo appears on the student's page and the report card. Lists show initials, not photos. +- **Change section** [শাখা বদল]: moves the student to another section of the **same class and + year**. The roll must be free there. (This is what the app calls a transfer; a student who + leaves the institute is a different thing, see below.) +- **Guardians**: section 10. +- **Deactivate** [নিষ্ক্রিয় করুন]: the student leaves the lists and attendance registers, and + their roll can be given to someone else. Nothing is deleted; the page becomes read only. + **To check:** there is no "activate again" for a student today. + +A student who leaves the institute (transferred to another school, dropped out, graduated): +today the only way is **Deactivate**. After PR #21 there is a proper **Leaves the institute** +action that keeps their dues and history (15.4). + +**Attendance report** [হাজিরার হিসাব] on the page opens the student's day-by-day attendance. + +### 9.5 Messages + +| Message | What to do | +| --------------------------------------------------------------------------- | ------------------------------------------------- | +| "This roll is already taken in the section" | Give another roll, or leave it empty. | +| "This section has no seats left" | Choose another section, or raise the seats (5.3). | +| "Another student has this birth registration number" | Probably the same child. Search for them first. | +| "This ID already exists" | Leave the ID empty to make a new one. | +| "The institute has reached the student limit of its plan. Contact Jantrik." | The owner should contact Jantrik. | +| "Only an owner or admin can admit students." | Ask your institute's admin. | +| "Make someone else the primary guardian first." | 10.2. | +| "A student needs at least one guardian." | Add another guardian before removing this one. | +| "This student is deactivated." | Nothing can be changed on a deactivated student. | + +## 10. Guardians + +Guardians are managed on each student's page (owner and admin). There is no separate guardian +list. + +### 10.1 Add a guardian + +Student page → **Add guardian** [অভিভাবক যোগ করুন]: name, mobile number, relation. If the +number is already known, pick the existing guardian or add a new one (9.2). + +### 10.2 Primary guardian + +The **primary** guardian [প্রধান] gets the attendance SMS, fee receipt SMS, reminders and +result SMS. To change it: **Make primary** [প্রধান করুন] on another guardian. You cannot +remove the primary guardian until someone else is primary. + +### 10.3 Remove a guardian + +**Remove** [বাদ দিন] unlinks them from this student. A student must keep at least one guardian. + +### 10.4 What guardians see + +Guardians sign in with an SMS code on the number the institute has on file. They never get a +password. They see only their own children: + +- each child's card with their class, roll and ID (the photo is on the report card); +- the attendance calendar for the month; +- fees: dues, receipts, and **I paid by bKash/Nagad** to report a transfer (12.6); +- exam results, only after they are published (13.6). + +If a guardian says "No students are linked to your mobile number", their number is not on any +child's record, or is typed differently. Check the student's page. + +## 11. Attendance + +Menu: **Attendance** [হাজিরা]. Tabs: Take attendance [হাজিরা নিন], Today [আজকের হিসাব], +Monthly register [মাসিক রেজিস্টার], Settings [সেটিংস], and for the owner and admins Devices +[ডিভাইস] and Staff [কর্মীদের হাজিরা]. + +### 11.1 Take attendance (teachers) + +1. Attendance → **Take attendance**. You see the sections you were given. If you see "You + haven't been given any section", **ask your institute's admin** to assign you (8.2). +2. Tap a section. +3. Everyone starts as **Present** [উপস্থিত]. Tap a name to change it: Present → Absent + [অনুপস্থিত] → Late [দেরি] → Leave [ছুটি] → Present. **All present** [সবাই উপস্থিত] resets + everyone. +4. **Submit attendance** [হাজিরা জমা দিন]. If more than half are absent, the app asks you to + confirm. +5. The screen says "Submitted at 10:42" [জমা হয়েছে]. To correct it later the same day, + change the names and **Submit changes** [পরিবর্তন জমা দিন]. + +If attendance is taken every period (a setting), choose the **Period** [পিরিয়ড] first. + +### 11.2 No internet? Your work is kept on the phone + +- Every tap is saved on the phone at once. The screen always says where your work is: "Kept on + this phone, not sent yet", "Sending…", "Couldn't send. Trying again in N s", or "Submitted + at …". +- When the internet comes back the app sends it by itself. **Send now** [এখনই পাঠান] tries at + once. +- Do not clear the browser's data or use a private window for attendance: that would lose the + kept copy. Unsent copies older than 7 days are removed. +- The dashboard and the take screen list registers still on this phone. + +### 11.3 "Someone changed this attendance" + +If another person (or the attendance device) changed the same register while you were working, +you see "X changed this attendance at 10:30" with only the students that differ, and two +buttons: **Keep mine** [আমারটা রাখুন] or **Keep theirs** [ওনারটা রাখুন]. Talk to the other +person if you are not sure. + +If the student list changed (a new admission, a section change), the app says so: new students +are marked present. Check and submit again. + +### 11.4 Which days can be changed + +- Never a future day. +- Teachers: today and the number of days back the institute allows (the edit window; 0 means + today only). Older days: "It's too late to change this day. Ask the institute admin if it + needs a fix." [এই দিনের হাজিরা বদলানোর সময় শেষ।] +- Owner and admin: any past day. +- Weekly days off and holidays: "No attendance today." An owner or admin can still **Take + attendance anyway** [তবুও হাজিরা নিন]. + +### 11.5 Reports + +- **Today** [আজকের হিসাব]: every section, taken or not, counts, and the absent students with + how many days running and a call button. +- **Monthly register** [মাসিক রেজিস্টার]: students × days for a section and month, with + totals. **Print** [প্রিন্ট] (A4 landscape) or **Download CSV** [CSV ডাউনলোড] (opens in + Excel, Bangla included). +- **One student**: this month, the last 30 days or this year, day by day, with who marked each + day (by hand or the device). + +Present % = (present + late) ÷ (all days − leave days). If the institute counts leave as +absent, leave days stay in. + +### 11.6 Absent SMS + +Off by default, because SMS cost the institute money. When on: + +- one SMS per absent student per day, to the **primary** guardian, only for today's register, + and only for active students; +- it waits a few minutes first (the correction delay, 10 minutes by default). If the teacher + corrects the mistake within that time, no SMS goes; +- it counts towards the daily SMS limit (14). + +### 11.7 Attendance settings (owner, admin) + +Attendance → **Settings** [হাজিরার সেটিংস]: + +- **How often** [হাজিরা কতবার]: once a day, or every period. +- **Weekly days off** [সাপ্তাহিক ছুটি]. +- **How many days back teachers can change attendance**. +- **Count leave as absent** [ছুটিকে অনুপস্থিত ধরুন]. +- **Absent SMS** [অনুপস্থিতির SMS]: on or off; the text (with `{student}`, `{date}`, + `{institute}` filled in for you, a preview, and how many SMS it costs: Bangla fits 70 + characters in one SMS); the wait before sending; **Most SMS per day** (automatic = twice the + number of students, or your own number). +- **Holidays** [ছুটির দিন]: add each holiday with its dates. +- **Teachers per section** [শাখার শিক্ষক]: who takes attendance for each section; mark one as + **Class teacher** [শ্রেণি শিক্ষক]. +- Device, punch check, entry/exit SMS and staff office hours cards: 11.8. + +### 11.8 Attendance devices (ZKTeco) and staff attendance + +Built, but **not yet tried with a real device**: everything was tested with a simulated one. +Try it with your own device before relying on it. + +Who: owner and admin. Attendance → **Devices** [ডিভাইস]. + +1. **Add device** [ডিভাইস যোগ করুন] with its serial number (the device's System Info → + Device Info). The setup guide then shows, in Bangla, what to set on the device: the server + address and port, HTTPS off, the time zone GMT+6. +2. When the device connects, the guide shows the internet address it called from. **Trust** + only the address that is your institute's own internet connection. No changes are sent to + the device until one address is trusted. +3. **People and device IDs** [মানুষ ও ডিভাইস আইডি]: everyone gets a number. **Assign default + IDs** [ডিফল্ট আইডি দিন] gives students their ID's digits and staff a number from 9001 up. + New IDs are sent to every active device by themselves. +4. On the device itself, enrol each person's finger, card or face under their ID. Jantrik + never receives or stores fingerprints, faces or photos from the device: only the ID, the + time and in/out. + +What the device does for attendance: + +- The take screen shows each student's punch-in time. +- With **Take attendance from the devices at the cutoff** on (once-a-day attendance only), the + day's register is written at the cutoff (the shift's start + the cutoff minutes, 60 by + default): punched in = present or late, no punch = absent. A teacher's own register before + the cutoff always wins. +- The app holds it back, and says why on the Today page, when no device was connected in the + last 15 minutes, when students are not on any device yet, or when more than half have no + punch. Then take it by hand, or an owner/admin uses **Take from the device** [ডিভাইস থেকে + নিন]. +- **Entry and exit SMS** [প্রবেশ ও বের হওয়ার SMS]: optional; at most one of each per student per + day; they stop at 90 % of the daily SMS limit so absent alerts still go. +- **Device alerts** [ডিভাইসের সতর্কতা]: offline, a new internet address, too many punches in a + minute (held until you accept them), a clock that is fast or slow. +- Raw punches are kept for 730 days by default (a setting: 30 to 3650). Attendance made from + them is kept. + +**Staff attendance** [কর্মীদের হাজিরা] (owner, admin): each tracked staff member's in and out +from the device, late and early-leave minutes against the office hours (a setting, 08:00 to +16:00 by default), a month view to print or download, and manual entries (present, absent or +leave) with a reason. + +**Before switching a device off and on again** after giving someone's ID to another person, +read `docs/devices.md` → Device IDs ("Known limit"): the old person's fingerprint could punch +as the new one. **To check** with the owner how to explain this to institutes. + +### 11.9 Messages + +| Message | What it means | +| -------------------------------------------------------------- | -------------------------------------------------------------------- | +| "Couldn't submit (CODE). The list is kept on this phone." | It was not saved yet. It stays on the phone and is sent again later. | +| "The student list changed: N new (marked present), M removed." | Check the names and submit again. | +| "Attendance can't be taken for a future day." | Choose today or a past day. | +| "The system is busy right now. Try again in a moment." | Wait a few seconds and try again. Nothing was changed. | +| "This text is longer than 3 SMS. Make it shorter." (settings) | Shorten the absent SMS text. | +| "This serial number can't be added." (devices) | Check the number. If it is right, contact Jantrik. | + +## 12. Fees + +Menu: **Fees** [ফি] (owner, admin, accountant; a teacher only if given fee collection). Tabs: +Collect [আদায়], bKash/Nagad [বিকাশ/নগদ যাচাই], Daily closing [দিনের হিসাব], Reports +[রিপোর্ট], Reminders [রিমাইন্ডার], Setup [সেটআপ]. + +All amounts are in taka; the app never rounds a payment. + +### 12.1 Fee setup (owner, admin) + +Fees → **Setup**. Do these once, in this order: + +1. **Start and general** [শুরু ও সাধারণ]: + - **First month of dues** [বকেয়া শুরুর মাস]. No dues are made before it, so switching fees + on in the middle of the year never charges past months. **No dues are created at all + until this is set.** + - Receipt SMS (on by default), a note printed on every receipt (for example office hours or + "Fees paid are not refundable"), the sibling discount rule. +2. **Fee heads** [খাত]: tuition, admission, exam, session and so on, each monthly, per term, + yearly or one-time, with its due day and an optional late fine (a fixed amount once, or an + amount per day up to a limit). Heads are deactivated, never deleted. +3. **Amounts** [পরিমাণ]: how much each class pays for each head this year. A group's amount + overrides the class amount. **Copy from another year** fills only what is missing. +4. **Terms** [সাময়িক]: for per-term heads, each term's opening and due dates. +5. **Concessions** [ছাড়]: per student and head: a fixed amount or a percentage, full or half + free studentship, or a scholarship (needs a reason), from a date. End a concession with a + reason; it is never deleted. +6. **Siblings** [ভাইবোন]: the app only **suggests** brothers and sisters (students sharing a + guardian phone). The sibling discount applies only to families an owner or admin confirms. + The student in the highest class pays in full. A student gets either the concession or the + sibling discount, whichever is larger, never both. +7. **bKash/Nagad numbers** [বিকাশ/নগদ নম্বর]: the institute's own numbers that guardians send + money to. **Only the owner** can change them. +8. **Fee collectors** [ফি আদায়কারী]: who can take money. Roles are changed on the Staff page + (8.2). + +Changes apply to new dues. A due already made keeps its amount. **Recalculate unpaid dues** +(owner, admin) rewrites dues nothing has been paid on. + +### 12.2 Dues + +A **due** is what one student owes for one head and one period (a month, a term, the year). +The app makes dues by itself when their period starts; opening a student at the counter always +brings their dues up to date. A student admitted in the middle of a period gets at least 7 +days to pay. + +### 12.3 Collect at the counter + +Who: accountant, owner, admin, or a teacher given fee collection. + +1. Fees → **Collect** [আদায়]. "Whose fees are you taking?" [কার ফি নেবেন?] Search by name, ID + or the guardian's **whole** phone number. +2. Open the student. Their ledger shows what is owed, with fines up to today. Overdue fees are + already ticked. Tick or untick what to collect. To take coming months in advance, choose + them too. +3. **Collect** [আদায় করুন]. +4. Type the **Amount** [টাকার অঙ্ক]. Less than the total is fine: the oldest fees are paid + first, then the fines. You cannot take more than is owed. +5. Choose the **Method** [মাধ্যম]: Cash [নগদ], bKash [বিকাশ] or Nagad. +6. Check "Where the money goes" and **Confirm** [আদায় নিশ্চিত করুন]. +7. The receipt opens. **Print receipt** [রসিদ প্রিন্ট] on A5 or an 80 mm thermal printer. + +If the internet dropped while confirming, pressing **Confirm** again sends the **same** +payment: the money is never recorded twice. + +The accountant sees guardian phones masked (`018•••••101`). The owner and admins see them in +full. + +### 12.4 Receipts + +- Numbered per institute and calendar year, with no gaps: `2026-000123`. +- Bangla, with the amount in words, the receipt number, ID and TrxID in English digits. +- After a payment the primary guardian gets a receipt SMS (if receipt SMS is on). This also + catches money taken without giving a receipt. + +### 12.5 Mistakes: void a receipt, cancel a due, waive a fine (owner, admin) + +Payments are never edited or deleted. + +- **Void a receipt** [রসিদ বাতিল করুন]: open the receipt → **Void** [বাতিল করুন], with a + reason. The fees it paid are owed again and their fines run again. The receipt is marked + VOID with the reason. Voiding does not give money back: **any refund happens outside the + app**. A receipt can be voided once. +- **Cancel a due**: only a due with nothing paid on it, with a reason. It stays in the list, + struck through, and is never charged again. If money was paid on it: "Void that receipt + first." +- **Waive a fine** [জরিমানা মওকুফ]: the whole fine (no more fine is added to that fee) or part + of it. + +An accountant who made a mistake: **ask your institute's admin** to void the receipt, then +collect again. + +### 12.6 bKash/Nagad payments to check + +Guardians (from their app: **I paid by bKash/Nagad**) or staff report a transfer with the +amount, the TrxID and the sender's number. + +1. Fees → **bKash/Nagad** [বিকাশ/নগদ যাচাই]. +2. For each one, find the TrxID in **the institute's own bKash/Nagad app or statement**. +3. **Verify** it if the money really arrived: a receipt is made, dated the day the guardian + reported it (so the fine stops there). Or **reject** it with a reason. + +A TrxID can be used only once. Jantrik does not check with bKash or Nagad: **the person +verifying is responsible for matching the TrxID**. (Online payment through a gateway is not +built yet.) + +### 12.7 Daily closing + +Fees → **Daily closing** [দিনের হিসাব]: for a date, per collector and method: collected, +voided, net, and "Cash that should be in hand" [হাতে নগদ থাকার কথা]. A void is counted on +the day it was made, so a closed day never changes later. An accountant sees only their own. +**Print** it at the end of the day. + +### 12.8 Reports + +Fees → **Reports**: **Dues** [বকেয়া তালিকা] by class and section, **Defaulters** [খেলাপি] +(overdue for at least N days and a minimum amount), **Collections** [আদায়] by day, month, head, +method or collector. Each prints and downloads as CSV. The lists cover students still here; a +student who left keeps their old dues on their own ledger. + +### 12.9 Reminders (owner, admin) + +Fees → **Reminders** [বকেয়ার রিমাইন্ডার SMS]: + +1. **See who would get one** [কতজন পাবেন দেখুন]: the students, those without a phone, those + already reminded, the number of SMS, the cost and what today's SMS limit leaves. +2. **Send SMS to N guardians**. If the numbers changed since you looked, the app asks you to + look again. + +One reminder per student per overdue period. If they pay before it goes out, it is cancelled. + +### 12.10 Messages + +| Message | What to do | +| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| "These fees changed meanwhile (now X owed). Check the new figures and confirm again." | Someone else collected or changed something. Read the new total and confirm. | +| "The earlier attempt may already have been recorded. Check the payments." | Look at the student's receipts before collecting again. | +| "Could not reach the server. Pressing again sends the same collection." | Press again when the internet is back. It will not be recorded twice. | +| "Money was paid on this fee, so it cannot be cancelled. Void that receipt first." | 12.5. | +| "Fee setup is for the owner and admins." | Ask your institute's admin to change heads, amounts or concessions. | +| "This student already has a concession on this fee for that time." | End the old concession first, then add the new one. | + +## 13. Exams and results + +Menu: **Exams & results** [পরীক্ষা ও ফলাফল]. In this release the office screens (setup, +locking, publishing, printing) are for the owner and admins; teachers enter marks. + +### 13.1 Exam setup (owner, admin, once) + +Exams → **Setup** [সেটআপ]: + +- **Subject marks** [বিষয়ের নম্বর]: each subject's parts (for example CQ, MCQ, practical) with + full and pass marks, and the pass rule (each part on its own, or parts of the same kind added + together across papers). **Fill in NCTB defaults** [এনসিটিবি অনুযায়ী ভরুন] fills subjects + that have no parts yet. +- **Subject teachers** [বিষয় শিক্ষক]: who enters marks for each subject in each section (up to + five people). Being the class teacher is not enough to enter marks: the person must be given + the subject. You can give every subject of a section to its class teacher in one step. +- **4th subject** [৪র্থ বিষয়]: which elective each student takes and which one is their 4th + subject. +- **Rooms** [কক্ষ]: exam rooms (rows × columns) for the seat plan. +- **Grading** [গ্রেডিং]: the grading scheme (read only in this release). + +### 13.2 Create and open an exam + +1. Exams → **New exam** [নতুন পরীক্ষা]: type (half-yearly, annual, pre-test, test, class test, + model test…), names, dates, and results by **GPA** (school exams) or **marks and + percentage** (coaching model tests). +2. Add the classes, their subjects and the routine. Everything can change until the exam is + opened. +3. **Open the exam** [চালু করুন]: each class's student list is taken now and teachers can + start entering marks. Once marks exist, a subject's parts cannot change. +4. After new admissions or section changes: Students → **Sync with enrolments** [ভর্তির সাথে + মেলান]. Students who left are withdrawn; their marks are kept but left out of results. + +### 13.3 Enter marks (teachers) + +1. Exams → **My mark sheets** [আমার নম্বরপত্র]: the subjects and sections you were given. +2. Open one. Type each student's marks. Enter moves down. Bangla digits are fine; at most two + decimals. Type **a**, **ab** or **অ** for absent. Empty means not entered yet. +3. The app saves by itself a few seconds after you stop typing. Like attendance, marks are + kept on the phone if the internet drops ("Kept on this phone"), and sent later. +4. When every student has marks or "absent", **Submit** [জমা দিন]. A sheet with empty cells + cannot be submitted. +5. Until the office locks it you can fix marks and **Submit again**. If the office returns it + [ফেরত পাঠান], you see their note under My mark sheets. + +Absent in any part fails the subject. + +### 13.4 Check and lock (owner, admin) + +For each sheet: **Return** [ফেরত পাঠান] with a note (back to the teacher), **Lock** [লক করুন], +or **Lock N submitted** [জমা দেওয়া Nটি লক করুন] for a whole class. After locking only the +owner or an admin can change a mark, with **Correct** [সংশোধন] and a reason. **Unlock** needs +a reason and is refused while results are published. Every change is kept in the sheet's +history. + +### 13.5 Remarks + +The class teacher (or owner/admin) writes remarks for the report cards. **To check:** the +remarks page and printouts are shown to the owner and admins in this release; whether class +teachers can reach them from the web. + +### 13.6 Publish + +1. Exam → **Results** [ফলাফল]. The page lists what blocks publishing (sheets not locked, + missing marks) and warnings (student list out of date, missing 4th-subject choices). +2. Before publishing, results shown are a "preview". +3. **Publish** [প্রকাশ করুন]. Guardians now see the results and report card in their app. +4. If marks or remarks change after publishing, the page says "changed since publish". + Guardians see the old version until you **Publish again** [আবার প্রকাশ করুন]. +5. **Unpublish** [প্রকাশ বাতিল] needs a reason; guardians stop seeing the results. +6. **Archive** [সংরক্ষণে রাখুন] freezes the exam. Published results stay visible. It can be + reopened. + +### 13.7 Printouts + +Browser print or "Save as PDF": + +- **Tabulation sheet** [টেবুলেশন শিট]: A4 landscape, also as CSV. +- **Report cards** [রিপোর্ট কার্ড]: one A4 page each, Bangla first, with the photo, + attendance over the exam period and the grading key. +- **Admit cards** [প্রবেশপত্র]: two per A4 page. +- **Seat plan**: per room. + +### 13.8 Result SMS (owner, admin) + +Never automatic. After publishing: Results → send results by SMS: + +1. The preview shows students, those without a phone, those already sent for this version, + the SMS count, the cost and today's limit. +2. **Send N** [Nটি পাঠান]. Over today's limit, the rest are **skipped, not held**. Send them + another day. + +The text is fixed: GPA and letter (or marks and %) and the class place. + +### 13.9 Messages + +| Message | What to do | +| -------------------------------------------------------------------------- | -------------------------------------------------------- | +| "Some cells are empty. Enter marks or mark absent for everyone." | Fill every cell, then submit. | +| "Someone else changed this mark sheet in the meantime." | Check the latest marks; choose keep mine or keep theirs. | +| "The results are published. Unpublish them first." | Correct with a reason instead, then publish again. | +| "The results changed in the meantime. Check the latest and publish again." | Another person published or changed something. | +| "This cannot be done while the mark sheet is in its current state." | For example a locked sheet: use Correct. | + +## 14. SMS: the daily limit + +All of an institute's SMS share **one daily limit**: absent SMS, receipts, reminders, result +SMS (and, after the PRs in section 15, admission and broadcast SMS). Sign-in and password codes +are paid by Jantrik and do not count. + +- The limit is set in Attendance → Settings → **Most SMS per day**: automatic (twice the + number of active students) or your own number. Jantrik may set a lower ceiling for your plan; + the settings page says so. +- **Absent SMS over the limit are held** [আটকে আছে]. The dashboard shows "N SMS held back + today" with **Send held SMS** [আটকে থাকা SMS পাঠান]. Each is checked again first (a student + who is now present gets none). Held SMS not sent by midnight are never sent. +- **Result SMS and entry/exit SMS over the limit are skipped.** +- A Bangla SMS holds 70 characters; a longer one costs one SMS per 67 characters. + +## 15. Coming soon: features in open PRs + +These are built in pull requests that are **not merged yet**. Screens and words may still +change. Each part applies **after its PR is merged**. + +### 15.1 Online admission, staff side (after PR #23 is merged) + +Owner and admin. New menu item **Admission** [ভর্তি]. + +1. **New admission cycle** [নতুন ভর্তি কার্যক্রম]: the academic year (usually next year), the + names, when the form opens and closes (Bangladesh time), whether there is an admission + test, whether to ask for the child's photo, which form fields are asked (not asked, + optional, required), and the classes with seats. +2. **Open the form** [ফর্ম চালু করুন] (needs at least one class). **Close the form** stops + it. +3. **Applications** [আবেদনসমূহ]: search, filter, CSV. Walk-in applications are typed by + staff. +4. Change an application's status: Submitted [জমা হয়েছে], Shortlisted [প্রাথমিক তালিকায়], + Selected [নির্বাচিত], Rejected [বাতিল] (reason required), Withdrawn [প্রত্যাহার] (reason + required). +5. **Approve as a student** [শিক্ষার্থী হিসেবে ভর্তি]: the child becomes a student of the + cycle's year with the applicant's guardian as primary guardian. If the guardian's number is + already known, pick the existing guardian or a new one. **Approve a class** [একটি শ্রেণি + ভর্তি করুন] admits every **Selected** application of a class into one section, in the + background. + +The same child cannot apply twice in one cycle (same birth registration number, or same phone, +name and date of birth); one phone can have at most three live applications per cycle. +Applications are never deleted. A child admitted in December for January owes fees from +January. + +### 15.2 The public admission form (after PR #24 is merged) + +Guardians apply from their phone without an account, at `/apply/`. The +cycle page shows the address to share. + +- Steps: class → phone → a code by SMS → the form → check → submitted, with an application + number to print or save. +- The status page asks for the application number and sends a code to the phone that applied. +- A "not a robot" check (Cloudflare Turnstile) protects the form. +- "Application received" SMS goes through the institute's daily limit; the code SMS does not. + +**To check:** how the institute should share the link (notice board, Facebook page, SMS). + +### 15.3 Admission test and merit list (after PR #27 is merged) + +For a cycle with an admission test. Owner and admin. Cycle page → a class → **Admission test** +[ভর্তি পরীক্ষা]. Tabs: + +1. **Setup and rolls** [বিবরণ ও রোল]: date, time, venue, full marks, pass marks (empty: nobody + fails), seats and waiting-list size; then **Issue rolls** [রোল দিন]. An issued roll never + changes. +2. **Admit cards** [প্রবেশপত্র]: two per A4, with the logo, photo and roll. +3. **Scores** [নম্বর]: one total score per applicant, or absent. +4. **Merit list** [মেধাতালিকা]: build it, check it, publish it. Statuses become Selected, + Waiting list [অপেক্ষমাণ] or Rejected. Only published Selected applicants can be approved. +5. **Result SMS** [ফলাফলের এসএমএস]: preview, then send. The SMS never shows the score. + +When a seat frees up, **move up** the waiting list. Applicants see their result on the status +page. + +### 15.4 Leaving, promotion and the new session (after PRs #21 and #22 are merged) + +**Leaving** (PR #21). Student page → **Leaves the institute** [প্রতিষ্ঠান ছাড়ছে]: graduated, +transferred or dropped out, the date, and an optional note. Nothing is deleted: old dues and +history stay. They leave attendance, the device and the due list from the next day, and free +their seat. **Came back** [ফিরে এসেছে] makes them active again. Fees → Reports gains "Leavers +with dues". + +**The new academic year** (PR #22). Setup → academic year → **New academic year** [নতুন +শিক্ষাবর্ষ]. Nothing switches by itself and no dues move. + +1. **The new year**: create it from the current one (sections copied), or pick one made. +2. **Fees**: copy amounts, terms and (optionally) running concessions. +3. **Teachers**: copy class, section and subject teachers by name. +4. **Promote, class by class** [শ্রেণি ধরে উত্তীর্ণ করুন]: for each class a list of who is + promoted, who repeats and who leaves, with defaults from the published annual results + (passed → promoted, failed → repeat, the top class → graduated). Change any row, then + **apply**. It runs in the background and can be resumed if it stops. +5. **Number the rolls** [রোল নম্বর দিন]: promoted students first (by merit, name or old roll), + then repeaters, then new admissions. Rolls already given are kept. +6. **Make it the current year** [চলতি বছর করুন]: a checklist of what is not finished, then the + switch. Students not enrolled in the new year leave the due list and attendance after the + switch. + +There is no "undo" for an applied list; single students are fixed afterwards on their page. + +### 15.5 Notices (after PR #25 is merged) + +- Everyone sees the **Notices** [নোটিশ] board, with "New" on unread ones and a count in the + menu. +- Owner and admin: **Manage notices** [নোটিশ পরিচালনা] → **New notice**: title, details, + **Who sees it** (everyone, staff, guardians), optionally only some classes or sections (for + guardians), a last day, and a pin. **Publish** now or at a later time (up to 30 days ahead). +- Edit a published notice (it shows "Edited"). **Withdraw** [প্রত্যাহার] with a reason takes + it off every board; it is kept on record. Notices are never deleted. +- Links in a notice are shown as text and cannot be clicked. +- The manage list shows how many have read each notice. + +### 15.6 SMS broadcasts (after PR #26 is merged) + +Owner and admin. Menu: **SMS broadcasts** [এসএমএস বার্তা]. + +1. **New broadcast** [নতুন বার্তা]: the message (sent exactly as typed, at most 3 SMS), **Send + to** [কাকে পাঠাবেন] primary guardians, all guardians or staff, and optionally some classes + or sections. +2. **Preview** [হিসাব দেখুন]: recipients, those without a phone, shared phones (sent once), + SMS per message, the estimated cost, and what today's limit leaves. +3. **Send now** or schedule it (5 minutes to 30 days ahead). + +Rules: + +- **All or nothing**: if it does not fit today's limit, nothing is sent. +- **Quiet hours**: nothing goes between 21:00 and 08:00. +- It is not sent if it would cost much more than you confirmed, or if it is found more than 3 + hours late; the dashboard says so, and **Edit and send again** starts over. +- A sent broadcast cannot be stopped. + +## 16. To check + +For the owner, before this guide goes to institutes: + +1. Walk through every numbered step on the running app (bn, phone and desktop) and fix the + wording to match the screens. +2. The SMS gateway: until it is connected nobody can receive a sign-in code (see the top). +3. What the Staff [কর্মী] role is meant to do: today it sees only the dashboard. +4. How a staff member who lost their phone or number gets back in (no admin reset today). +5. There is no "activate again" for a deactivated student, and no web screen to enrol an + existing student into another year (the API has one). +6. Which printouts use the institute's logo, signature and seal today. +7. Whether class teachers can reach remarks and report cards from the web in this release. +8. Devices: confirm the setup steps on a real ZKTeco device, and how to explain the "device + switched off and on again" limit to institutes. +9. How institutes should share the public admission link (after PR #24). +10. Names: the screens use the institute's own words; check the guide reads well for a coaching + centre ("Course", "Batch") and a madrasa. +11. A short printed "first day" sheet per role (teacher: 3.1, 3.2, 11.1; accountant: 3.1, 3.2, + 12.3, 12.7) may help more than this full guide. diff --git a/docs/legal/README.md b/docs/legal/README.md new file mode 100644 index 00000000..86d511d7 --- /dev/null +++ b/docs/legal/README.md @@ -0,0 +1,84 @@ +# Legal drafts: read this first + +> **DRAFT FOR LAWYER REVIEW — NOT LEGAL ADVICE. Not for publication or signature until reviewed +> by a lawyer qualified in Bangladesh.** + +Three drafts, written on 2026-11-18/19 from the product's code and docs by an assistant while the +owner was away. They describe only what the software does today and mark what is planned. + +| File | What it is | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| [terms-of-service.md](terms-of-service.md) | The agreement between Jantrik and each institute (the business customer). | +| [privacy-policy.md](privacy-policy.md) | The public notice: who decides what, what is held, how long, rights, cookies. | +| [school-data-custody-agreement.md](school-data-custody-agreement.md) | The data processing agreement: Jantrik handles Institute Data on its behalf; security, sub-processor, retention annexes. | + +The model: **the institute decides** (data fiduciary / controller-like), **Jantrik processes on +its behalf**. Most data is about children. Placeholders: `[Company legal name]`, `[address]`, +`[governing court]`, `[fee schedule]`, `[hosting provider]` and similar; `[to verify]` marks law +nobody has checked; `[to decide]` marks the owner's choices. + +## Bangladeshi law: what was checked + +Checked on the web on 2026-11-18 (news and secondary sources, **not the gazette texts**). Every +point below still needs the lawyer to confirm against the official text. + +| Law | What the sources say | Sources | +| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Personal Data Protection Ordinance, 2025 | Gazetted in November 2025 (Ordinance No. 61 of 2025), with the National Data Governance Ordinance, 2025. Reported: "data fiduciary" / "data processor" roles; parent or guardian consent for children; no profiling or targeted ads for minors; some sections in force 18 months after the gazette. | [TBS](https://www.tbsnews.net/node/1281356), [Daily Star](https://www.thedailystar.net/tech-startup/news/bangladeshs-personal-data-protection-ordinance-2025-key-takeaways-4015401), [Digital Policy Alert](https://digitalpolicyalert.org/change/18757-personal-data-protection-amendment-ordinance-2026-ordinance-no-23-of-2026) | +| Personal Data Protection (Amendment) Ordinance, 2026 | 5 February 2026 (No. 23 of 2026): narrowed data localisation to a synchronised copy in Bangladesh for some data (reports differ on which), dropped jail terms for some violations. | [Digital Policy Alert](https://digitalpolicyalert.org/event/38601-president-implemented-personal-data-protection-amendment-ordinance-2026-ordinance-no-23-of-2026) | +| **Personal Data Protection Act, 2026** | Parliament passed the Personal Data Protection Bill, 2026 on 9 April 2026; the Daily Star says it became an Act on 15 April 2026. Act number (63 of 2026?), commencement, rules, the authority's name and breach-notification duties: **[to verify]** (sources conflict). | [UNB](https://unb.com.bd/category/Bangladesh/parliament-passes-31-bills-related-to-ig-era-ordinances/183312), [Daily Star, 7 July 2026](https://www.thedailystar.net/slow-reads/big-picture/news/why-bangladeshs-new-data-protection-law-may-fail-protect-your-data-4217396), [Securiti (vendor)](https://securiti.ai/bangladesh-personal-data-protection-act-overview/) | +| Cyber Security Act, 2023 → Cyber Security Ordinance, 2025 | The 2023 Act was repealed and replaced by the Cyber Security Ordinance, 2025 (gazetted May 2025). | [Dhaka Tribune](https://www.dhakatribune.com/bangladesh/381943/govt-issues-gazette-of-cyber-security-ordinance) | +| Cyber security law of 2026 | Parliament replaced the ordinance with a Cyber Security Bill/Act, 2026 (April 2026; the exact date and name **[to verify]**), amended about 30 June 2026 (BTRC and other agencies may block content and request user data from platforms); further amendments proposed. | [Prothom Alo](https://en.prothomalo.com/bangladesh/wbq9kji6z7), [Dhaka Tribune](https://www.dhakatribune.com/bangladesh/parliament/414016/cyber-security-amendment-bill-2026-passes-in) | +| Information and Communication Technology Act, 2006 | Act No. XXXIX of 2006, amended 2013. Which sections still apply to a SaaS provider: **[to verify]**. | [ICJ brief](https://www.icj.org/wp-content/uploads/2014/06/Bangladesh-ICT-Brief-2013.pdf) | +| Payment and Settlement Systems Act, 2024 | Payment services and gateways need a Bangladesh Bank licence; a draft PSO regulation (2025) lists SSLCOMMERZ among operators. SSLCommerz's current licence: **[to verify]**. | [Dhaka Tribune](https://www.dhakatribune.com/amp/business/420801/bb-warns-against-22-unauthorized-online-payment) | +| BTRC and A2P SMS | BTRC licenses/enlists A2P SMS aggregators and has cancelled many (41 in January 2025, 22 in March 2026); limits on promotional SMS. The actual rules (hours, content, masking): **[to verify]**. The Bangladesh Telecommunications (Amendment) Bill, 2026 passed on 9 April 2026. | [Meatechwatch](https://meatechwatch.com/2026/03/03/btrc-cancels-certificates-of-22-a2p-sms-service-providers-over-noncompliance/), [UNB](https://unb.com.bd/category/Bangladesh/parliament-passes-31-bills-related-to-ig-era-ordinances/183312) | +| Consumer Rights Protection Act, 2009 | Act No. 26 of 2009. Whether it covers a business customer of a SaaS: **[to verify]**. | [FAOLEX](https://leap.unep.org/en/countries/bd/national-legislation/consumers-right-protection-act-2009-act-no-26-2009) | + +**Not checked at all [to verify]:** the Children Act, 2013; the Contract Act, 1872; the Evidence +Act, 1872 (electronic records); the Arbitration Act, 2001; the Right to Information Act, 2009 (for +government institutes); education-board and ministry record-keeping rules; VAT on software +services; Bangladesh Bank / mobile financial service rules on collecting fees into personal bKash +or Nagad numbers; any e-commerce or digital-commerce rules. + +## Open questions for the lawyer + +1. **The data protection Act.** Is the Personal Data Protection Act, 2026 in force, with which + commencement dates, rules and authority? Do the terms "data fiduciary", "data processor" and + "data custodian" fit this model (institute decides, Jantrik processes)? +2. **Children.** What consent is needed for children's data, from whom, in what form, and must + the software record it? Under 18 throughout? Anything special for madrasas and coaching + centres? +3. **Localisation.** Must any of this data (or a synchronised copy) stay in Bangladesh? Is a + server in Singapore or Mumbai allowed, and for backups? +4. **Sensitive data.** Are birth registration numbers, religion, blood group and photos + "sensitive" or "restricted", and what follows? +5. **Breach notification.** Who must notify (institute, Jantrik, both), whom, and how fast? Is + 48 hours from Jantrik to the institute right? +6. **Retention and erasure.** SMS logs, audit logs, attendance and payments are kept with no end + date today. Which need an end date, and which school records must institutes keep by law? Does + the right to erasure force a permanent-delete feature before go-live? +7. **Authorities.** Which laws let which authorities demand data from Jantrik directly, and may + Jantrik tell the institute? +8. **SMS.** What BTRC rules apply to an institute's SMS to its own guardians (absent alerts, + reminders, broadcasts)? What must the SMS provider contract contain? +9. **Fees into personal numbers.** May an institute collect fees on a personal bKash/Nagad + number? Should the terms warn against it? +10. **Liability.** A sensible cap, a higher cap for data breaches, and what cannot be excluded. +11. **Contract form.** Click-through in the app, a signed order form, or both; Bangla and English + versions, and which prevails. +12. **Disputes.** Courts (which?) or arbitration in Dhaka. +13. **Guardians.** Do guardians need their own short notice on first sign-in, given they never + sign the terms? +14. **Jantrik's own staff access.** What policy and logging is needed for engineers who can reach + the database directly? + +## Open questions for the owner + +1. Company legal name, registration, address, contacts, and a data protection contact. +2. Hosting provider and region; off-site backup storage; SMS provider (must be BTRC-licensed). +3. Fee schedule, trial length, invoice due days, late-payment suspension notice. +4. Support hours and channels; whether to promise an uptime target. +5. Export window and deletion period at the end, and building the full-export and deletion tools + before the first institute leaves. +6. Breach notice period to institutes (the drafts say 48 hours). +7. When to add end dates for SMS and audit logs. diff --git a/docs/legal/privacy-policy.md b/docs/legal/privacy-policy.md new file mode 100644 index 00000000..54250933 --- /dev/null +++ b/docs/legal/privacy-policy.md @@ -0,0 +1,236 @@ +# Jantrik School: Privacy Policy (DRAFT) + +> **DRAFT FOR LAWYER REVIEW — NOT LEGAL ADVICE. Not for publication or signature until reviewed +> by a lawyer qualified in Bangladesh.** +> +> Written on 2026-11-18 from the product's code and docs, by an assistant, while the owner was +> away. It describes only what the software does today, and says so where something is planned +> or depends on an open pull request (PR). Square brackets mark undecided facts and unchecked +> law (`[to verify]`). Open questions: [README.md](README.md). A Bangla version is needed before +> use; most readers will be guardians. + +**Version:** [version] · **Effective from:** [date] + +--- + +## 1. In short + +- Jantrik School is software that schools, madrasas and coaching centres ("**institutes**") use + to run their office: students, guardians, attendance, fees, exams and messages. +- **Your institute decides** what information about students, guardians and staff goes into + Jantrik School and what it is used for. **[Company legal name]** ("**Jantrik**", "**we**") + runs the software and handles that information **on the institute's behalf**, under a written + agreement with it. +- Most of this information is about **children**. We do not sell it, do not show advertising, + do not build profiles of children, and do not send them or their guardians marketing. +- For questions about a child's record, or to correct it, **contact the institute first**. We + help the institute answer. + +## 2. Who is responsible for what + +| Information | Who decides how it is used ("data fiduciary") | Jantrik's role | +| ------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------- | +| Students, guardians and staff, and everything the institute records about them ("Institute Data") | The institute | Processes it on the institute's instructions | +| The institute's account: its name, owner contacts, plan, invoices and payments to Jantrik | Jantrik | Decides | +| Sign-in security records (codes sent, sessions, failed attempts) and Jantrik's own staff accounts | Jantrik | Decides | + +The words "data fiduciary" and "data processor" come from Bangladesh's personal data protection +law. [to verify: the final terms used in the Personal Data Protection Act, 2026, and that this +split of roles matches it.] + +## 3. What information the software holds + +Only what the institute enters, or what the software creates from it. Not every institute uses +every part. + +**About students:** + +- name (Bangla and English), date of birth, gender, religion, blood group, birth registration + number, father's and mother's names, present and permanent address, a photo; +- student ID, academic year, class, section, group, roll, subjects and elective choices, + status (for example active or deactivated); +- attendance: each day's present, absent, late or leave, and who marked it; +- if the institute uses attendance devices: the person's device ID number and the time and + direction (in or out) of each punch. **Fingerprints, face data and photos from the device are + never received or stored by Jantrik**; they stay on the device; +- fees: dues, concessions and scholarships (with reasons), payments, receipts, bKash/Nagad + transaction IDs and the sender's number; +- exams: marks, results, positions, remarks, seat plans; +- after PRs #23, #24 and #27 are released: **admission applications** (the child's and + guardian's details typed into the online form, a photo if the institute asks for one, and + admission test rolls and scores). + +**About guardians:** name, mobile number, relation to the student, occupation, and which +children they are linked to. + +**About staff:** name, mobile number, email (optional), roles, sections and subjects they teach, +staff attendance (from devices or entered by the office), and who collected which payment. + +**About anyone who signs in:** + +- mobile number (and for staff, a password, stored only as a one-way hash); +- sign-in sessions: the type of client, the browser's description (user agent), the internet + (IP) address, and when the session was created and last used; +- a record that a sign-in code was sent to a number (never the code); +- display preferences (language; light or dark). + +**About the institute itself:** its names, address, contacts, EIIN, head's name and title, logo, +the head's signature image and the seal image. + +**Messages:** a log of every SMS the institute sends: the mobile number, the full text, the +purpose (for example "absent"), when it was sent, its status and its cost. + +**History:** an audit log records who created, changed or deleted important records (for +example marks, fees, payments, attendance, staff roles), with the old and new values. + +We do not collect any information from children directly. Children do not have accounts today. + +## 4. What it is used for + +Institute Data is used only to provide the service to the institute, for example to: + +- show staff the records their role allows (a teacher sees full details only of the students in + their own sections; an accountant sees guardian numbers partly hidden); +- show guardians their own children's attendance, fees and published results; +- send the SMS the institute has switched on or chosen to send: absent alerts, fee receipts and + reminders, exam results, and later admission and broadcast messages; +- print registers, receipts, report cards and other documents; +- keep the service secure and find faults. + +Jantrik uses its own information (section 2) to run accounts, bill institutes, count SMS costs, +keep sign-in secure and give support. + +Jantrik's own staff tools show institutes' **counts** (for example the number of active students +and SMS sent), never students' or guardians' names, numbers or records. This is enforced by the +database's permissions, not only by the screens. + +There is **no advertising and no analytics or tracking service** in the software today. [to +verify before any is added: this section must change first.] + +## 5. The legal basis + +[to verify with the lawyer under the Personal Data Protection Act, 2026:] + +- For Institute Data: the institute's basis (for example its education duties, the contract with + parents, and the consent of a parent or guardian for a child's data). The institute is + responsible for obtaining any consent the law requires. +- For Jantrik's own information: the contract with the institute, keeping the service secure, + and legal duties (for example tax records). + +## 6. Who can see it + +- **The institute's staff**, according to their roles (owner, admin, teacher, accountant). +- **Guardians**, for their own children only. Anyone using the same mobile number shares one + sign-in and sees every child linked to that number. +- **Service providers** that Jantrik uses to run the service ("sub-processors"), only as needed + for their job. The current list is in the School Data Custody Agreement, Annex B. In short: + the hosting provider [to decide], the SMS provider [to decide] and the off-site backup storage + [to decide]; later Cloudflare (for the "not a robot" check on the public admission form, after + PR #24) and SSLCommerz (for online payments, not live yet). +- **Authorities**, only when Bangladeshi law requires it, for example a lawful order under the + cyber security or data protection laws [to verify which laws give which authorities the power + to demand data, and how Jantrik should respond and inform the institute]. +- **Nobody else.** Jantrik does not sell or rent personal data. + +Each institute's data is kept separate from every other institute's (section 9). + +## 7. Where it is stored + +The service runs on servers at [hosting provider, country/region: to decide]. Photos, logos, +signature and seal images are stored in the same database. + +[to verify: whether the Personal Data Protection Act, 2026 (and the February 2026 amendment of +the earlier ordinance) requires a copy of some of this data to be kept inside Bangladesh, which +data counts as "restricted" or "sensitive" (children's data, birth registration numbers), and +what is needed for storage outside Bangladesh. The deployment guide currently suggests a region +near Bangladesh such as Singapore or Mumbai.] + +## 8. How long it is kept + +What the software does **today**: + +| Information | How long | +| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Student, guardian and staff records | While the institute uses the service. A student or staff member who is "deactivated" is hidden from lists but **not deleted**. | +| Attendance, staff attendance, fee payments and receipts, exam marks | Not deleted automatically. | +| Raw attendance-device punches | The institute's setting: 730 days by default (between 30 and 3650). Attendance made from them is kept. | +| Commands sent to attendance devices (they carry names and ID numbers) | Failed, cancelled and replaced commands are deleted 90 days after their last activity; the latest one per person and device is kept. | +| Student import files (with phone and birth registration numbers) | The uploaded rows are cleared when the import finishes or fails, or after 7 days if unfinished. A per-row result (row number, name, the problem) is kept. | +| SMS log (number, text, status, cost) | Not deleted automatically. | +| Audit log (who changed what, old and new values) | Not deleted automatically. | +| Sign-in codes | Stored only in scrambled (hashed) form, for 5 minutes; deleted once used. | +| Sign-in sessions | A session expires after 30 days without use. [to verify: when old session records are deleted.] | +| Attendance and marks drafts on a teacher's phone | Kept in that phone's browser until sent (attendance drafts: at most 7 days). They hold names, rolls and IDs, never phone numbers or photos. | +| Photos, logo, signature, seal | Until replaced or removed; then deleted from the database (copies remain in backups until those expire). | +| Admission applications (after PRs #23 and #24) | Not deleted. **Planned:** the personal data of rejected applications cleared 12 months after the admission cycle closes (decided, not built yet). | +| Backups | Nightly, kept 14 days on the server by default; off-site copies [to decide]. | +| When an institute leaves | [Export window, then deletion: see the Custody Agreement. Not built yet.] | + +[to verify: whether keeping SMS logs, audit logs and attendance with no end date is allowed under +the Personal Data Protection Act, 2026's rule that data is not kept longer than needed; and what +records schools must keep by law. Jantrik may need to add deletion periods.] + +## 9. How it is protected + +Measures the software has today (the full list, with what is planned: Custody Agreement, +Annex A): + +- every institute's records are tagged with the institute and the database itself refuses to + show one institute's rows to another (row-level security), as a second lock behind the + application's own checks; +- every screen and request checks the person's role and the institute's modules; +- passwords are stored only as strong one-way hashes (argon2id); sign-in codes are hashed, + expire in 5 minutes and work once; repeated attempts are limited; +- the web app and API are reached only over encrypted connections (HTTPS); +- an audit log of important changes; +- uploaded images are re-made by the server, which removes hidden details such as the location + a photo was taken; +- nightly backups, with a regular test that they can be restored. + +No system is perfectly secure. Attendance devices talk to the service over plain, unencrypted +internet connections because that is all the devices support; only an ID number and a time are +sent. + +## 10. Your rights + +Under Bangladesh's personal data protection law you may have rights to know what data is held +about you or your child, to get a copy, to have it corrected, to withdraw consent, and to have it +deleted in some cases. [to verify: the exact list, how requests must be made, time limits, and +exceptions, under the Personal Data Protection Act, 2026 and any rules made under it.] + +**How to use them:** ask the institute. If you contact Jantrik, we will pass your request to the +institute and help it answer, unless the law says we must answer directly. For information +Jantrik decides about (section 2), contact us directly. + +Contact: [name or role, email, phone, postal address]. + +## 11. Cookies and browser storage + +The web app uses only what it needs to work: + +- a secure sign-in cookie that keeps you signed in (it cannot be read by the page's scripts); +- a small cookie that tells the app you are signed in (it holds no personal data); +- for Jantrik's own staff, a separate session cookie; +- the browser's local storage, for unsent attendance and marks drafts and display preferences. + +No advertising or tracking cookies are used. + +## 12. If something goes wrong + +If a security breach puts Institute Data at risk, Jantrik will tell the affected institute +without undue delay and help it inform the authority and the people affected, as the law and +the Custody Agreement require. [to verify: whether the Personal Data Protection Act, 2026 +requires notification to the authority or to individuals, and the time limits.] + +## 13. Changes + +We will post any change here with its date, and tell institute owners in the app at least [30] +days before an important change. + +## 14. Contact and complaints + +[Company legal name], [address], [email], [phone]. [Data protection contact or Chief Data +Officer, if the law requires one: to verify.] + +You may also complain to the data protection authority [name of the authority under the Personal +Data Protection Act, 2026: to verify]. diff --git a/docs/legal/school-data-custody-agreement.md b/docs/legal/school-data-custody-agreement.md new file mode 100644 index 00000000..dd6ee064 --- /dev/null +++ b/docs/legal/school-data-custody-agreement.md @@ -0,0 +1,338 @@ +# Jantrik School: School Data Custody Agreement (DRAFT) + +> **DRAFT FOR LAWYER REVIEW — NOT LEGAL ADVICE. Not for publication or signature until reviewed +> by a lawyer qualified in Bangladesh.** +> +> Written on 2026-11-18 from the product's code and docs, by an assistant, while the owner was +> away. The annexes describe **only what the software does today**, and mark what is planned or +> waiting in an open pull request (PR). Square brackets mark undecided facts and unchecked law +> (`[to verify]`). Open questions: [README.md](README.md). A Bangla version is needed before use. + +This agreement is part of the Jantrik School Terms of Service ([terms-of-service.md](terms-of-service.md)) +between **[Company legal name]** ("**Jantrik**") and the institute named in the Order Form +("**the Institute**"). It says how Jantrik looks after the information the Institute puts into +Jantrik School. It is written in plain language on purpose: the Institute's head should be able +to read it and know what Jantrik will and will not do. + +--- + +## 1. The idea in one paragraph + +The Institute decides what information about its students, guardians and staff goes into Jantrik +School and why. Jantrik keeps that information safe and uses it **only** to run the service for +the Institute, in the way the Institute sets it up. Jantrik does not own it, sell it, advertise +with it, or use it for anything else. When the Institute leaves, it gets its information back +and Jantrik deletes it. + +## 2. Words used + +- **Institute Data:** all personal information the Institute, its staff or its guardians put into + the service, or that the service creates from it. Annex D lists the kinds. +- **Data fiduciary** and **data processor:** the roles under Bangladesh's personal data + protection law: the one who decides the purpose, and the one who handles data on its behalf. + [to verify: the exact terms and definitions in the Personal Data Protection Act, 2026, and + whether "data custodian" has its own meaning there.] +- **Sub-processor:** a company Jantrik uses that handles Institute Data for the service (Annex B). +- **Breach:** any event where Institute Data is lost, changed, seen or taken by someone who + should not have it. + +## 3. Roles + +3.1 The Institute is the **data fiduciary** for Institute Data. Jantrik is its **data +processor**. [to verify] + +3.2 The Institute is responsible for: + +- having a lawful basis for the data, including **a parent's or guardian's consent for a child's + data** where the law requires it [to verify: when consent is needed and in what form]; +- telling students, guardians and staff about the processing (Jantrik's Privacy Policy can help); +- the accuracy of what it enters, especially guardians' mobile numbers; +- who in the Institute has access, and with which roles; +- answering requests from students, guardians and staff about their data (section 8). + +## 4. Jantrik follows the Institute's instructions + +4.1 Jantrik processes Institute Data only: + +- to provide, secure, support and fix the service under the Terms of Service; +- as the Institute sets it up in the service. **The Institute's settings and actions in the + service are its instructions**: for example switching absent SMS on, publishing results, + sending reminders, inviting a teacher; +- where Bangladeshi law requires it (section 10). + +4.2 If Jantrik believes an instruction breaks the law, it will tell the Institute. + +4.3 Jantrik does **not**: + +- sell, rent or trade Institute Data; +- use it for advertising, or show advertising in the service; +- build profiles of children, or track them for any purpose other than the Institute's own + records; +- contact students or guardians for Jantrik's own purposes, except service messages the + Institute has switched on and sign-in codes; +- combine one Institute's data with another's. + +4.4 Jantrik may use **counts** (for example the number of active students, SMS sent, imports) +to bill the Institute and run the service. Jantrik's own staff screens show only such counts; +the database does not give them students' or guardians' details. + +## 5. Children's data + +Most Institute Data is about children. Jantrik treats all of it as needing special care: + +- access inside the Institute follows its roles (teachers see full details only of the students + in their own sections; accountants see guardian numbers partly hidden; guardians see only their + own children); +- images are re-made by the server and hidden details (such as a photo's location) are removed; +- attendance devices never send fingerprints, faces or photos to Jantrik; +- Jantrik will not use children's data to train or improve anything other than the service + itself, and will not use it in any automated decision about a child. [to verify: whether this + promise, and the ban on profiling minors reported for the 2025 ordinance, need more.] + +## 6. Jantrik's people + +6.1 Everyone at Jantrik who can reach Institute Data is bound by confidentiality. + +6.2 Only the people who run the servers can reach the database directly, and only to keep the +service working, fix faults, restore backups or follow the law. [to decide: a written access +policy: who, when, logged how, and whether the Institute is told. Today there is no separate log +of a server operator's direct database access.] + +6.3 Jantrik's platform staff (who onboard institutes and send invoices) use a separate login +with a password and an authenticator app, and see counts only (section 4.4). + +## 7. Security + +Jantrik keeps the measures in **Annex A** in place and improves them over time. It will not +reduce the overall level of protection during this agreement. + +## 8. Requests from students, guardians and staff + +8.1 Most requests the Institute can handle itself in the service: correcting a record, changing +a guardian's number, removing a photo, deactivating a student or staff member, or producing a +student's attendance, fee ledger or report card. + +8.2 Jantrik will help with anything the Institute cannot do itself, within [number] working +days of being asked, for example a full copy of one person's records. [to decide: fees for +unusual requests.] + +8.3 If a student, guardian or staff member contacts Jantrik directly, Jantrik will pass the +request to the Institute and not answer it itself, unless the law requires Jantrik to answer. +[to verify] + +8.4 **Not built yet:** a one-click "everything about this person" export, and a way to +permanently delete one person's records. Records today are deactivated, not deleted (Annex C). +[to verify: whether the right to erasure under the Personal Data Protection Act, 2026 requires +Jantrik to build permanent deletion before go-live, and which school records are exempt.] + +## 9. Sub-processors + +9.1 Jantrik may use the sub-processors in **Annex B**. Each is bound by a written agreement to +protect the data at least as well as this agreement requires. Jantrik is responsible for them. + +9.2 Jantrik will tell the Institute at least [30] days before adding or replacing a +sub-processor. If the Institute has a reasonable objection, the sides will discuss it; if it +cannot be solved, the Institute may end the agreement without penalty. + +## 10. Where the data is kept, and requests from authorities + +10.1 Institute Data is stored at [hosting provider, country/region: to decide]. + +10.2 [to verify: whether the Personal Data Protection Act, 2026 requires some or all of this +data, or a synchronised copy of it, to be kept inside Bangladesh, and what is needed for +storage or backups outside Bangladesh. The February 2026 amendment of the earlier ordinance +required a copy in Bangladesh for some data; reports differ on which.] + +10.3 If an authority asks Jantrik for Institute Data, Jantrik will check that the request is +lawful, give only what the law requires, and tell the Institute first unless the law forbids it. +[to verify: the powers under the cyber security law, the data protection law and the +telecommunication law, and whether "tipping off" restrictions apply.] + +## 11. Breaches + +11.1 Jantrik will tell the Institute's owner **without undue delay, and within [48] hours** of +becoming aware of a breach affecting the Institute's data, even if not all facts are known yet. +[to verify: the period the law requires, and whether 48 hours is achievable.] + +11.2 The notice will say, as far as known: what happened and when; what data and how many +people are affected; the likely effects; what Jantrik has done and will do; and a contact +person. Jantrik will update it as it learns more. + +11.3 Jantrik will help the Institute tell the data protection authority and the people affected +where the law requires. [to verify: who must notify (the Institute as fiduciary, Jantrik, or +both), to whom, and in what time. Reports on the final Act differ on whether it requires breach +notification at all.] + +11.4 Jantrik keeps a record of every breach, including small ones, and what was done. + +11.5 **Today:** there is no automated breach detection beyond server logs, health checks and the +backup alerts the deployment guide describes. [to decide] + +## 12. Backups + +12.1 Jantrik backs up the whole database (including photos and images) every night, checks each +backup, and keeps it for **14 days** on the server by default. A restore is tested regularly +(the deployment guide says once a month). + +12.2 [to decide: off-site backup storage, its location and how long it keeps copies. The +deployment guide treats an off-site copy as required but has not chosen one.] + +12.3 Deleted data stays in backups until those backups expire. + +## 13. When the agreement ends + +13.1 **Export.** For [30] days after the agreement ends, the Institute can sign in (read only +[to decide]) and export its data. Jantrik will also provide, on request within that time, a +complete export in a common format (for example CSV files and the images). **Today the service +has per-screen exports only** (attendance registers, fee reports, tabulation sheets, import +reports, as CSV or print); a full export must be built before the first Institute leaves. + +13.2 **Deletion.** After the export period Jantrik deletes Institute Data from the live service +within [30] days, and it disappears from backups as they expire (14 days by default, plus +[off-site period]). Jantrik will confirm the deletion in writing. **Today there is no deletion +tool**; it must be built and tested before the first Institute leaves. + +13.3 Jantrik may keep, for as long as the law requires, its own records: invoices, payments to +Jantrik and the Institute's account details. [to verify: tax and company record periods.] + +13.4 If the law requires the Institute to keep school records for a period, the Institute must +export them before deletion. Jantrik is not a records archive after the agreement ends unless +agreed separately. [to verify: record-keeping duties of institutes.] + +## 14. Information and audits + +14.1 Jantrik will answer the Institute's reasonable questions about how it protects the data, +including security questionnaires, within [number] working days. + +14.2 Once a year, or after a breach, the Institute may ask for a review of these measures, +with [30] days' notice, at its own cost, by a reviewer bound by confidentiality, without access +to other institutes' data. [to decide] + +## 15. Liability and term + +15.1 The liability terms of the Terms of Service apply. [to verify: whether a higher cap should +apply to data breaches.] + +15.2 This agreement lasts as long as Jantrik holds Institute Data. + +--- + +## Annex A: Security measures + +Status: **Built** = in the released code (`main`). **Merging** = built and reviewed, in an open +pull request that is about to merge. **Planned** = decided or proposed, not built. **Limit** = +a known weakness, stated openly. + +### A1. Keeping institutes apart + +| Measure | Status | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| Every institute's records carry the institute's ID, and every query is limited to the signed-in person's institute. | Built | +| The database itself also enforces this (PostgreSQL row-level security, forced on every institute table), so a mistake in the application cannot show another institute's rows. | Built | +| The application logs in to the database as an ordinary user that cannot switch this protection off; at start-up it refuses a login that could (superuser, bypass of row-level security, replication or role creation). | Built | +| Separate database logins, each with only the rights it needs: the main app, Jantrik's platform tools, the password check, and the attendance-device receiver. | Built | +| The ordinary application login cannot read password hashes; only the sign-in check can. | Merging (PR #16) | +| A signed request context, so that even an SQL injection could not pose as another person or institute. | Planned (PR #20) | +| Today, an SQL injection (if one existed) could still change who the request acts as and so take over an account. No such injection is known. | Limit (fixed by PR #20) | + +### A2. Who can see what + +| Measure | Status | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| Every page and request checks the person's role and whether the institute has that module. | Built | +| Teachers see full student details only for their own sections; accountants see guardian phone numbers partly hidden; guardians see only their own children (any other child's link answers "not found"). | Built | +| Jantrik's platform staff tools return counts only; the database grants them no access to students', guardians' or messages' details. | Built | +| Jantrik's platform staff sign in with a password and an authenticator app (with one-time backup codes), never SMS, and their actions are logged. | Built | + +### A3. Sign-in + +| Measure | Status | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| No public sign-up: only people an institute (or Jantrik, for a first owner) added can sign in. | Built | +| Sign-in codes: 6 digits, valid 5 minutes, 5 tries, single use, stored only as a keyed hash; limits per phone (10 a day) and per address. | Built | +| Staff passwords: at least 10 characters, not the phone number or the institute's name, not a common password; stored with argon2id; 5 wrong tries per 15 minutes. | Built | +| The app never says whether a number or account exists. | Built | +| Sessions: short-lived access tokens kept only in memory; the long-lived token in a secure, script-proof cookie, stored only as a hash and replaced on every use; reuse of an old token ends the session. | Built | +| Sign-out ends the session at once; setting a password signs out every other device. | Built | +| A screen showing a person's signed-in devices; password reset by an admin. | Planned | + +### A4. Network and servers + +| Measure | Status | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| The web app, the API and Jantrik's platform area are served only over HTTPS (automatic certificates, HSTS). | Built (deployment guide) | +| The server's firewall opens only SSH, web (80, 443) and the device port (4080); the database and Redis are not reachable from the internet. | Built (deployment guide; confirm on server) | +| Secrets (database passwords, signing keys) live only in the server's settings file, never in the code. Authenticator secrets for Jantrik's staff are encrypted (AES-256-GCM). | Built | +| Attendance devices connect over plain HTTP, because ZKTeco devices support nothing else. Only a device ID number, a time, in/out and how the person verified are accepted; everything else the device sends is thrown away unread. Devices are identified by serial number, and commands go only to an address the Institute has trusted. | Limit | +| The device receiver runs as its own program with its own database login that can read no table. | Built | +| Encryption of the database and backups at rest (beyond what the hosting provider's disks offer). | Planned [to decide] | +| An uptime monitor with alerts. | Planned (owner to choose) | + +### A5. Records and history + +| Measure | Status | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| An audit log of creating, changing and deleting important records (marks, fees, payments, attendance, staff roles, setup), with who, when, and the old and new values. | Built | +| Payments, receipts and marks are never edited or deleted; mistakes are voided or corrected with a reason, which is kept. | Built | +| Uploaded images are checked (JPEG, PNG or WebP only), re-made by the server, shrunk, and stripped of hidden details such as location. | Merging (PR #18) | +| An institute-facing screen to read the full audit log. | Planned [to decide] | + +### A6. Backups + +| Measure | Status | +| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| Nightly backup of the whole database (images included), with a checksum, private files, kept 14 days by default. | Built (deployment guide) | +| A restore tool that refuses unsafe restores, and a restore check that compares a restored copy with the live database. | Built | +| The restore check runs on every code change in CI; on the server the guide says monthly. | Built | +| An off-site copy of every backup. | Planned (owner to choose) | +| An alert when the last good backup is older than a day. | Built (deployment guide, cron) | + +## Annex B: Sub-processors + +| Sub-processor | What it does | Data it handles | Where | Status | +| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- | ---------------------- | ---------------------------------- | +| [Hosting provider] | Runs the servers, disks and network | All Institute Data (stored on its machines) | [country/region] | To decide | +| [SMS provider, a BTRC-licensed A2P aggregator] | Delivers SMS to mobile networks | Mobile numbers and message texts | Bangladesh [to verify] | To decide; required before go-live | +| [Off-site backup storage] | Keeps copies of backups | All Institute Data (inside backup files) | [country/region] | To decide | +| Cloudflare (Turnstile) | "Not a robot" check on the public admission form | The visitor's browser signals and internet address; no form content | [to verify] | After PR #24 is merged | +| SSLCommerz | Online fee payments | Payment details; the payer's name and contact [to verify] | Bangladesh | Planned (not live) | +| Let's Encrypt | Issues HTTPS certificates | Only the service's domain names; no personal data | — | Not a sub-processor [to verify] | + +Jantrik does not use any analytics, advertising, email-marketing or error-tracking service +today. + +## Annex C: How long data is kept (what the software does today) + +| Data | Kept | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Students, guardians, staff | During the agreement. "Deactivate" hides a record; nothing is deleted. | +| Attendance registers and records, staff attendance days | Not deleted. | +| Raw device punches | The Institute's setting, 730 days by default (30 to 3650); the database never lets the app delete the last 30 days. | +| Device commands (names and ID numbers sent to devices) | Failed, cancelled or replaced ones: deleted 90 days after their last activity. The latest per person and device: kept. | +| Fee dues, payments, receipts, voids | Not deleted. | +| Exam marks, results, remarks and their history | Not deleted. | +| Student import files | Uploaded rows cleared when the import ends, or after 7 days unfinished (a daily job). Per-row results (row number, name, the problem) kept. | +| SMS log (number, text, status, cost) | Not deleted. | +| Audit log | Not deleted. | +| Sign-in codes | Hashed, 5 minutes, deleted on use. | +| Sessions (browser description, IP address, times) | Expire after 30 days unused. [to verify: deletion of old rows] | +| Photos, logo, signature, seal | Until replaced or removed (then deleted in the same step). | +| Admission applications (after PRs #23 and #24) | Not deleted. **Planned:** rejected applications' personal data cleared 12 months after the cycle closes (decision S30; not built). | +| Notices and SMS broadcasts (after PRs #25 and #26) | Not deleted; withdrawn notices kept for the record. | +| Backups | 14 days on the server by default; off-site [to decide]. | + +[to verify with the lawyer: which of these "not deleted" periods must get an end date under the +data protection law, and which records institutes must keep by law.] + +## Annex D: Description of the processing + +- **People:** students (mostly children), applicants for admission, guardians, the Institute's + staff. +- **Data:** as listed in the Privacy Policy, section 3. Includes birth registration numbers, + religion and blood group (possibly "sensitive" data [to verify]), photos, attendance, fees and + exam results. No biometric data. +- **Purpose:** running the Institute's administration through the service, as set out in the + Terms of Service. +- **What is done with it:** storing, organising, showing to authorised users, printing, sending + SMS, backing up, and deleting at the end. +- **Duration:** the agreement, then the export and deletion periods in section 13. diff --git a/docs/legal/terms-of-service.md b/docs/legal/terms-of-service.md new file mode 100644 index 00000000..6b1b325d --- /dev/null +++ b/docs/legal/terms-of-service.md @@ -0,0 +1,286 @@ +# Jantrik School: Terms of Service (DRAFT) + +> **DRAFT FOR LAWYER REVIEW — NOT LEGAL ADVICE. Not for publication or signature until reviewed +> by a lawyer qualified in Bangladesh.** +> +> Written on 2026-11-18 from the product's code and docs, by an assistant, while the owner was +> away. Square brackets mark facts nobody has decided yet (`[Company legal name]`) and points of +> law nobody has checked yet (`[to verify]`). Nothing in brackets may be filled in by guessing. +> Open questions for the lawyer: [README.md](README.md). A Bangla version is needed before use. + +**Version:** [version] · **Effective from:** [date] + +--- + +## 1. Who these terms are between + +1.1 These terms are an agreement between **[Company legal name]**, a company registered in +Bangladesh under [registration number], with its office at [address] ("**Jantrik**", "**we**", +"**us**"), and the school, madrasa, coaching centre or other education institute that uses +Jantrik School ("**the Institute**", "**you**"). + +1.2 The person who accepts these terms for the Institute (usually its owner, principal or head) +confirms that they have the authority to bind the Institute. [to verify: how acceptance is +recorded: a signed order form, a click in the app, or both.] + +1.3 These terms come with: + +- the **Order Form** or plan the Institute agreed with Jantrik (modules, prices, limits, trial); +- the **School Data Custody Agreement** ([school-data-custody-agreement.md](school-data-custody-agreement.md)), + which says how Jantrik handles the data the Institute puts into the Service; and +- the **Privacy Policy** ([privacy-policy.md](privacy-policy.md)). + +If they conflict, the order is: the Custody Agreement (for anything about Institute Data), then +the Order Form, then these terms, then the Privacy Policy. [to verify: the order of precedence.] + +## 2. Words used in these terms + +- **Service:** Jantrik School, the online software that Jantrik runs for institutes: the web app, + its mobile screens, its SMS messages, and any later mobile app. +- **Module:** a part of the Service that is switched on per Institute, such as Attendance, Fees + or Exams. The core (students, guardians, classes, staff) is always on. +- **Institute Data:** all information the Institute, its staff or its guardians put into the + Service, or that the Service creates from it (for example attendance, fee and result records). + Most of it is about **children**. +- **Staff Users:** people the Institute adds as owner, admin, teacher, accountant or staff. +- **Guardians:** parents or guardians whose mobile number the Institute records for a student. + They can sign in with an SMS code to see their own children only. +- **Plan:** the prices, limits (such as the number of students and the daily SMS ceiling) and + billing cycle in the Order Form. + +## 3. Accounts and sign-in + +3.1 **No public sign-up.** Jantrik creates the Institute's account and invites its first owner +by mobile number. The owner then invites the Institute's other staff. Guardians get access +because the Institute records their mobile number for a student. + +3.2 **The Institute decides who has access.** The Institute chooses who is a Staff User, what +roles they have, which sections they teach, and which guardian numbers are on each student's +record. It removes access when someone leaves. Jantrik does not check whether a person really +works at the Institute or is really a child's guardian. + +3.3 **One mobile number, one login.** Everyone who uses the same mobile number shares one +sign-in. Whoever holds that phone sees every child linked to that number. The Institute should +record each guardian's own number. [to verify: whether this needs a stronger warning in the +admission form.] + +3.4 **Users keep their sign-in safe.** Staff Users must keep their phone and password to +themselves, sign out of shared computers, and tell the Institute at once if they think someone +else used their account. The Institute must make sure its Staff Users follow this. + +## 4. What the Institute is responsible for + +4.1 **Permission to use the data.** The Institute is responsible for having a lawful basis to +put Institute Data into the Service, including any **consent of a parent or guardian** that the +law requires for children's data, and for telling students, guardians and staff how their data +is used. [to verify: what the Personal Data Protection Act, 2026 requires of the Institute as +the party that decides the purpose, and whether the Service should collect or record that +consent.] + +4.2 **Accurate records.** The Institute keeps names, classes and especially **guardian phone +numbers** correct. SMS go to the numbers the Institute records. + +4.3 **What the Institute sends.** The Institute is responsible for the content and timing of +messages it sends through the Service (for example the absent-SMS text it writes, and notices +and SMS broadcasts once those features are released), and for having a reason to send them. + +4.4 **Money.** The Service keeps records of fees and payments; it does not hold or move money. + +- Cash is collected by the Institute's own staff. +- For bKash or Nagad, guardians send money directly to numbers the Institute owns. The + Institute's staff check each transaction ID in the Institute's own account before marking it + verified. **Jantrik does not check bKash or Nagad transactions** and is not responsible for a + transaction that a staff member verified wrongly. [to verify: whether Bangladesh Bank or + mobile financial service rules allow an institute to collect fees on a personal bKash/Nagad + number; the Service lets the owner list personal, merchant or agent numbers.] +- Voiding a receipt in the Service does not refund money. Refunds happen outside the Service. + +4.5 **The Institute's own duties.** The Institute remains responsible for its duties to +education boards, the government, students and guardians, including keeping records for as long +as those rules require. [to verify: record-keeping duties of schools and madrasas in +Bangladesh, and how they interact with deletion at the end of this agreement.] + +4.6 **Equipment and internet.** The Institute provides its own computers, phones, printers, +internet connection and any attendance devices. + +## 5. Acceptable use + +The Institute and its users must not: + +- use the Service for anything unlawful, or to harass, threaten or defame anyone; +- put in data they have no right to use, or data about people who have nothing to do with the + Institute; +- send SMS that are advertising for third parties, or that break the rules of the Bangladesh + Telecommunication Regulatory Commission (BTRC) [to verify: which BTRC rules apply to an + institute's messages to its own guardians]; +- try to see another institute's data, test the Service's security without Jantrik's written + permission, overload it, or get around its limits; +- copy, resell or reverse-engineer the Service, except as the law allows; +- share sign-in codes or passwords. + +Jantrik may suspend a user or the Institute's access (section 11) to stop serious misuse. + +## 6. What Jantrik provides + +6.1 **The Service.** Jantrik provides the Service and the Modules in the Order Form, and keeps +them working and secure with reasonable care and skill. What each Module does is described in +Jantrik's staff guide [link when published]. + +6.2 **Availability.** Jantrik aims to keep the Service available at all times but does not +promise it will never stop. Planned maintenance will be announced [how far ahead] where +possible. [to decide: whether to offer an uptime target or service credits; none exists +today.] + +6.3 **Support.** [Support hours, channels (phone, email, WhatsApp), response times.] + +6.4 **Changes.** Jantrik improves the Service over time. It will not remove a core feature the +Institute relies on without [notice period] notice, unless the law or security requires it. + +6.5 **Features still being proven.** Some features are new and depend on outside equipment or +services. In particular, **attendance devices** (ZKTeco fingerprint, card or face machines) have +so far been tested only with a simulated device; the Institute should test its own device +before relying on it. Jantrik will say clearly in the Service or the Order Form which features +are in trial. [to verify: how to word this.] + +## 7. SMS + +7.1 The Service sends SMS (sign-in codes, absent alerts, fee receipts and reminders, exam +results, and later admission and broadcast messages) through a Bangladeshi SMS provider +[provider name; to verify that it is a BTRC-licensed or enlisted A2P SMS aggregator]. **No +provider is connected yet.** + +7.2 SMS delivery depends on the provider and the mobile networks. Jantrik does not promise that +every SMS arrives or arrives on time. + +7.3 Each Institute has a **daily SMS limit**, which it sets (by default twice its number of +active students) and which its Plan may cap. Some messages over the limit are held for the +Institute to release; others are skipped. The Service shows the cost before bulk sends. + +7.4 SMS sent for the Institute are charged as set out in [fee schedule]. Sign-in and password +codes are not charged to the Institute. + +7.5 Jantrik may stop or delay messages to protect the Service, the networks or recipients, or +to follow the law. + +## 8. Online payments (not live yet) + +The Service does not take online card or mobile-wallet payments today. Jantrik plans to add +online fee payment through **SSLCommerz** [to verify: SSLCommerz's licence under the Payment +and Settlement Systems Act, 2024]. When it does, separate terms will apply, including who bears +the gateway's charges (the current plan: the Institute) and how refunds and disputes work. + +## 9. Fees and invoices + +9.1 The Institute pays the prices in its Order Form. Today Jantrik's plans can be priced per +active student per month for each Module, or as a flat monthly price, billed monthly or yearly. +[fee schedule] + +9.2 **Trial.** A new Institute may start on a free trial until [date]. Jantrik does not invoice +an Institute while it is in trial. + +9.3 **Invoices** are issued by Jantrik for each billing period and are due [10] days after they +are issued. The owner sees unpaid Jantrik invoices on the dashboard. [to verify: VAT and other +taxes on the Service; whether prices include them.] + +9.4 **Late payment.** If an invoice is not paid [number] days after it is due, Jantrik may, +after written notice of at least [number] days, suspend the Institute's access (section 11). +The Service does not suspend anyone automatically. Data is kept during a suspension. + +9.5 **Price changes** apply to invoices issued after [notice period] notice. + +## 10. Data + +10.1 **The Institute's data stays the Institute's.** Jantrik handles Institute Data only to +provide the Service, and only as the School Data Custody Agreement says. Jantrik does not sell +Institute Data, does not use it for advertising, and does not contact students or guardians for +its own marketing. + +10.2 **What Jantrik keeps for itself.** Jantrik keeps the Institute's account, contact and +billing details, and counts of use (such as the number of active students and SMS sent) to run +and bill the Service. Jantrik's own staff screens show these counts, not students' or guardians' +details. + +10.3 **Security, breaches, sub-processors, export and deletion:** see the Custody Agreement. + +## 11. Suspension and ending this agreement + +11.1 **Suspension.** Jantrik may suspend access, after notice where it reasonably can, for +unpaid invoices (section 9.4), serious misuse (section 5), a security threat, or if the law +requires it. Suspension takes effect at once in the Service; data is kept. + +11.2 **Ending by the Institute.** The Institute may end this agreement at any time with +[notice period] written notice. [to decide: refunds of prepaid yearly plans.] + +11.3 **Ending by Jantrik.** Jantrik may end this agreement with [notice period] written notice, +or at once if the Institute seriously breaks these terms and does not fix it within [number] +days of notice. + +11.4 **What happens to the data.** On ending, the Institute can export its data for [30] days +and then Jantrik deletes it, as the Custody Agreement says. **Today the Service has per-screen +exports (CSV and print) but no single "export everything" tool, and no deletion tool; both must +be built before the first Institute leaves.** + +11.5 Sections 4.4, 10, 12, 13, 14 and 16 continue after the agreement ends. + +## 12. Intellectual property + +Jantrik owns the Service, its software, design and documentation. The Institute owns (or has +the rights to) Institute Data, its name, logo, seal and signature images. The Institute lets +Jantrik use these only to provide the Service. + +## 13. Confidentiality + +Each side keeps the other's non-public information confidential and uses it only for this +agreement, except where the law requires disclosure. [to verify: standard wording under +Bangladeshi contract law.] + +## 14. Warranties, liability and indemnity + +14.1 Except as these terms say, the Service is provided "as is". [to verify: which implied +terms cannot be excluded under Bangladeshi law, including the Consumer Rights Protection Act, +2009, if it applies to a business customer.] + +14.2 **Limit.** Neither side is liable for indirect or consequential loss. Jantrik's total +liability in any 12 months is limited to [the fees paid in those 12 months / amount]. This limit +does not apply to [fraud, wilful misconduct, and anything the law does not allow to be +limited]. [to verify] + +14.3 **Indemnity.** The Institute is responsible for claims that arise because it put data into +the Service without the right to do so, or sent messages it should not have sent. Jantrik is +responsible for claims that the Service itself infringes someone's intellectual property. +[to verify] + +## 15. Changes to these terms + +Jantrik may change these terms with at least [30] days' notice to the Institute's owner, in the +Service and by [email/SMS]. If the Institute does not agree, it may end the agreement before the +change takes effect. + +## 16. Law and disputes + +16.1 These terms are governed by the laws of Bangladesh. + +16.2 The sides will first try to settle a dispute by talking, for [30] days. If that fails, +[the courts of [governing court] / arbitration in Dhaka under the Arbitration Act, 2001 [to +verify]] will decide it. + +## 17. General + +- **Notices** to Jantrik go to [address/email]; to the Institute, to its owner's contact details + in the Service. +- Neither side may transfer this agreement without the other's consent, except Jantrik to a + company that takes over the Service, with notice. +- Neither side is liable for delays caused by events outside its reasonable control (for + example a nationwide internet shutdown). +- If a part of these terms is invalid, the rest stays in force. +- This is the whole agreement about the Service. + +--- + +## Notes for the lawyer (delete before publication) + +- The Institute is the business customer. Guardians and students do not sign these terms; their + access is under the Institute's control. Should guardians see a short separate notice when they + first sign in? [to verify] +- Laws named here and their status (with sources): [README.md](README.md) → "Bangladeshi law: + what was checked". 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 00000000..1e361124 --- /dev/null +++ b/docs/plans/sprint-1-p1j-password-hash.md @@ -0,0 +1,300 @@ +# 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. + +## 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). +- **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 +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. **(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. + +## 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. diff --git a/docs/plans/sprint-1-p2-files.md b/docs/plans/sprint-1-p2-files.md new file mode 100644 index 00000000..278fb1d0 --- /dev/null +++ b/docs/plans/sprint-1-p2-files.md @@ -0,0 +1,455 @@ +# 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.** A student's photo is part of the full record, as on the student's page + (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, guardians for their own + children only; anyone else gets 404. 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. + +## Changed after the review (2026-11-16) + +- **R1. Uploads no longer run inside the request transaction** (must-fix). `TenantContextInterceptor` + (a global interceptor) opened the 15 s transaction and took a pool connection before multer read + the body: a 2–5 MB photo on slow 4G took longer than 15 s (a 500 every time), and ten slow + uploads could hold all 10 connections (every other institute failing). The two upload routes + are now `@OwnTransaction()`: the body is read, the upload limit applied and the image decoded + with no connection; then `RequestTransaction.run` (the interceptor's own logic, moved into a + service) opens the same tenant transaction for the short store. The image queue is bounded (8 + waiting; more get 503 `IMAGE_BUSY`), and the browser shrinks a chosen image to 1600 px on the + long side (JPEG 0.85 for photos, PNG for the others) before sending, so a phone sends about + 300 KB. Test: while a slow body arrives, no session of the app login is idle in a transaction. +- **R2. The code scan also catches Prisma relation fields** (`photoFile`, `logoFile`, + `signatureFile`, `sealFile`, `storedFiles`, `storedFileUsage`, `storedFilesCreated`, the + `profile*` back-relations). +- **R3. The guardian's report card shows the photo** through `/me/children/:id/photo` + (`ReportCardsPrint as="guardian"`); Playwright checks it in the exams spec. +- **R4. The web address's scheme is stored in lower case** (`HTTPS://x` → `https://x`), as the + database CHECK is case-sensitive; it was a 500. +- **R5. The image queue hands a freed slot straight to the next waiter**, so it can never run + three at once. +- **R6. A file reference is tied to its kind in the database.** `stored_files` has + `UNIQUE (tenant_id, id, kind)`; `students.photo_file_kind` (always `STUDENT_PHOTO`) and + `institute_profiles.logo_file_kind`, `head_signature_file_kind`, `seal_file_kind` (always + `LOGO`, `SIGNATURE`, `SEAL`, by CHECK) are part of each foreign key, so a photo column can only + hold a photo, a logo column a logo, and so on. +- **R7. Replacing an image near the cap is allowed** when the total would not grow: `put` takes the + id it replaces (read under the file lock) and counts it. +- **R8. The first image and the first save cannot collide:** the row an image creates is inserted + with `ON CONFLICT DO NOTHING`. +- **R9.** F1 above now says what the code does (a teacher sees photos of their own sections only). +- **R10.** The database tests name the rule that refuses each write; a PNG `eXIf` GPS case was + added to the image tests. + +## Changed after the review, round 2 (2026-11-16) + +- **R11. Uploads in flight are bounded.** With R1 nothing limited how many upload bodies could be + in memory. `UploadGuard` (before multer) allows 16 per process and 2 per person, refuses more at + once with 503 `IMAGE_BUSY`, gives the slot back when the response closes (sent, failed or + dropped by the client), and drops a body not received within 60 s. +- **R12. `RequestTransaction.run` refuses to nest** inside a request transaction (it would replace + the outer one in the request context). The interceptor itself uses an unchecked entry (`around`): it is the outermost transaction, and a request made from inside a running job (as some tests do) inherits that job\'s request context. +- **R13. The upload's transaction re-checks the session and the route's roles** (OWNER/ADMIN), + read in the transaction, besides the institute's status and the membership: an admin + downgraded, or a session revoked, while the body arrives stores nothing (403 / 401). +- **R14. The target is checked before decoding:** a student photo for an unknown or deactivated + student, or any upload in a suspended institute or by someone who lost the role, is refused + before the image is decoded or the upload quota is used. +- **R15. sharp's own 10 s timeout** on the decode and each encode → 422 `IMAGE_TIMEOUT`. +- **R16. A replacement no bigger than the old file is never refused**, even when the total is over + a lowered cap; `FileStore.put`'s contract says the caller deletes the replaced file in the same + transaction. +- **R17. A profile save takes the file lock before reading the row**, so a first save racing a + first image is audited as an UPDATE (one CREATE per institute). +- **R18. The browser asks for the EXIF orientation explicitly** (`imageOrientation: +'from-image'`); an engine without it sends the original, which the server turns upright. +- **Tests:** a deterministic database test of the ON CONFLICT path (an insert held uncommitted); + the slow-body check sampled every 100 ms, for the logo route too; suspended institute and + disabled member → 403 with nothing stored; the signature column's wrong kind; the exams spec + removes the demo child's photo in an `afterEach`. +- **Migrations edited in place:** both migrations of this PR changed after it was first pushed + (R6). Nothing outside this run's scratch databases applied them; any database that did needs + a fresh one (or a reset) before applying the final versions. + +## Changed after the review, round 3 (2026-11-16) + +- **R19. No upload slot leaks when the client leaves early** (must-fix). If the socket closed while + the global guards awaited Redis, the response's one 'close' event was already past when + `UploadGuard` listened for it, so the slot was never given back. A client already gone (the + test on-finished uses: the request or response destroyed, the answer sent, or the socket no + longer writable) now gets no slot, and every slot is given back after 5 minutes at the latest + (a backstop). +- **R20. The revoked-session check runs before the transaction**, with Redis's 2 s deadline (503 + `SERVICE_UNAVAILABLE`), so a slow Redis never holds a pooled connection; the roles are still + read in the transaction. +- **R21. A browser that predates `imageOrientation`** (a TypeError) decodes without it when the + photo needs no turning (no EXIF orientation, or 1; a small JPEG reader checks), and sends the + original otherwise (the server turns it upright). +- **R22.** The timeout test uses sharp 0.35.5's real message (`timeout: N% complete`). + +## 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. 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 00000000..b323c827 --- /dev/null +++ b/packages/db/prisma/migrations/20261116000000_users_password_hash_hidden/migration.sql @@ -0,0 +1,90 @@ +-- P1-J: the app login (jantrik_app) never reads a password hash, its own or anyone's, so an SQL +-- 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. +-- +-- 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 +-- 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(): no password data ───────────── +-- It returned password_hash of any user by phone or email, which made the column grant above +-- 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 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 + SET search_path = pg_catalog, public, pg_temp + AS $$ + 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)) + 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_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. +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 + SET search_path = pg_catalog, public, pg_temp + AS $$ + 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_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. +DROP FUNCTION IF EXISTS auth_my_password_is_set(); +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/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 00000000..f4f25d79 --- /dev/null +++ b/packages/db/prisma/migrations/20261116100000_files_and_institute_profile/migration.sql @@ -0,0 +1,201 @@ +-- 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, + "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, + + 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 (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"); + +-- 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_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_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_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; + +-- 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_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_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_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; +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 + ), + -- 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 + 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 00000000..7894ee21 --- /dev/null +++ b/packages/db/prisma/migrations/20261116100100_students_photo_file/migration.sql @@ -0,0 +1,17 @@ +-- 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_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_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_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 493b2648..7aa32919 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") } @@ -996,34 +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? - photoUrl String? @map("photo_url") - status StudentStatus @default(ACTIVE) + /// The student's photo (stored_files, kind STUDENT_PHOTO); replaced files are deleted. + 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, photoFileKind], references: [tenantId, id, kind], onDelete: Restrict, onUpdate: Restrict) guardians StudentGuardian[] enrolments Enrolment[] @@ -1042,6 +1052,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, photoFileKind]) @@index([tenantId, status], where: raw("deleted_at IS NULL")) @@index([tenantId, nameEn]) // Trigram indexes for ILIKE '%…%' search (GET /students). @@ -3112,3 +3124,112 @@ 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]) + // What the kind-bound foreign keys point at. + @@unique([tenantId, id, kind]) + @@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 + /// 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, 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, logoFileKind]) + @@unique([tenantId, headSignatureFileId, signatureFileKind]) + @@unique([tenantId, sealFileId, sealFileKind]) + @@map("institute_profiles") +} diff --git a/packages/db/src/cli/platform-admin.ts b/packages/db/src/cli/platform-admin.ts index da311ac7..8832fe47 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 00000000..4b27e4c3 --- /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 08e0d3cc..67e26d9b 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 1be77b09..4106537a 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 @@ -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/src/platform/context.ts b/packages/db/src/platform/context.ts index c3d59914..8a282310 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 b7b921b9..3bd24ea6 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 dddd407e..3463571f 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 3b442e49..d517bcf8 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 9cbe1366..fdd334ec 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 6023dbb9..146e76a9 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/auth-functions.test.ts b/packages/db/test/auth-functions.test.ts index a12c9689..c529ee6e 100644 --- a/packages/db/test/auth-functions.test.ts +++ b/packages/db/test/auth-functions.test.ts @@ -8,6 +8,7 @@ const FUNCTIONS = [ 'auth_resolve_tenant', 'auth_find_refresh_token', 'app_find_or_create_user', + 'auth_my_password_is_set', ]; describe('auth SECURITY DEFINER functions', () => { diff --git a/packages/db/test/env.ts b/packages/db/test/env.ts index fd19b390..377d7ac7 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/files-rls.test.ts b/packages/db/test/files-rls.test.ts new file mode 100644 index 00000000..841ba27c --- /dev/null +++ b/packages/db/test/files-rls.test.ts @@ -0,0 +1,365 @@ +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, 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, + 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(RLS); + 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], 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(rule); + }); + + 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(RLS); + await expect( + withTenant(app, a, (tx) => tx.$executeRaw`DELETE FROM stored_file_usage`), + ).rejects.toThrow(/permission denied/); + 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'); + } + }); + }); + + 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(RLS); + }); + + it('one per institute, never deleted', async () => { + await expect( + withTenant(app, a, (tx) => + tx.instituteProfile.create({ data: { tenantId: a, nameEn: 'Again' } }), + ), + ).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 }, '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(rule); + }); + + 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 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('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'); + await expect( + withTenant(app, a, (tx) => + tx.instituteProfile.updateMany({ data: { headSignatureFileId: aPhoto } }), + ), + ).rejects.toThrow('institute_profiles_tenant_id_head_signature_file_id_head_s_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 } }), + ); + await expect( + withTenant(app, a, (tx) => + tx.storedFile.delete({ where: { id: aLogo }, select: { id: true } }), + ), + ).rejects.toThrow('institute_profiles_tenant_id_logo_file_id_logo_file_kind_fkey'); + }); + }); + + it('a first image and a first save at once: the insert waits for the held one, then skips it', async () => { + // InstituteProfileService.ensureRow inserts with ON CONFLICT DO NOTHING (createMany + // skipDuplicates) while PUT /institute/profile upserts. Hold an uncommitted insert, run the + // second, commit the first: no error, nothing inserted twice, the first row stays. + const t = (await createTenant(app)).id; + const other = appClient(); + let release!: () => void; + const held = new Promise((r) => (release = r)); + let inserted!: () => void; + const insertedOnce = new Promise((r) => (inserted = r)); + const first = withTenant(app, t, async (tx) => { + await tx.instituteProfile.create({ data: { tenantId: t, nameEn: 'First save' } }); + inserted(); + await held; + }); + await insertedOnce; + const second = withTenant(other, t, (tx) => + tx.instituteProfile.createMany({ + data: [{ tenantId: t, nameEn: 'From the image' }], + skipDuplicates: true, + }), + ); + await new Promise((r) => setTimeout(r, 300)); // the second is now waiting on the first + release(); + await first; + expect((await second).count).toBe(0); + const rows = await withTenant(app, t, (tx) => + tx.instituteProfile.findMany({ select: { nameEn: true } }), + ); + expect(rows).toEqual([{ nameEn: 'First save' }]); + await other.$disconnect(); + }); + + describe('students.photo_file_id', () => { + 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 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.storedFile.delete({ where: { id: photo }, select: { id: true } }), + ), + ).rejects.toThrow(FK); + await expect( + withTenant(app, a, (tx) => + tx.student.update({ + where: { id: student.id }, + data: { photoFileKind: 'LOGO' }, + select: { id: true }, + }), + ), + ).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', 'photo_file_kind']); + }); + }); +}); diff --git a/packages/db/test/helpers.ts b/packages/db/test/helpers.ts index d5311ca6..a453b2a3 100644 --- a/packages/db/test/helpers.ts +++ b/packages/db/test/helpers.ts @@ -1,24 +1,28 @@ 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'; -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'; +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); +/** 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); @@ -52,7 +56,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/login-privileges.test.ts b/packages/db/test/login-privileges.test.ts index 5080c075..b12b65b7 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'] }), diff --git a/packages/db/test/schema-safety.test.ts b/packages/db/test/schema-safety.test.ts index cca53886..0e7721b0 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', () => { @@ -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); @@ -125,11 +128,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', ]; @@ -182,11 +200,158 @@ 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', 'search_student_ids', ]); expect(scoped.filter((r) => !r.scoped)).toEqual([]); }); + // 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; 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 + ORDER BY a.attname`; + 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 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([]); + }); + + // 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. + 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(r.login, p.oid, 'EXECUTE') + AND has_column_privilege(p.proowner, 'users'::regclass, 'password_hash', 'SELECT') + ORDER BY 1`; + 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'], + }, + ]); + }); + + // 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 // the second factor). Everything else needs a live session of an active admin. const PRE_SESSION_PLATFORM = [ diff --git a/packages/db/test/test-phones.test.ts b/packages/db/test/test-phones.test.ts new file mode 100644 index 00000000..50d5a460 --- /dev/null +++ b/packages/db/test/test-phones.test.ts @@ -0,0 +1,186 @@ +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, 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-')); + }); + 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 + 3_600_000 }); + for (let i = 0; i < 300; i++) expect(earlier.has(later())).toBe(false); + }); + + 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', () => { + 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', () => { + fs.mkdirSync(`${counterFile()}.lock`); + const old = new Date(Date.now() - 60_000); + fs.utimesSync(`${counterFile()}.lock`, old, old); + const next = phoneSource('+88013', db, { dir, now: () => t0 }); + expect(next()).toMatch(BD_PHONE_E164); + 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 new file mode 100644 index 00000000..d200eed1 --- /dev/null +++ b/packages/db/test/test-phones.ts @@ -0,0 +1,149 @@ +import { randomUUID } from 'node:crypto'; +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). 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). + */ + +/** 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 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 = 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)); + +const pause = (ms: number): void => { + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); +}; + +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 { + f.mkdirSync(lockDir); + f.writeFileSync(path.join(lockDir, 'owner'), token); + break; + } catch (error) { + 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); + } + } + try { + return fn(); + } finally { + if (ownerOf(f, lockDir) === token) f.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++; + 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/users-password-hash.test.ts b/packages/db/test/users-password-hash.test.ts new file mode 100644 index 00000000..717ae390 --- /dev/null +++ b/packages/db/test/users-password-hash.test.ts @@ -0,0 +1,262 @@ +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'; +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. 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 }; + 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(); + login = loginClient(); + 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 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 () => { + 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 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']); + expect(rows[0]!['id']).toBe(staff.id); + }); + + 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); + }); + + 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('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, + ); + 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 () => { + 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); + }); + + 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); + }); +}); + +// ─────────── 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); + }); +}); diff --git a/packages/db/test/users-rls.test.ts b/packages/db/test/users-rls.test.ts index 76d8afda..72bacdcf 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([ diff --git a/packages/shared/src/api.ts b/packages/shared/src/api.ts index 5a0d27d1..4d96fc88 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 068f5e3e..1d54f877 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 new file mode 100644 index 00000000..a7068df4 --- /dev/null +++ b/packages/shared/src/files-schema.ts @@ -0,0 +1,71 @@ +import { z } from 'zod'; +import { toAsciiDigits } from './digits.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. + +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); + +export const instituteProfileSchema = z + .object({ + nameBn: text(L.name), + nameEn: text(L.name), + shortName: text(L.shortName), + 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 || 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 && P.website.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 00000000..95dd0dec --- /dev/null +++ b/packages/shared/src/files.test.ts @@ -0,0 +1,92 @@ +import { describe, expect, it } from 'vitest'; +import { + FILE_LIMITS, + INSTITUTE_PROFILE_PATTERNS, + normalizeInstitutePhone, + normalizeWebsite, + 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', () => { + 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'); + }); + + 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 new file mode 100644 index 00000000..b8ea489b --- /dev/null +++ b/packages/shared/src/files.ts @@ -0,0 +1,152 @@ +// 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', + '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; + +/** 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+$/, +} 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) in lower + * case (`HTTP://` → `http://`), as the database CHECK compares it case-sensitively. + */ +export function normalizeWebsite(input: string): string { + const v = input.trim(); + const scheme = /^[a-z][a-z0-9+.-]*:/i.exec(v); + return scheme ? scheme[0].toLowerCase() + v.slice(scheme[0].length) : `https://${v}`; +} diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 9a4559f3..0a004c98 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'; diff --git a/packages/shared/src/password.test.ts b/packages/shared/src/password.test.ts index 8920a1f4..a5f33d79 100644 --- a/packages/shared/src/password.test.ts +++ b/packages/shared/src/password.test.ts @@ -87,6 +87,121 @@ 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.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('উচ্চবিদ্যালয়', 'উচ্চ বিদ্যালয়'); + }); + }); + 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 24a60ea6..d7d6e478 100644 --- a/packages/shared/src/password.ts +++ b/packages/shared/src/password.ts @@ -23,9 +23,107 @@ export function normalizePassword(pw: string): string { return pw.normalize('NFC'); } -/** NFC, lower-case, without whitespace: how passwords and institute names are compared. */ +/** 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; + +/** + * 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, ''); + return folded(text).replace(NOT_COMPARED, ''); +} + +/** + * 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 + 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 + বিদ্যালয় মহাবিদ্যালয় উচ্চ মাধ্যমিক নিম্ন প্রাথমিক জুনিয়র সিনিয়র স্কুল হাই কলেজ মাদ্রাসা + মাদরাসা একাডেমি একাডেমী বিশ্ববিদ্যালয় সরকারি সরকারী বেসরকারি বেসরকারী মডেল আদর্শ আইডিয়াল + পাবলিক ক্যাডেট আবাসিক রেসিডেন্সিয়াল বালিকা বালক মহিলা গার্লস বয়েজ ইংলিশ বাংলা মিডিয়াম ভার্সন + ইন্টারন্যাশনাল আন্তর্জাতিক কোচিং সেন্টার কেন্দ্র ইনস্টিটিউট ইন্সটিটিউট ইনস্টিটিউশন প্রতিষ্ঠান + কিন্ডারগার্টেন কিন্ডার টেকনিক্যাল কারিগরি ভোকেশনাল পলিটেকনিক প্রশিক্ষণ আলিয়া দাখিল আলিম ফাজিল + কামিল হাফিজিয়া হাফেজিয়া হিফজ হিফজুল তাহফিজুল কুরআন কোরআন নূরানী নুরানী কওমী কওমি ইসলামিয়া + ইসলামী ইসলামি দারুল উলুম জামিয়া পাঠশালা বিদ্যানিকেতন বিদ্যাপীঠ বিদ্যামন্দির নিকেতন শিক্ষা + শিক্ষালয় অ্যান্ড এন্ড এবং + পাইলট মেমোরিয়াল স্মৃতি শিশু ইবতেদায়ী ইবতেদায়ি নার্সারি নার্সারী শহীদ শহিদ +` + .split(/\s+/u) + .filter((w) => w !== ''); + +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. + * 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, 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(); + 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]; } /** The 10-digit national number (`17XXXXXXXX`) of a Bangladeshi phone, or null if there is none. */ @@ -54,10 +152,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; diff --git a/packages/shared/src/students.ts b/packages/shared/src/students.ts index 0d0cc80f..4ee0ca85 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; diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b6e984a4..6459aded 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: