Harden private media and backup recovery; add V2 deployment and migration guides

This commit is contained in:
Elijah 2026-11-11 19:31:32 -07:00
parent c549c34f60
commit ffaa1f6afa
19 changed files with 623 additions and 14 deletions

17
.dockerignore Normal file
View file

@ -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*

1
.gitignore vendored
View file

@ -16,3 +16,4 @@ coverage/
npm-debug.log* npm-debug.log*
.test-data/ .test-data/
.claude/ .claude/
data-v2/

20
Dockerfile Normal file
View file

@ -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"]

90
PROGRESS.md Normal file
View file

@ -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.

81
README.md Normal file
View file

@ -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.

20
compose.yaml Normal file
View file

@ -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

44
docs/AI.md Normal file
View file

@ -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.

96
docs/DEPLOYMENT.md Normal file
View file

@ -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.

22
docs/MIGRATION.md Normal file
View file

@ -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.

View file

@ -137,9 +137,17 @@ export function createApp(app: AppContext): Hono {
if (!webDir) { 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); 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)); 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. // Hashed build assets never change; everything else is revalidated.
const immutable = urlPath.startsWith('/assets/'); const immutable = urlPath.startsWith('/assets/');
return sendFile(candidate, immutable ? 'public, max-age=31536000, immutable' : 'no-cache'); return sendFile(candidate, immutable ? 'public, max-age=31536000, immutable' : 'no-cache');

View file

@ -31,16 +31,21 @@ function bool(v: string | undefined, fallback: boolean): boolean {
} }
function loadSecret(dataDir: string, fromEnv: string | undefined): Buffer { 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(); return crypto.createHash('sha256').update(`studydesk:${fromEnv.trim()}`).digest();
} }
const file = path.join(dataDir, 'secret.key'); const file = path.join(dataDir, 'secret.key');
if (fs.existsSync(file)) { if (fs.existsSync(file)) {
const raw = Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'base64'); const raw = Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'base64');
if (raw.length === 32) return raw; 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); 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; return key;
} }

View file

@ -5,6 +5,7 @@ import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit'; import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod'; import { z } from 'zod';
import { titleSchema } from '../../shared/content.ts'; import { titleSchema } from '../../shared/content.ts';
import { isAuthenticated } from '../auth.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts'; import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { getClass, mapClass, resolveFolder } from '../services/content.ts'; import { getClass, mapClass, resolveFolder } from '../services/content.ts';
import { deleteDocument, documentPath, enqueue, getDocument, ingestUpload, listChunks, mapDocument, sourceLabel } from '../services/documents.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 * Images are private unless an enabled share contains a reference to them.
* a shared quiz show its pictures to visitors without exposing anything else. * Re-check on each request so revoking a share also revokes its embedded images.
*/ */
export function mediaRoute(app: AppContext): Hono { export function mediaRoute(app: AppContext): Hono {
const r = new Hono(); const r = new Hono();
r.get('/:name', (c) => { r.get('/:name', (c) => {
const name = c.req.param('name'); 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 (!/^[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 row = app.db.get<{ mime: string }>('SELECT mime FROM media WHERE id = ?', name);
const file = path.join(app.config.mediaDir, name); const file = path.join(app.config.mediaDir, name);
if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found'); if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found');
return new Response(fs.readFileSync(file), { 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; return r;

View file

@ -89,6 +89,10 @@ export function fullBackupStream(app: AppContext): { stream: ReadableStream<Uint
const tmp = path.join(app.config.backupsDir, `.export-${Date.now()}.db`); const tmp = path.join(app.config.backupsDir, `.export-${Date.now()}.db`);
app.db.snapshot(tmp); app.db.snapshot(tmp);
const entries: { name: string; file: string }[] = [{ name: 'study.db', file: tmp }]; const entries: { name: string; file: string }[] = [{ name: 'study.db', file: tmp }];
// Include the generated key so a full backup can actually restore encrypted AI settings.
// APP_SECRET is deliberately never exported; deployments using it must retain it separately.
const keyFile = path.join(app.config.dataDir, 'secret.key');
if (fs.existsSync(keyFile)) entries.push({ name: 'secret.key', file: keyFile });
for (const [dir, prefix] of [ for (const [dir, prefix] of [
[app.config.uploadsDir, 'uploads'], [app.config.uploadsDir, 'uploads'],
[app.config.mediaDir, 'media'], [app.config.mediaDir, 'media'],
@ -104,7 +108,7 @@ export function fullBackupStream(app: AppContext): { stream: ReadableStream<Uint
version: 1, version: 1,
createdAt: new Date().toISOString(), createdAt: new Date().toISOString(),
files: entries.length, files: entries.length,
restore: 'Stop the container, copy study.db, uploads/ and media/ into the data folder (replacing what is there), keep your existing secret.key, then start the container.', restore: 'Stop the container. Restore into a NEW data folder: study.db, uploads/, media/ and secret.key if present. Preserve the original APP_SECRET separately if configured. Never retain old study.db-wal or study.db-shm files. Keep the old folder intact until the restored installation is verified.',
}; };
let index = -1; let index = -1;
let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null; let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
@ -139,11 +143,14 @@ export function fullBackupStream(app: AppContext): { stream: ReadableStream<Uint
zip.add(entry); zip.add(entry);
try { try {
entry.push(new Uint8Array(fs.readFileSync(file)), true); entry.push(new Uint8Array(fs.readFileSync(file)), true);
} catch { } catch (error) {
entry.push(new Uint8Array(0), true); controllerRef?.error(error);
zip.terminate();
cleanup();
} }
}, },
cancel() { cancel() {
zip.terminate();
cleanup(); cleanup();
}, },
}); });

91
tests/hardening.test.ts Normal file
View file

@ -0,0 +1,91 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { unzipSync } from 'fflate';
import { afterEach, describe, expect, it } from 'vitest';
import { loadConfig } from '../server/config.ts';
import { encryptSecret, decryptSecret } from '../server/crypto.ts';
import { openDatabase } from '../server/db.ts';
import { TINY_PNG } from '../server/documents/testFixtures.ts';
import { createTestApp, type TestApp } from './helpers.ts';
let app: TestApp | undefined;
const dirs: string[] = [];
afterEach(() => {
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();
}
});
});

79
tests/migration.test.ts Normal file
View file

@ -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 });
}
});
});

View file

@ -682,7 +682,7 @@ export default function AiSettings() {
</div> </div>
)} )}
<p className="mt-2.5 text-xs text-ink-3"> <p className="mt-2.5 text-xs text-ink-3">
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.
</p> </p>
</Section> </Section>

View file

@ -132,6 +132,7 @@ export function QuizRunner(p: RunnerProps) {
const tick = useLatest(p.onTick); const tick = useLatest(p.onTick);
const finish = useLatest(p.onFinish); const finish = useLatest(p.onFinish);
const elapsedRef = useLatest(elapsed); const elapsedRef = useLatest(elapsed);
const autoSubmitted = useRef(false);
const total = p.questions.length; const total = p.questions.length;
const index = Math.min(p.index, total - 1); 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); if (elapsed > 0 && elapsed % 10 === 0) tick.current?.(elapsed);
}, [elapsed, tick]); }, [elapsed, tick]);
useEffect(() => { 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]); }, [remaining, p.finishing, finish, elapsedRef]);
useEffect(() => { useEffect(() => {
topRef.current?.scrollIntoView({ block: 'start' }); topRef.current?.scrollIntoView({ block: 'start' });

View file

@ -106,6 +106,10 @@ export default function SessionPage() {
const back = attempt.quizId ? `/quizzes/${attempt.quizId}` : attempt.classId ? `/classes/${attempt.classId}` : '/'; const back = attempt.quizId ? `/quizzes/${attempt.quizId}` : attempt.classId ? `/classes/${attempt.classId}` : '/';
const exit = async () => { const exit = async () => {
await flush(); 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(); void refresh();
navigate(back); navigate(back);
}; };
@ -165,6 +169,9 @@ export default function SessionPage() {
setFinishing(true); setFinishing(true);
try { try {
await flush(); 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 }); const res = await api.post<{ attempt: Attempt }>(`/api/attempts/${attempt.id}/complete`, { elapsedSec });
qc.setQueryData(qk.attempt(attempt.id), res.attempt); qc.setQueryData(qk.attempt(attempt.id), res.attempt);
void refresh(); void refresh();

View file

@ -21,7 +21,7 @@
--line-strong: #d3cec1; --line-strong: #d3cec1;
--ink: #1b1a17; --ink: #1b1a17;
--ink-2: #57534a; --ink-2: #57534a;
--ink-3: #8b867a; --ink-3: #6f6a60;
--accent: #2747d8; --accent: #2747d8;
--accent-hover: #1c37b5; --accent-hover: #1c37b5;
--accent-ink: #ffffff; --accent-ink: #ffffff;
@ -57,7 +57,7 @@
--line-strong: #46423a; --line-strong: #46423a;
--ink: #f3f0e9; --ink: #f3f0e9;
--ink-2: #bcb7ab; --ink-2: #bcb7ab;
--ink-3: #8a857a; --ink-3: #aaa496;
--accent: #91a6ff; --accent: #91a6ff;
--accent-hover: #adbdff; --accent-hover: #adbdff;
--accent-ink: #0f1430; --accent-ink: #0f1430;