diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..11d5ad3 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,17 @@ +node_modules +dist +.git +.env +.env.* +.data +data +.test-data +.claude +.codex +.agents +coverage +*.db +*.db-wal +*.db-shm +*.key +npm-debug.log* diff --git a/.gitignore b/.gitignore index 7a7fd29..8cfadb5 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ coverage/ npm-debug.log* .test-data/ .claude/ +data-v2/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..4fda957 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,20 @@ +# syntax=docker/dockerfile:1 +FROM node:24-bookworm-slim AS build +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci +COPY . . +RUN npm run build && npm prune --omit=dev + +FROM node:24-bookworm-slim AS runtime +ENV NODE_ENV=production HOST=0.0.0.0 PORT=3726 DATA_DIR=/data WEB_DIR=/app/dist/web +WORKDIR /app +COPY --from=build --chown=node:node /app/package.json ./ +COPY --from=build --chown=node:node /app/node_modules ./node_modules +COPY --from=build --chown=node:node /app/dist ./dist +RUN mkdir -p /data && chown node:node /data +USER node +VOLUME ["/data"] +EXPOSE 3726 +HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))" +CMD ["node", "dist/server/main.js"] diff --git a/PROGRESS.md b/PROGRESS.md new file mode 100644 index 0000000..28623ac --- /dev/null +++ b/PROGRESS.md @@ -0,0 +1,90 @@ +# Study Desk V2 — progress and resume notes + +Updated 2026-11-11. Branch: **v2**. Original V1: **main**, preserved at `7bd0a9a`. +Work remains local; no push, repository creation or production deployment has been performed. + +## Product and architecture + +This is a rebuilt app using React + Vite + TypeScript, Hono/Node HTTP server, built-in +`node:sqlite`, SQLite FTS5, local document storage and a persistent document queue. One process, +one data volume, one administrator. Anonymous visitors get public read-only shares and +browser-local study progress. Administrator progress stays server-side. + +The previous agent implemented the core product and committed it through `c549c34`: +classes/folders, CRUD/duplicate/move/search, quiz sessions/results/history, FSRS flashcards, +imports/exports/templates, documents/extraction/retrieval/OCR, provider adapters, editable +AI drafts, tool-based assistant actions, sharing, analytics and the responsive themed UI. +User feedback fixes are already included: larger clickable flashcards, arrow keys, streak +effects, persistent review sidebar, live quiz score, shared quiz timers, SATA credit details, +type-grouped materials, copyable import instructions and assistant library links. + +## Current continuation + +- Confirmed original 162 tests pass; sandbox networking initially blocked the mock provider. +- Added encryption-key corruption/missing-key refusal, static-path boundary validation, + private embedded-media authorization and share-revocation checks. +- Full backups include the generated encryption key and fail on unreadable files. +- Added backup restore, media authorization, key durability, V1 import and failed-migration + rollback tests. The new V1 test checks source bytes are unchanged and state is preserved. +- Added Dockerfile, Compose, .dockerignore, README and deployment/migration/AI documentation. +- Updated obsolete ChatGPT subscription wording after checking official documentation: + account integration exists for eligible clients, but hosted app approval for this private + Unraid web deployment has not been established. API integration remains the working path. +- Terra completed isolated UI/workflow and visual QA; see results below. +- Guarded quiz exit/submission when the latest save failed, and prevented repeated automatic + timer submissions after a failed request. + +## Verification status + +Baseline: 162 tests passed, TypeScript passed and production web/server builds passed. +Added five regression tests. Full `npm run check` passes: **167 tests**, TypeScript and both +production builds. Tests were run with loopback access for the mock provider. + +The earlier agent manually exercised quiz completion/results, flashcards, streak effects, +mock AI generation through the assistant, editable drafts, and a 375px home page without +horizontal overflow. Treat these as historical evidence; record Terra's fresh results below. + +Not verified: actual Docker image build/runtime, Unraid filesystem permissions and proxy, +paid provider inference, real ChatGPT OAuth/eligibility. Docker is not installed here. Do not +claim these have been tested. The installable app caches its shell, not private study data; +full offline administrator study is not implemented. + +## Remaining work + +1. Finish the brief post-fix Terra contrast recheck and public visitor UI check. +2. Record its results, review the diff and commit locally. +3. On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md. +4. With owner-supplied provider connections: verify live discovery, streamed chat, generation, + OCR and task routing. No real-provider calls should be inferred from mock test results. +5. Future optional work: approved ChatGPT account OAuth, more robust offline studying and + semantic embeddings (current retrieval is lexical FTS5). + +## Resume safely + +1. `git status --short`, read this file and recent commits. Do not overwrite user changes. +2. The ignored `.env` currently selects `.data/`, containing dev/demo content that the user + has tried. Never print its secrets or reset/seed it casually. Use a new `.test-data/...` + directory and a separate port for destructive QA. +3. `npm.cmd run check` (tests require localhost networking for their mock AI server). +4. `npm.cmd run dev` for Vite + API, or `npm.cmd run build` then `npm.cmd start` for the built + app. See README and .env.example. All automated test databases are disposable copies. +5. Keep regular local commits on `v2`. Do not push until the owner explicitly changes the + original local-only instruction. Publishing later can use `git push -u origin v2` after + reviewing the diff and confirming credentials; no force push is needed. + +## Fresh UI QA findings + +Terra tested through Edge in an isolated volume on port 3731. Observed successful login, +class creation, quiz/question editing, practice start, save/exit, resume, answer check and +100% results; deck/card creation, browse flip, FSRS review, pasted question import; desktop +and emulated 400×933 mobile layouts in both themes. No obvious clipping or overlap observed +on those screens. The test server was stopped and the temporary password removed. + +Visual finding: secondary labels appeared faint, particularly in dark mode. Adjusted the +shared `ink-3` colors. Computed WCAG contrast against paper/surface/sunken backgrounds: +light now **5.15 / 5.38 / 4.76** (previously 3.48 / 3.63 / 3.21); dark now +**7.42 / 6.86 / 7.71**. These ratios cover these token pairs, not a full accessibility audit. + +Screenshots remain ignored under `.test-data/ui-terra/`: desktop-dark-quiz.png, +desktop-light-quiz.png, mobile-dark-quiz.png, mobile-light-quiz.png and mobile-light-session.png. +Post-fix visual and anonymous-share recheck pending. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0f7c70e --- /dev/null +++ b/README.md @@ -0,0 +1,81 @@ +# Study Desk V2 + +A personal study platform for nursing school: classes and folders, quizzes, FSRS flashcards, +notes, private documents, and AI-assisted content creation. One administrator; friends study +through revocable public links without accounts. + +## Run locally + +Requires Node.js 24 or newer and npm. The development VM currently uses Node 26. + +```powershell +npm.cmd ci +npm.cmd run dev +``` + +Open the Vite address printed in the terminal (normally http://localhost:5173). +The API listens on port 3726. For the production build locally: + +```powershell +npm.cmd run build +npm.cmd start +``` + +Open http://localhost:3726. On a fresh install, enter the setup code from the server log or +`data/setup-code.txt`, then choose your administrator password. Alternatively set +`ADMIN_PASSWORD` for first startup. An optional `.env` file is loaded by the server; see +[.env.example](.env.example). Existing environment variables take precedence. + +**This checkout already has an ignored `.env` pointing at `.data/` from development.** +Do not delete it or run reset/seed commands against content you want to keep. The demo seeder +is an opt-in development tool, never part of startup. + +## What is implemented + +- Classes, folders, search, edit/duplicate/move/delete actions; Markdown and embedded images. +- Multiple-choice and select-all quizzes; practice feedback, exam timers, shuffle, partial + credit, saved sessions, missed-question review, results and history. +- Flashcard editing, browse/self-assessment sessions, FSRS scheduling, persistent reviews, + undo, keyboard shortcuts and streak effects. +- Public quiz/deck/class/folder/note links and explicitly shared documents. Collection shares + include current and future quizzes, decks and notes; uploaded documents stay private. +- JSON import previews, validation, templates, content exports and a V1 SQLite import path. +- PDF/DOCX/PPTX/TXT/Markdown/image uploads; text extraction, OCR via a configured vision model, + chunking and SQLite FTS retrieval with source references. +- OpenAI, Anthropic, Gemini, OpenAI-compatible and Ollama provider connections, manual/discovered + models, task routing, encrypted keys and usage estimates. +- AI generation with editable drafts; an assistant that searches materials, reads notes, + creates drafts, finds weak topics and proposes confirmed content changes. +- Responsive light/dark interface and an installable app shell. Offline studying is limited: + private data is not cached; most operations need a server connection. + +## Deploy, back up, migrate + +See [deployment and restore](docs/DEPLOYMENT.md), [V1 migration](docs/MIGRATION.md), and +[AI providers and account integration](docs/AI.md). + +The image runs a single Node process with SQLite and local file storage. No database or queue +container is required. The container runs as UID/GID 1000 and persists everything under `/data`. + +```sh +docker compose up -d --build +``` + +Default V2 host port: **3727**, deliberately separate from the old application. Use a separate +data folder. Docker is not installed in this VM; image build/runtime checks remain to be run +on Unraid. No production deployment has been performed. + +## Verification and resuming work + +```powershell +npm.cmd run check +``` + +Tests create isolated temporary databases. AI integration tests use a local mock server and +need loopback networking. They do not spend provider credits. Real provider credentials, +account-specific model access, Linux container behavior and Unraid proxy configuration must +be checked in their target environments. + +[PROGRESS.md](PROGRESS.md) records completed work, remaining verification, decisions and the +resume procedure. V1 remains on `main` and in Git history; all V2 work is on local `v2`. +Nothing is automatically pushed or published. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..587315e --- /dev/null +++ b/compose.yaml @@ -0,0 +1,20 @@ +services: + study-v2: + build: . + image: study-desk:v2-local + container_name: study-v2 + restart: unless-stopped + init: true + ports: + - "${STUDY_PORT:-3727}:3726" + volumes: + - "${STUDY_DATA_DIR:-./data-v2}:/data" + environment: + TZ: ${TZ:-America/Phoenix} + TRUST_PROXY: ${TRUST_PROXY:-false} + COOKIE_SECURE: ${COOKIE_SECURE:-auto} + MAX_UPLOAD_MB: ${MAX_UPLOAD_MB:-100} + BACKUP_KEEP: ${BACKUP_KEEP:-7} + stop_grace_period: 15s + security_opt: + - no-new-privileges:true diff --git a/docs/AI.md b/docs/AI.md new file mode 100644 index 0000000..acf8acb --- /dev/null +++ b/docs/AI.md @@ -0,0 +1,44 @@ +# AI connections and verification + +Settings → AI manages provider connections and model routing. Add a connection, test it, +discover models where supported (or add a custom model), enable models and select defaults +for generation, chat, explanations and vision. Output limits, capabilities, pricing and +reasoning settings can be edited per model. Catalog prices are estimates, not billing records. + +Adapters use OpenAI Responses, Anthropic Messages, Gemini generateContent, OpenAI-compatible +Chat Completions and Ollama's native chat API. Configure the endpoint as shown in Settings. +Local models are reached **from the server/container**: `localhost` inside Docker is the +container itself, not your workstation or Unraid host. Use a reachable LAN address instead. + +Keys are encrypted with AES-256-GCM in SQLite using `/data/secret.key` or `APP_SECRET`. +Only the server decrypts them. Keep the key with backups; changing it breaks decryption. +Documents are sent to the selected provider when you request AI processing; extraction and +full-text indexing otherwise run locally. OCR requires a compatible vision/PDF model. +Retrieval uses chunked SQLite FTS search; it is lexical retrieval, not embedding similarity. +Review generated nursing content and source references before using it for study. + +## ChatGPT account investigation (2026-11-11) + +The official [Sign in with ChatGPT quickstart](https://developers.openai.com/siwc/quickstart) +now describes plan access for eligible integrations. The +[official implementation guide](https://developers.openai.com/cookbook/articles/sign-in-with-chatgpt) +distinguishes local personal/open-source tools from remotely hosted apps, which require +access approval. This Unraid/reverse-proxy deployment is a hosted web application; eligibility +for its private client has not been established. Therefore V2 currently uses conventional API +connections, and does not advertise ChatGPT plan access or reuse another client's credentials. + +To add this later, obtain the appropriate approval/registration and implement the documented +OAuth/PKCE flow, verified identity, encrypted refresh tokens, approved callbacks and plan-scoped +model discovery. Keep this separate from the single administrator's local login. Never copy +ChatGPT browser session tokens or a Codex client's registration/credentials into Study Desk. + +## What has been tested + +Mock protocol tests cover request translation, streams, tools, usage and error handling. +Integration tests use a local OpenAI-compatible mock to generate/edit/save drafts, search +documents with citations and exercise confirmed assistant actions. They cost no API credits. +No successful real-provider inference or real ChatGPT OAuth authorization is claimed. + +For manual local AI testing: `npx tsx scripts/mock-ai.ts` starts a scripted mock at +`http://localhost:4010/v1` with key `mock-key`. It returns clearly labeled synthetic material. +Do not use mock output as nursing guidance. Stop the mock and remove its connection after QA. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..cdf3648 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,96 @@ +# Single-container deployment and recovery + +## Unraid + +Build from this checkout with `docker build -t study-desk:v2-local .`. +Create a **new** container named `study-v2`, image `study-desk:v2-local`: + +| Setting | Value | +| --- | --- | +| Network | bridge | +| Container port | 3726 TCP | +| Host port | 3727 (or another unused port) | +| Container path | /data | +| Host path | /mnt/user/appdata/study-v2 | +| TZ | America/Phoenix | +| TRUST_PROXY | true only behind a trusted proxy | +| COOKIE_SECURE | true with HTTPS; auto for local HTTP testing | + +The image uses UID/GID **1000:1000**. Create a dedicated host directory writable by that user +before starting. For example, on Unraid: `mkdir -p /mnt/user/appdata/study-v2` then +`chown 1000:1000 /mnt/user/appdata/study-v2`. Only change permissions on this new folder. +Alternatively select an appropriate non-root UID/GID using Docker's `--user` option and grant +that identity access to the dedicated directory. Never mount V1's database or data folder. + +The supplied `compose.yaml` defaults to `./data-v2` and host port 3727. Override +`STUDY_DATA_DIR` for Unraid. Do not reuse a V1 container name, mount or proxy destination. + +Startup applies committed schema migrations transactionally, taking a database snapshot first +when an existing V2 schema needs upgrading. A database from a newer app version is refused. +The first visit asks for the setup code from the container log or `/data/setup-code.txt`. +After setup, the password is stored as a salted scrypt hash. No registration exists. + +## Reverse proxy + +Point your proxy to the container's port 3726 (or the host's mapped port). Forward `Host`, +`X-Forwarded-Proto`, and a trustworthy `X-Forwarded-For`. With `TRUST_PROXY=true`, restrict +direct access to the application to your proxy/network: forwarded headers are trusted. +Use `COOKIE_SECURE=true` for the HTTPS public hostname. Plain HTTP cannot carry Secure cookies. +Keep proxy upload limits at least as large as `MAX_UPLOAD_MB`, and allow long AI responses. +Disable buffering for `/api/ai/chat` and `/api/ai/explain`; allow a long read timeout there. +Do not cache `/api/`, `/media/` or shared study data. `/api/health` returns 200 when SQLite works. + +## Configuration + +`.env.example` documents all server variables. Environment values override a local `.env`. +The image excludes local configuration, source databases and test content from its build context. +Do not bake passwords or keys into an image. + +- `ADMIN_PASSWORD`: optional first-install password, ignored after setup. +- `RESET_ADMIN_PASSWORD`: changes the password and revokes sessions at startup. Remove it + after one successful reset or it will repeat on every restart. +- `APP_SECRET`: optional external encryption secret (16+ characters). Keep it stable. + Otherwise `/data/secret.key` is generated once. A damaged key is refused, never replaced. +- `MAX_UPLOAD_MB`: default 100; OCR/native vision input has additional provider limits. +- `BACKUP_KEEP`: default 7 daily automatic database snapshots. + +## Backups + +Settings → Data has portable content JSON and a full ZIP download. JSON includes quizzes, +decks, classes, folders and notes, **not** progress, uploads, credentials or all settings. +The full ZIP contains a consistent SQLite snapshot, uploads, media, a restore manifest and +the generated `secret.key` when present. It contains private content and credential material; +store it securely. An externally configured `APP_SECRET` must be saved separately. + +Daily snapshots under `/data/backups` cover **the database only**. They are not a substitute +for a full off-machine backup of the data volume and encryption key. A backup stream that +cannot read an included file fails rather than silently substituting an empty file. +Avoid changing or deleting source files while making a full ZIP; filesystem content is not +transactional with SQLite. + +## Restore drill + +1. Download a full ZIP and verify it opens. Stop the V2 container before restoring. +2. Keep the old data folder intact. Extract the ZIP into a **new**, empty folder. +3. Check that `study.db`, `uploads/`, `media/` and the matching key are present as applicable. + If using `APP_SECRET`, set the original value. Do not copy stale `study.db-wal` or + `study.db-shm` files from another database into the restored folder. +4. Give the container user access. Start the same image version with the new folder mounted + at `/data`, initially on a separate port without public routing. +5. Verify login, class/quiz/deck counts, representative uploads, review progress, AI connection + decryption and shared links. Use SQLite `PRAGMA integrity_check` and `foreign_key_check` + if manually inspecting a copy. Do not run migration/reset experiments on your only backup. +6. Switch proxy routing only after these checks succeed. Retain the previous folder and image. + +For an upgrade, make and verify a full backup first, then rebuild/recreate the container with +the same V2 volume. Never edit an already applied migration. Roll back by restoring the +pre-upgrade data into a separate directory with the prior image; do not force an older image +to open a newer schema. + +## Verification still required on Unraid + +Docker is unavailable in the development VM. Before production use: build the image, confirm +health status and non-root volume permissions, complete setup over HTTPS, upload a PDF and +PPTX, restart and check persistence, test public links from a private browser, confirm proxy +streaming and upload limits, and perform the restore drill above. The Dockerfile and Compose +configuration are implemented, but container deployment has **not** been executed here. diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..175ed06 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,22 @@ +# Importing V1 safely + +V1 code remains on `main` at `7bd0a9a` and in history. V2 has a separate schema and must use +a separate data folder. It never upgrades a production V1 database in place. + +1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself, + stop V1 first; copying only a live WAL-mode `.db` can omit recent writes. +2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume. +3. In V2 Settings → Data → V1 import, select the **backup copy** and preview it. +4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted + SQLite file read-only and creates new IDs in one transaction. A failed import rolls back. +5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and + scheduling. V1's passwords, provider settings and share URLs are not reused. Recreate links + deliberately. Running the import again creates another set of content. + +The importer supports V1 classes, material groups, decks/cards, quiz sets/questions/options, +completed attempts, spaced-repetition card state and activity where present. It reports +unsupported/skipped records. Older optional game features are not migrated as games. +V1 JSON quiz/flashcard exports can also be pasted/uploaded in a class's Import dialog. + +Portable V2 JSON exports are useful for migration between apps; full ZIP backups are needed +to preserve progress, documents, settings and credentials. See DEPLOYMENT.md for recovery. diff --git a/server/app.ts b/server/app.ts index 8e1c784..57eeba9 100644 --- a/server/app.ts +++ b/server/app.ts @@ -137,9 +137,17 @@ export function createApp(app: AppContext): Hono { if (!webDir) { return c.text('The web app has not been built. Run "npm run build", or use "npm run dev" and open the Vite dev server.', 404); } - const urlPath = decodeURIComponent(new URL(c.req.url).pathname); + let urlPath: string; + try { + urlPath = decodeURIComponent(new URL(c.req.url).pathname); + } catch { + return c.text('Invalid URL', 400); + } const candidate = path.normalize(path.join(webDir, urlPath)); - if (candidate.startsWith(webDir) && urlPath !== '/' && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) { + const relative = path.relative(webDir, candidate); + const inside = relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); + if (!inside) return c.text('Not found', 404); + if (urlPath !== '/' && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) { // Hashed build assets never change; everything else is revalidated. const immutable = urlPath.startsWith('/assets/'); return sendFile(candidate, immutable ? 'public, max-age=31536000, immutable' : 'no-cache'); diff --git a/server/config.ts b/server/config.ts index 078df62..1707029 100644 --- a/server/config.ts +++ b/server/config.ts @@ -31,16 +31,21 @@ function bool(v: string | undefined, fallback: boolean): boolean { } function loadSecret(dataDir: string, fromEnv: string | undefined): Buffer { - if (fromEnv && fromEnv.trim().length >= 16) { + if (fromEnv && fromEnv.trim().length < 16) throw new Error('APP_SECRET must contain at least 16 characters.'); + if (fromEnv) { return crypto.createHash('sha256').update(`studydesk:${fromEnv.trim()}`).digest(); } const file = path.join(dataDir, 'secret.key'); if (fs.existsSync(file)) { const raw = Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'base64'); if (raw.length === 32) return raw; + throw new Error('secret.key is damaged. Restore the original key from your backup; refusing to replace it.'); + } + if (fs.existsSync(path.join(dataDir, 'study.db'))) { + throw new Error('Existing database has no secret.key. Restore its original key or set the original APP_SECRET; refusing to generate a replacement.'); } const key = crypto.randomBytes(32); - fs.writeFileSync(file, key.toString('base64'), { mode: 0o600 }); + fs.writeFileSync(file, key.toString('base64'), { mode: 0o600, flag: 'wx' }); return key; } diff --git a/server/routes/documents.ts b/server/routes/documents.ts index c4492c2..ff4ef90 100644 --- a/server/routes/documents.ts +++ b/server/routes/documents.ts @@ -5,6 +5,7 @@ import { Hono } from 'hono'; import { bodyLimit } from 'hono/body-limit'; import { z } from 'zod'; import { titleSchema } from '../../shared/content.ts'; +import { isAuthenticated } from '../auth.ts'; import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts'; import { getClass, mapClass, resolveFolder } from '../services/content.ts'; import { deleteDocument, documentPath, enqueue, getDocument, ingestUpload, listChunks, mapDocument, sourceLabel } from '../services/documents.ts'; @@ -162,19 +163,35 @@ export function documentRoutes(app: AppContext): Hono { } /** - * Public image route. Images are addressed by an unguessable 128-bit name, which is what lets - * a shared quiz show its pictures to visitors without exposing anything else. + * Images are private unless an enabled share contains a reference to them. + * Re-check on each request so revoking a share also revokes its embedded images. */ export function mediaRoute(app: AppContext): Hono { const r = new Hono(); r.get('/:name', (c) => { const name = c.req.param('name'); if (!/^[A-Za-z0-9_-]{16,40}\.(png|jpg|gif|webp)$/.test(name)) throw new HttpError(404, 'not_found', 'Not found'); + if (!isAuthenticated(app, c)) { + const reference = `/media/${name}`; + const shared = app.db.get(` + SELECT 1 FROM shares s WHERE s.enabled = 1 AND ( + EXISTS (SELECT 1 FROM questions q JOIN quizzes z ON z.id = q.quiz_id + WHERE ((s.kind = 'quiz' AND s.target_id = z.id) OR (s.kind = 'class' AND s.target_id = z.class_id) OR (s.kind = 'folder' AND s.target_id = z.folder_id)) + AND instr(q.stem || q.options || q.rationale, ?) > 0) + OR EXISTS (SELECT 1 FROM cards c JOIN decks d ON d.id = c.deck_id + WHERE ((s.kind = 'deck' AND s.target_id = d.id) OR (s.kind = 'class' AND s.target_id = d.class_id) OR (s.kind = 'folder' AND s.target_id = d.folder_id)) + AND instr(c.front || c.back || c.hint, ?) > 0) + OR EXISTS (SELECT 1 FROM notes n + WHERE ((s.kind = 'note' AND s.target_id = n.id) OR (s.kind = 'class' AND s.target_id = n.class_id) OR (s.kind = 'folder' AND s.target_id = n.folder_id)) + AND instr(n.content, ?) > 0) + ) LIMIT 1`, reference, reference, reference); + if (!shared) throw new HttpError(404, 'not_found', 'Not found'); + } const row = app.db.get<{ mime: string }>('SELECT mime FROM media WHERE id = ?', name); const file = path.join(app.config.mediaDir, name); if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found'); return new Response(fs.readFileSync(file), { - headers: { 'Content-Type': row.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox" }, + headers: { 'Content-Type': row.mime, 'Cache-Control': 'private, no-store', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox" }, }); }); return r; diff --git a/server/services/backup.ts b/server/services/backup.ts index e204f06..09b4552 100644 --- a/server/services/backup.ts +++ b/server/services/backup.ts @@ -89,6 +89,10 @@ export function fullBackupStream(app: AppContext): { stream: ReadableStream | null = null; @@ -139,11 +143,14 @@ export function fullBackupStream(app: AppContext): { stream: ReadableStream { + app?.close(); + app = undefined; + for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true }); +}); +const temporary = () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'studydesk-hardening-test-')); + dirs.push(dir); + return dir; +}; + +describe('private image authorization', () => { + it('only exposes an embedded image while its content has an enabled share', async () => { + app = await createTestApp(); + const form = new FormData(); + form.set('file', new File([Buffer.from(TINY_PNG)], 'private.png', { type: 'image/png' })); + const uploaded = await app.raw('POST', '/api/media', { body: form }); + expect(uploaded.status).toBe(201); + const { url } = await uploaded.json() as { url: string }; + expect((await app.raw('GET', url)).status).toBe(200); + expect((await app.raw('GET', url, { cookie: null })).status).toBe(404); + const cls = (await app.api('POST', '/api/classes', { name: 'Images' })).body.class; + const deck = (await app.api('POST', '/api/decks', { classId: cls.id, title: 'Picture deck', cards: [{ front: `![picture](${url})`, back: 'Answer' }] })).body.deck; + const share = (await app.api('POST', '/api/shares', { kind: 'deck', targetId: deck.id })).body.share; + const publicImage = await app.raw('GET', url, { cookie: null }); + expect(publicImage.status).toBe(200); + expect(publicImage.headers.get('cache-control')).toContain('no-store'); + await app.api('DELETE', `/api/shares/${share.id}`); + expect((await app.raw('GET', url, { cookie: null })).status).toBe(404); + const collection = (await app.api('POST', '/api/shares', { kind: 'class', targetId: cls.id })).body.share; + expect((await app.raw('GET', url, { cookie: null })).status).toBe(200); + await app.api('PATCH', `/api/shares/${collection.id}`, { enabled: false }); + expect((await app.raw('GET', url, { cookie: null })).status).toBe(404); + }); +}); + +describe('key durability and restore', () => { + it('refuses a damaged encryption key without replacing it', () => { + const dir = temporary(); + const config = loadConfig({ dataDir: dir }, {}); + expect(loadConfig({ dataDir: dir }, {}).secretKey).toEqual(config.secretKey); + fs.writeFileSync(path.join(dir, 'secret.key'), 'damaged'); + expect(() => loadConfig({ dataDir: dir }, {})).toThrow(/damaged/); + expect(fs.readFileSync(path.join(dir, 'secret.key'), 'utf8')).toBe('damaged'); + expect(() => loadConfig({ dataDir: dir }, { APP_SECRET: 'short' })).toThrow(/16 characters/); + fs.unlinkSync(path.join(dir, 'secret.key')); + fs.writeFileSync(path.join(dir, 'study.db'), 'fixture'); + expect(() => loadConfig({ dataDir: dir }, {})).toThrow(/no secret.key/); + }); + + it('restores a full backup into a new folder with data and the original encryption key', async () => { + app = await createTestApp(); + await app.api('POST', '/api/classes', { name: 'Restored class' }); + const encrypted = encryptSecret('test-only-provider-secret', app.ctx.config.secretKey); + fs.writeFileSync(path.join(app.ctx.config.uploadsDir, 'fixture.txt'), 'Preserved document'); + const res = await app.raw('GET', '/api/backup/download'); + const files = unzipSync(new Uint8Array(await res.arrayBuffer())); + expect(Object.keys(files)).toEqual(expect.arrayContaining(['study.db', 'secret.key', 'uploads/fixture.txt', 'manifest.json'])); + const dir = temporary(); + for (const [name, bytes] of Object.entries(files)) { + const file = path.join(dir, name); + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, bytes); + } + const config = loadConfig({ dataDir: dir }, {}); + expect(decryptSecret(encrypted, config.secretKey)).toBe('test-only-provider-secret'); + const { db, report } = openDatabase(config.dbPath, config.backupsDir); + try { + expect(report.applied).toEqual([]); + expect(db.get<{ name: string }>('SELECT name FROM classes')?.name).toBe('Restored class'); + expect(Object.values(db.get('PRAGMA integrity_check') ?? {})).toEqual(['ok']); + expect(db.all('PRAGMA foreign_key_check')).toEqual([]); + expect(fs.readFileSync(path.join(config.uploadsDir, 'fixture.txt'), 'utf8')).toBe('Preserved document'); + } finally { + db.close(); + } + }); +}); diff --git a/tests/migration.test.ts b/tests/migration.test.ts new file mode 100644 index 0000000..4b909c1 --- /dev/null +++ b/tests/migration.test.ts @@ -0,0 +1,79 @@ +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { DatabaseSync } from 'node:sqlite'; +import { describe, expect, it } from 'vitest'; +import { DB, migrate } from '../server/db.ts'; +import { MIGRATIONS } from '../server/migrations.ts'; +import { importV1 } from '../server/services/v1import.ts'; +import { createTestApp } from './helpers.ts'; + +describe('safe migration paths', () => { + it('previews and imports a V1 database without changing its bytes, preserving answers and schedules', async () => { + const app = await createTestApp(); + const file = path.join(app.dir, 'v1-fixture.db'); + const old = new DatabaseSync(file); + old.exec(` + CREATE TABLE Class (id TEXT, name TEXT, sortOrder INTEGER, createdAt INTEGER); + CREATE TABLE MaterialGroup (id TEXT, classId TEXT, name TEXT, sortOrder INTEGER, createdAt INTEGER); + CREATE TABLE Deck (id TEXT, classId TEXT, groupId TEXT, name TEXT, description TEXT, sortOrder INTEGER, createdAt INTEGER); + CREATE TABLE Flashcard (id TEXT, deckId TEXT, front TEXT, back TEXT, sortOrder INTEGER); + CREATE TABLE QuizSet (id TEXT, classId TEXT, groupId TEXT, name TEXT, description TEXT, sortOrder INTEGER, createdAt INTEGER); + CREATE TABLE Question (id TEXT, quizSetId TEXT, type TEXT, prompt TEXT, rationale TEXT, category TEXT, sortOrder INTEGER); + CREATE TABLE AnswerOption (id TEXT, questionId TEXT, text TEXT, isCorrect INTEGER, sortOrder INTEGER); + CREATE TABLE QuizAttempt (id TEXT, quizSetId TEXT, score REAL, maxScore INTEGER, answersJson TEXT, isPartialRetake INTEGER, completedAt INTEGER); + CREATE TABLE SpacedRepetitionCardState (flashcardId TEXT, state INTEGER, reps INTEGER, due INTEGER, stability REAL, difficulty REAL, scheduledDays INTEGER, learningSteps INTEGER, lapses INTEGER, lastReview INTEGER, firstReviewedAt INTEGER); + INSERT INTO Class VALUES ('c','Legacy class',0,1700000000000); + INSERT INTO MaterialGroup VALUES ('g','c','Legacy group',0,1700000000000); + INSERT INTO Deck VALUES ('d','c','g','Legacy deck','',0,1700000000000); + INSERT INTO Flashcard VALUES ('f','d','Term','Definition',0); + INSERT INTO QuizSet VALUES ('z','c','g','Legacy quiz','',0,1700000000000); + INSERT INTO Question VALUES ('q','z','MULTIPLE_CHOICE','Pick A','Reason','Topic',0); + INSERT INTO AnswerOption VALUES ('a','q','A',1,0),('b','q','B',0,1); + INSERT INTO QuizAttempt VALUES ('attempt','z',1,1,'{"q":["a"]}',0,1700000000000); + INSERT INTO SpacedRepetitionCardState VALUES ('f',2,7,1800000000000,15,5,14,0,1,1700000000000,1600000000000); + `); + old.close(); + const digest = () => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); + const before = digest(); + try { + expect(importV1(app.ctx, file, { dryRun: true })).toMatchObject({ classes: 1, quizzes: 1, cards: 1, attempts: 1 }); + expect(app.ctx.db.get<{ n: number }>('SELECT count(*) AS n FROM classes')?.n).toBe(0); + importV1(app.ctx, file); + expect(digest()).toBe(before); + const classes = (await app.api('GET', '/api/classes')).body.classes; + expect(classes[0].name).toBe('Legacy class'); + const card = app.ctx.db.get<{ reps: number; due: number }>('SELECT reps, due FROM cards'); + expect(card).toMatchObject({ reps: 7, due: 1800000000000 }); + const attempt = app.ctx.db.get<{ id: string }>('SELECT id FROM attempts')!; + const result = (await app.api('GET', `/api/attempts/${attempt.id}`)).body; + expect(JSON.stringify(result)).toContain('Pick A'); + expect(app.ctx.db.get<{ score: number }>('SELECT score FROM responses')?.score).toBe(1); + expect(app.ctx.db.all('PRAGMA foreign_key_check')).toEqual([]); + } finally { + app.close(); + } + }); + + it('backs up before a schema change and rolls back a failed migration', () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'studydesk-migration-test-')); + const db = new DB(path.join(dir, 'test.db')); + try { + migrate(db, dir); + db.run("INSERT INTO settings VALUES ('fixture', 'preserved')"); + MIGRATIONS.push({ id: 999999, name: 'test_failure', sql: 'CREATE TABLE should_rollback (id INTEGER); INVALID SQL;' }); + try { + expect(() => migrate(db, dir)).toThrow(); + expect(db.get("SELECT name FROM sqlite_master WHERE name = 'should_rollback'")).toBeUndefined(); + expect(db.get<{ value: string }>("SELECT value FROM settings WHERE key = 'fixture'")?.value).toBe('preserved'); + expect(fs.readdirSync(dir).some((n) => n.startsWith('pre-migration-'))).toBe(true); + } finally { + MIGRATIONS.pop(); + } + } finally { + db.close(); + fs.rmSync(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/web/src/features/AiSettings.tsx b/web/src/features/AiSettings.tsx index 402629b..e625702 100644 --- a/web/src/features/AiSettings.tsx +++ b/web/src/features/AiSettings.tsx @@ -682,7 +682,7 @@ export default function AiSettings() { )}

- API keys are encrypted on the server and never sent back to the browser. A ChatGPT, Claude or Gemini app subscription is separate from API access and cannot be used here: each provider bills API usage on its own. + API keys are encrypted on the server and never sent back to the browser. These connections use each provider's API billing. ChatGPT plan sign-in requires a separate approved integration for remotely hosted apps; it is not configured in this installation.

diff --git a/web/src/features/quiz.tsx b/web/src/features/quiz.tsx index 231dcb6..de8e5bb 100644 --- a/web/src/features/quiz.tsx +++ b/web/src/features/quiz.tsx @@ -132,6 +132,7 @@ export function QuizRunner(p: RunnerProps) { const tick = useLatest(p.onTick); const finish = useLatest(p.onFinish); const elapsedRef = useLatest(elapsed); + const autoSubmitted = useRef(false); const total = p.questions.length; const index = Math.min(p.index, total - 1); @@ -168,7 +169,10 @@ export function QuizRunner(p: RunnerProps) { if (elapsed > 0 && elapsed % 10 === 0) tick.current?.(elapsed); }, [elapsed, tick]); useEffect(() => { - if (remaining === 0 && !p.finishing) finish.current(elapsedRef.current); + if (remaining === 0 && !p.finishing && !autoSubmitted.current) { + autoSubmitted.current = true; + finish.current(elapsedRef.current); + } }, [remaining, p.finishing, finish, elapsedRef]); useEffect(() => { topRef.current?.scrollIntoView({ block: 'start' }); diff --git a/web/src/pages/SessionPage.tsx b/web/src/pages/SessionPage.tsx index a8c35a6..2134278 100644 --- a/web/src/pages/SessionPage.tsx +++ b/web/src/pages/SessionPage.tsx @@ -106,6 +106,10 @@ export default function SessionPage() { const back = attempt.quizId ? `/quizzes/${attempt.quizId}` : attempt.classId ? `/classes/${attempt.classId}` : '/'; const exit = async () => { await flush(); + if (Object.keys(pending.current.answers).length > 0 || pending.current.flags !== undefined || pending.current.currentIndex !== undefined || pending.current.elapsedSec !== undefined) { + toast.error('Your latest progress has not been saved. Stay here and retry when connected.'); + return; + } void refresh(); navigate(back); }; @@ -165,6 +169,9 @@ export default function SessionPage() { setFinishing(true); try { await flush(); + if (Object.keys(pending.current.answers).length > 0 || pending.current.flags !== undefined || pending.current.currentIndex !== undefined || pending.current.elapsedSec !== undefined) { + throw new Error('Your latest progress has not been saved. Reconnect and submit again.'); + } const res = await api.post<{ attempt: Attempt }>(`/api/attempts/${attempt.id}/complete`, { elapsedSec }); qc.setQueryData(qk.attempt(attempt.id), res.attempt); void refresh(); diff --git a/web/src/styles.css b/web/src/styles.css index 3791210..5c85407 100644 --- a/web/src/styles.css +++ b/web/src/styles.css @@ -21,7 +21,7 @@ --line-strong: #d3cec1; --ink: #1b1a17; --ink-2: #57534a; - --ink-3: #8b867a; + --ink-3: #6f6a60; --accent: #2747d8; --accent-hover: #1c37b5; --accent-ink: #ffffff; @@ -57,7 +57,7 @@ --line-strong: #46423a; --ink: #f3f0e9; --ink-2: #bcb7ab; - --ink-3: #8a857a; + --ink-3: #aaa496; --accent: #91a6ff; --accent-hover: #adbdff; --accent-ink: #0f1430;