Write the notes in an app, a school day at a time

The notes existed but there was nowhere to write them: a CLI command on a
laptop, a tool call through Claude, or a file in a Docker volume. None of
those is reachable from a phone in a lesson, which is where notes are
actually taken.

So: `/app`, served only when WEB_PASSWORD is set. A login, the day's
notes, and a settings page for the Schulcloud token — the one surface
here meant for a person rather than a program.

The shape follows how the notes are written: one note per school day,
one `##` heading per lesson, prose and lists and tables beneath. That
turns out to be the design decision that matters, twice over.

First, it is what lets WebUntis earn its keep. Opening a day with no
note fills in that day's lessons — numbered, with times, teacher and
room, cancellations dropped and substitutions marked. Retyping the
timetable is exactly the work the second upstream exists to avoid, and
"Stunden ergänzen" tops up a note started before the day ended without
touching what is already written.

Second, it changes how notes are indexed. A day note is indexed per
lesson, not whole: search answers "my own note, Deutsch, 18.09.2026"
rather than "my own note, Friday", and `list_notes subject=Deutsch`
finds a day whose frontmatter names no subject at all. Indexed whole,
every hit would read as a weekday and "what did we do in Deutsch" would
match notes whose other five lessons were something else. `lessonHeading`
and `subjectFromHeading` are a loop — the app writes the heading, the
indexer reads the subject back out — and a test holds them to it.

Notes taken in a lesson cannot be retaken, so the editor is built
around not losing them: autosave, every keystroke mirrored to local
storage, a save when the phone locks, and a fallback to the local copy
when the request never arrives. A save that would overwrite a version
the editor never saw is refused and the choice handed back — the notes
folder is synced and open in more than one place, and a phone must not
silently win over a laptop. `replaceNote` is separate from `writeNote`
for that reason: never-overwrite is right for `add_note` and exactly
wrong for an editor.

WEB_PASSWORD is the first credential here a human types, so it is the
first that can be guessed: scrypt at startup, never stored or compared
in the clear, per-address rate limiting — which is not decoration, since
the scrypt cost is itself a denial-of-service vector without it. The
session is a signed HttpOnly SameSite=Strict cookie whose key is derived
from the password, so changing it logs everyone out and there is no
second secret to keep. It opens /api, because a session is the user, and
never /mcp, because nothing in a browser speaks MCP.

Also here, because the app made them matter: frontmatter now reads the
indented `- item` list form editors write, so an Obsidian vault
round-trips its tags; and a four-digit folder is a filing scheme, not a
subject, so `2026/` does not file a school year under one.

357 tests; 106/107 smoke against the local instance, the one failure
being the H5P service that instance does not run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/smoke.mjs

@@ -30,6 +30,10 @@ process.env.STATE_DIR = STATE_DIR;
 // an empty directory is also the only way to assert the empty case.
 const NOTES_DIR = await mkdtemp(join(tmpdir(), 'schulcloud-smoke-notes-'));
 process.env.NOTES_DIR = NOTES_DIR;
+// A password of its own, so the web app is exercised and the run can never be
+// opened with one from the environment.
+const WEB_PASSWORD = `smoke-${randomBytes(16).toString('hex')}`;
+process.env.WEB_PASSWORD = WEB_PASSWORD;
 // The app is bound by this script on an ephemeral port, so config.port is unused.
 
 const config = loadConfig();
@@ -703,6 +707,123 @@ if (hasUntis) {
 	);
 }
 
+console.log('\n== web app ==');
+// The one surface here meant for a person rather than a program: a login, the
+// day's notes, and the settings page that replaces the Schulcloud token.
+{
+	const root = `http://127.0.0.1:${port}`;
+	const jsonHeaders = { 'content-type': 'application/json' };
+
+	const shell = await fetch(`${root}/app/`);
+	const shellText = await shell.text();
+	check(
+		'the app shell is served with a strict content security policy',
+		shell.ok &&
+			/text\/html/.test(shell.headers.get('content-type') ?? '') &&
+			/default-src 'none'/.test(shell.headers.get('content-security-policy') ?? '') &&
+			/no-store/.test(shell.headers.get('cache-control') ?? ''),
+		shell.headers.get('content-security-policy')?.slice(0, 40),
+	);
+	check('the shell holds no secret of its own', !shellText.includes(WEB_PASSWORD) && !shellText.includes(TOKEN));
+
+	const assets = await Promise.all(
+		['app.js', 'app.css', 'icon.svg', 'manifest.webmanifest'].map((name) => fetch(`${root}/app/${name}`)),
+	);
+	check('the app\'s assets are served', assets.every((response) => response.ok), assets.map((r) => r.status).join(' '));
+
+	const anonymousSession = await (await fetch(`${root}/app/session`)).json();
+	check('session says "not logged in" rather than failing', anonymousSession.authenticated === false);
+
+	const closed = await fetch(`${root}/api/notes`);
+	check('/api is closed without a session or a token', closed.status === 401, `got ${closed.status}`);
+
+	const wrong = await fetch(`${root}/app/login`, {
+		method: 'POST',
+		headers: jsonHeaders,
+		body: JSON.stringify({ password: 'not-the-password' }),
+	});
+	check('a wrong password is refused with no detail', wrong.status === 401, `got ${wrong.status}`);
+
+	const login = await fetch(`${root}/app/login`, {
+		method: 'POST',
+		headers: jsonHeaders,
+		body: JSON.stringify({ password: WEB_PASSWORD }),
+	});
+	const setCookie = login.headers.get('set-cookie') ?? '';
+	check(
+		'logging in sets an HttpOnly, SameSite=Strict session cookie',
+		login.ok && /HttpOnly/.test(setCookie) && /SameSite=Strict/i.test(setCookie),
+		setCookie.split(';').slice(1).join(';').trim(),
+	);
+
+	const cookie = setCookie.split(';')[0] ?? '';
+	const withSession = { cookie };
+
+	const session = await (await fetch(`${root}/app/session`, { headers: withSession })).json();
+	check('the session is recognised', session.authenticated === true);
+
+	const viaSession = await fetch(`${root}/api/notes`, { headers: withSession });
+	check('a logged-in browser reaches /api without a token', viaSession.ok, `got ${viaSession.status}`);
+
+	const mcpViaSession = await fetch(`${root}/mcp`, {
+		method: 'POST',
+		headers: { ...jsonHeaders, accept: 'application/json, text/event-stream', ...withSession },
+		body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }),
+	});
+	// The session is for the app. Nothing in a browser speaks MCP, and a surface
+	// that is not needed is not offered.
+	check('the session does not open /mcp', mcpViaSession.status === 401, `got ${mcpViaSession.status}`);
+
+	const tampered = await fetch(`${root}/api/notes`, { headers: { cookie: `${cookie.split('=')[0]}=9999999999999.x.forged` } });
+	check('a forged session cookie is refused', tampered.status === 401, `got ${tampered.status}`);
+
+	// The day editor: read the day, write it, read it back.
+	const day = await (await fetch(`${root}/api/notes/day?date=2026-09-18`, { headers: withSession })).json();
+	check(
+		'the day route answers with a path, a title and the timetable state',
+		day.path === '2026/2026-09-18.md' && /2026/.test(day.title) && ['ok', 'off', 'unavailable'].includes(day.timetable),
+		`${day.title} — timetable ${day.timetable}, ${day.lessons?.length ?? 0} lesson(s)`,
+	);
+
+	// A subject no other check uses, so "found by its heading" cannot pass by
+	// matching the subject note the notes section wrote earlier.
+	const body = '## 1. Geschichte — 08:00–08:45\n\nWeimarer Republik: Ursachen des Scheiterns.\n';
+	const saved = await fetch(`${root}/api/notes/day`, {
+		method: 'PUT',
+		headers: { ...jsonHeaders, ...withSession },
+		body: JSON.stringify({ date: '2026-09-18', text: body }),
+	});
+	const savedBody = await saved.json();
+	check('the day saves', saved.ok && savedBody.path === '2026/2026-09-18.md', `${saved.status}`);
+
+	const conflict = await fetch(`${root}/api/notes/day`, {
+		method: 'PUT',
+		headers: { ...jsonHeaders, ...withSession },
+		body: JSON.stringify({ date: '2026-09-18', text: 'überschrieben', expectedModifiedAt: '2020-01-01T00:00:00.000Z' }),
+	});
+	check('a save that would clobber a newer version is refused', conflict.status === 409, `got ${conflict.status}`);
+
+	const reread = await (await fetch(`${root}/api/notes/day?date=2026-09-18`, { headers: withSession })).json();
+	// Trimmed on both sides: a stored note ends with exactly one newline, which
+	// is the editor's business and not something to assert on.
+	check('the refused save changed nothing', reread.text.trim() === body.trim(), reread.text.split('\n')[0]);
+
+	// The lesson heading the page writes has to be the one the index reads back,
+	// or a day's notes are filed under no subject at all.
+	const bySubject = await (await fetch(`${root}/api/notes?subject=Geschichte`, { headers: withSession })).json();
+	check(
+		'a day note is found by a subject only its lesson headings know',
+		bySubject.count === 1 && bySubject.notes[0]?.path === '2026/2026-09-18.md',
+		`${bySubject.count} note(s)`,
+	);
+
+	const badDate = await fetch(`${root}/api/notes/day?date=2026-02-30`, { headers: withSession });
+	check('a date that does not exist is refused', badDate.status === 400, `got ${badDate.status}`);
+
+	const loggedOut = await fetch(`${root}/app/logout`, { method: 'POST', headers: withSession });
+	check('logging out clears the cookie', loggedOut.ok && /Max-Age=0/.test(loggedOut.headers.get('set-cookie') ?? ''));
+}
+
 console.log('\n== api_get guard rails ==');
 check('api_get allows /api/ paths', !(await call('api_get', { path: '/api/v3/me' })).isError);
 check('api_get rejects non-/api path', (await call('api_get', { path: '/etc/passwd' })).isError);