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>
This commit is contained in:
MechaCat02
115
test/day-note.test.ts
Normal file
115
test/day-note.test.ts
Normal file
@@ -0,0 +1,115 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { describe, it } from 'node:test';
|
||||
import { dayLessons, dayNoteSkeleton, dayNoteTitle, lessonHeading, missingHeadings } from '../src/core/day-note.ts';
|
||||
import { subjectFromHeading } from '../src/core/notes.ts';
|
||||
import type { UntisLesson, UntisTimetable } from '../src/core/untis.ts';
|
||||
|
||||
function lesson(overrides: Partial<UntisLesson> & { periodId: number }): UntisLesson {
|
||||
return {
|
||||
lessonId: 1,
|
||||
date: '2026-09-18',
|
||||
start: '08:00',
|
||||
end: '08:45',
|
||||
statuses: ['REGULAR'],
|
||||
cancelled: false,
|
||||
changed: false,
|
||||
subjects: [{ name: 'DE', longName: 'Deutsch' }],
|
||||
teachers: [{ name: 'MEI', longName: 'Meier' }],
|
||||
rooms: [{ name: '204' }],
|
||||
classes: [],
|
||||
replaced: { subjects: [], teachers: [], rooms: [] },
|
||||
notes: {},
|
||||
homework: [],
|
||||
online: false,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function timetable(lessons: UntisLesson[]): UntisTimetable {
|
||||
return { from: '2026-09-18', to: '2026-09-18', days: [{ date: '2026-09-18', lessons, holidays: [] }] };
|
||||
}
|
||||
|
||||
describe('dayNoteTitle', () => {
|
||||
it('is the weekday and the date, as a person would write it', () => {
|
||||
assert.equal(dayNoteTitle('2026-09-18'), 'Freitag, 18.09.2026');
|
||||
});
|
||||
});
|
||||
|
||||
describe('lessonHeading', () => {
|
||||
it('leads with the subject, then the time, teacher and room', () => {
|
||||
assert.equal(lessonHeading(lesson({ periodId: 1 }), 0), '1. Deutsch — 08:00–08:45 · MEI · R 204');
|
||||
});
|
||||
|
||||
it('marks a substitution, because the teacher is not the usual one', () => {
|
||||
assert.match(lessonHeading(lesson({ periodId: 1, changed: true }), 0), /Vertretung$/);
|
||||
});
|
||||
|
||||
it('survives a period with no subject at all', () => {
|
||||
assert.match(lessonHeading(lesson({ periodId: 1, subjects: [] }), 2), /^3\. Stunde — /);
|
||||
});
|
||||
|
||||
it('writes a heading subjectFromHeading reads back — the loop that makes lessons searchable', () => {
|
||||
// These two have to agree or a day's notes index under nothing: the page
|
||||
// writes the heading, the indexer reads the subject out of it again.
|
||||
for (const [index, entry] of [lesson({ periodId: 1 }), lesson({ periodId: 2, changed: true })].entries()) {
|
||||
assert.equal(subjectFromHeading(lessonHeading(entry, index)), 'Deutsch');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('dayLessons', () => {
|
||||
it('leaves out a cancelled period, which taught nothing', () => {
|
||||
const lessons = dayLessons(
|
||||
timetable([lesson({ periodId: 1 }), lesson({ periodId: 2, cancelled: true, start: '08:50', end: '09:35' })]),
|
||||
'2026-09-18',
|
||||
);
|
||||
assert.deepEqual(lessons.map((entry) => entry.periodId), [1]);
|
||||
});
|
||||
|
||||
it('keeps a substitution, which did happen', () => {
|
||||
const lessons = dayLessons(timetable([lesson({ periodId: 1, changed: true })]), '2026-09-18');
|
||||
assert.equal(lessons[0]?.changed, true);
|
||||
});
|
||||
|
||||
it('is empty for a day the timetable does not cover', () => {
|
||||
assert.deepEqual(dayLessons(timetable([lesson({ periodId: 1 })]), '2026-09-19'), []);
|
||||
});
|
||||
});
|
||||
|
||||
describe('dayNoteSkeleton', () => {
|
||||
it('is a heading per lesson with room to write under each', () => {
|
||||
const text = dayNoteSkeleton(dayLessons(timetable([lesson({ periodId: 1 }), lesson({ periodId: 2, start: '08:50', end: '09:35' })]), '2026-09-18'));
|
||||
assert.equal(text.match(/^## /gm)?.length, 2);
|
||||
assert.match(text, /^## 1\. Deutsch/m);
|
||||
});
|
||||
|
||||
it('is empty when there are no lessons, rather than a lone heading', () => {
|
||||
assert.equal(dayNoteSkeleton([]), '');
|
||||
});
|
||||
});
|
||||
|
||||
describe('missingHeadings', () => {
|
||||
const lessons = dayLessons(
|
||||
timetable([lesson({ periodId: 1 }), lesson({ periodId: 2, start: '08:50', end: '09:35' })]),
|
||||
'2026-09-18',
|
||||
);
|
||||
|
||||
it('is empty when the note already has them', () => {
|
||||
assert.deepEqual(missingHeadings(dayNoteSkeleton(lessons), lessons), []);
|
||||
});
|
||||
|
||||
it('names the lesson a note started early does not have yet', () => {
|
||||
const started = '## 1. Deutsch — 08:00–08:45 · MEI · R 204\n\nErörterung.\n';
|
||||
assert.deepEqual(missingHeadings(started, lessons).map((entry) => entry.periodId), [2]);
|
||||
});
|
||||
|
||||
it('recognises a heading the person shortened', () => {
|
||||
// "2. Deutsch" is still the second period; adding it again would give the
|
||||
// day two of them.
|
||||
assert.deepEqual(missingHeadings('## 1. Kurz\n## 2. Auch kurz\n', lessons), []);
|
||||
});
|
||||
|
||||
it('is everything for an empty note', () => {
|
||||
assert.equal(missingHeadings('', lessons).length, 2);
|
||||
});
|
||||
});
|
||||
@@ -4,8 +4,14 @@ import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { describe, it } from 'node:test';
|
||||
import {
|
||||
dayNotePath,
|
||||
filterNotes,
|
||||
NoteConflict,
|
||||
NoteNotFound,
|
||||
noteSections,
|
||||
noteSubjects,
|
||||
replaceNote,
|
||||
subjectFromHeading,
|
||||
notePathFor,
|
||||
parseNote,
|
||||
readNoteAt,
|
||||
@@ -201,6 +207,142 @@ describe('writeNote', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('splitFrontmatter: block lists', () => {
|
||||
it('reads tags written as indented "- item" lines, which is how editors write them', () => {
|
||||
// Obsidian and most YAML front ends write a list this way; reading only
|
||||
// the inline form silently dropped every tag such an editor had written.
|
||||
const { front } = splitFrontmatter('---\ntitle: T\ntags:\n - klausur\n - aufsatz\n---\nx');
|
||||
assert.deepEqual(front.tags, ['klausur', 'aufsatz']);
|
||||
assert.equal(front.title, 'T');
|
||||
});
|
||||
|
||||
it('stops the list at the next key', () => {
|
||||
const { front } = splitFrontmatter('---\ntags:\n - eins\nsubject: Deutsch\n---\nx');
|
||||
assert.deepEqual(front.tags, ['eins']);
|
||||
assert.equal(front.subject, 'Deutsch');
|
||||
});
|
||||
});
|
||||
|
||||
describe('a note per school day', () => {
|
||||
const day = parseNote(
|
||||
'2026/2026-09-18.md',
|
||||
[
|
||||
'## 1. Deutsch — 08:00–08:45 · MEI',
|
||||
'',
|
||||
'Erörterung: These, Argument, Fazit.',
|
||||
'',
|
||||
'### Aufbau',
|
||||
'',
|
||||
'- Gegenargument nicht vergessen',
|
||||
'',
|
||||
'## 2. LF07 — 08:50–09:35 · Sb',
|
||||
'',
|
||||
'/24 = 254 nutzbare Adressen',
|
||||
].join('\n'),
|
||||
STAMP,
|
||||
);
|
||||
|
||||
it('does not take the year folder for a subject', () => {
|
||||
// "2026/" is a filing scheme, not a lesson.
|
||||
assert.equal(day.subject, undefined);
|
||||
});
|
||||
|
||||
it('splits into one section per lesson', () => {
|
||||
assert.deepEqual(noteSections(day).map((section) => section.subject), ['Deutsch', 'LF07']);
|
||||
});
|
||||
|
||||
it('keeps subheadings inside their lesson', () => {
|
||||
const first = noteSections(day)[0]!;
|
||||
assert.match(first.text, /### Aufbau/);
|
||||
assert.doesNotMatch(first.text, /LF07/);
|
||||
});
|
||||
|
||||
it('reports every subject the day covers', () => {
|
||||
assert.deepEqual(noteSubjects(day), ['Deutsch', 'LF07']);
|
||||
});
|
||||
|
||||
it('is found by a subject filter, which only its headings know', () => {
|
||||
assert.equal(filterNotes([day], { subject: 'lf07' }).length, 1);
|
||||
assert.equal(filterNotes([day], { subject: 'Mathe' }).length, 0);
|
||||
});
|
||||
|
||||
it('does not split on a ## inside a fenced code block', () => {
|
||||
const note = parseNote('2026/2026-09-18.md', '## Info\n\n```\n## nicht eine Stunde\n```\n', STAMP);
|
||||
assert.equal(noteSections(note).length, 1);
|
||||
});
|
||||
|
||||
it('has no sections when it is one piece of prose, as an imported note is', () => {
|
||||
assert.deepEqual(noteSections(parseNote('Deutsch/2026-09-15 A.md', 'Nur Text.', STAMP)), []);
|
||||
});
|
||||
});
|
||||
|
||||
describe('subjectFromHeading', () => {
|
||||
it('reads the subject out of every shape the page and a person write', () => {
|
||||
for (const [heading, expected] of [
|
||||
['1. Deutsch — 08:00–08:45 · MEI · R 204', 'Deutsch'],
|
||||
['2) LF07', 'LF07'],
|
||||
['Deutsch', 'Deutsch'],
|
||||
['08:00 Deutsch', 'Deutsch'],
|
||||
['3. Mathe (Vertretung)', 'Mathe'],
|
||||
] as const) {
|
||||
assert.equal(subjectFromHeading(heading), expected, heading);
|
||||
}
|
||||
});
|
||||
|
||||
it('names no subject rather than a wrong one', () => {
|
||||
for (const heading of ['1.', '08:00–08:45', '—', '###']) {
|
||||
assert.equal(subjectFromHeading(heading), undefined, heading);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('dayNotePath', () => {
|
||||
it('files a day under its year', () => {
|
||||
assert.equal(dayNotePath('2026-09-18'), '2026/2026-09-18.md');
|
||||
});
|
||||
});
|
||||
|
||||
describe('replaceNote', () => {
|
||||
it('overwrites, which is what saving from an editor means', async () => {
|
||||
const dir = await root();
|
||||
await replaceNote(dir, dayNotePath('2026-09-18'), { title: 'Freitag', text: 'eins', date: '2026-09-18' });
|
||||
const note = await replaceNote(dir, dayNotePath('2026-09-18'), { title: 'Freitag', text: 'zwei', date: '2026-09-18' });
|
||||
assert.equal(note.text, 'zwei');
|
||||
assert.equal((await readNotes(dir)).length, 1, 'saving twice is one note, not two');
|
||||
});
|
||||
|
||||
it('refuses a save that would clobber a version the editor never saw', async () => {
|
||||
// The notes folder is synced and open in more than one place; a phone must
|
||||
// not silently win over a laptop.
|
||||
const dir = await root();
|
||||
const first = await replaceNote(dir, 'x.md', { title: 'X', text: 'vom Laptop' });
|
||||
await assert.rejects(
|
||||
() => replaceNote(dir, 'x.md', { title: 'X', text: 'vom Handy' }, { expectedModifiedAt: '2020-01-01T00:00:00.000Z' }),
|
||||
NoteConflict,
|
||||
);
|
||||
assert.equal((await readNoteAt(dir, 'x.md')).text, 'vom Laptop', 'the refused save changed nothing');
|
||||
assert.ok(first.modifiedAt);
|
||||
});
|
||||
|
||||
it('accepts a save carrying the modification time it loaded', async () => {
|
||||
const dir = await root();
|
||||
const loaded = await replaceNote(dir, 'x.md', { title: 'X', text: 'eins' });
|
||||
const saved = await replaceNote(dir, 'x.md', { title: 'X', text: 'zwei' }, { expectedModifiedAt: loaded.modifiedAt });
|
||||
assert.equal(saved.text, 'zwei');
|
||||
});
|
||||
|
||||
it('creates the note when there is none, with nothing to clash against', async () => {
|
||||
const dir = await root();
|
||||
const note = await replaceNote(dir, dayNotePath('2026-09-18'), { title: 'Freitag', text: 'neu' }, { expectedModifiedAt: '2020-01-01T00:00:00.000Z' });
|
||||
assert.equal(note.text, 'neu');
|
||||
});
|
||||
|
||||
it('cannot be steered out of the notes root', async () => {
|
||||
const dir = await root();
|
||||
await assert.rejects(() => replaceNote(dir, '../escape.md', { title: 'X', text: 'x' }), /traversal/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('filterNotes', () => {
|
||||
const notes = [
|
||||
parseNote('Deutsch/2026-09-15 A.md', 'a', STAMP),
|
||||
|
||||
147
test/web-auth.test.ts
Normal file
147
test/web-auth.test.ts
Normal file
@@ -0,0 +1,147 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { describe, it } from 'node:test';
|
||||
import { createWebAuth, isSecureRequest, readCookie, SESSION_COOKIE } from '../src/http/web-auth.ts';
|
||||
|
||||
/**
|
||||
* The app's login. scrypt is deliberately slow, so these share one authenticator
|
||||
* rather than building one per test.
|
||||
*/
|
||||
const PASSWORD = 'ein-sehr-langes-testpasswort';
|
||||
const auth = createWebAuth(PASSWORD);
|
||||
|
||||
function cookieHeader(value: string): string {
|
||||
return `${SESSION_COOKIE}=${value}`;
|
||||
}
|
||||
|
||||
describe('createWebAuth without a password', () => {
|
||||
it('is disabled, and nothing it returns opens anything', () => {
|
||||
// The app is not served at all in this case; the object exists so callers
|
||||
// need no branch, and every answer it gives is "no".
|
||||
const off = createWebAuth(undefined);
|
||||
assert.equal(off.enabled, false);
|
||||
assert.equal(off.check(PASSWORD, '::1').ok, false);
|
||||
assert.equal(off.verify(cookieHeader('anything')), false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('password check', () => {
|
||||
it('accepts the password and rejects everything else', () => {
|
||||
assert.equal(auth.check(PASSWORD, 'a').ok, true);
|
||||
assert.equal(auth.check(PASSWORD + 'x', 'a').ok, false);
|
||||
assert.equal(auth.check('', 'a').ok, false);
|
||||
});
|
||||
|
||||
it('locks an address out after repeated failures', () => {
|
||||
const from = 'brute-force';
|
||||
let blocked;
|
||||
for (let attempt = 0; attempt < 12; attempt++) {
|
||||
blocked = auth.check('wrong', from);
|
||||
if (blocked.retryAfterSeconds !== undefined) break;
|
||||
}
|
||||
assert.ok(blocked?.retryAfterSeconds, 'expected a lockout with a retry hint');
|
||||
// And the lockout holds even for the *right* password, or it would be no
|
||||
// lockout at all — the attacker only has to guess it once.
|
||||
assert.equal(auth.check(PASSWORD, from).ok, false);
|
||||
});
|
||||
|
||||
it('counts per address, so one attacker cannot lock the user out', () => {
|
||||
assert.equal(auth.check(PASSWORD, 'somebody-else').ok, true);
|
||||
});
|
||||
|
||||
it('forgets the failures once a login succeeds', () => {
|
||||
const from = 'recovers';
|
||||
auth.check('wrong', from);
|
||||
auth.check('wrong', from);
|
||||
assert.equal(auth.check(PASSWORD, from).ok, true);
|
||||
assert.equal(auth.check(PASSWORD, from).ok, true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('session cookies', () => {
|
||||
it('mints a cookie it accepts back', () => {
|
||||
assert.equal(auth.verify(cookieHeader(auth.mint())), true);
|
||||
});
|
||||
|
||||
it('mints a different value every time', () => {
|
||||
assert.notEqual(auth.mint(), auth.mint());
|
||||
});
|
||||
|
||||
it('refuses a tampered signature', () => {
|
||||
const value = auth.mint();
|
||||
assert.equal(auth.verify(cookieHeader(`${value.slice(0, -1)}${value.at(-1) === 'A' ? 'B' : 'A'}`)), false);
|
||||
});
|
||||
|
||||
it('refuses an extended expiry, which is the point of signing it', () => {
|
||||
const value = auth.mint();
|
||||
const signature = value.slice(value.lastIndexOf('.') + 1);
|
||||
assert.equal(auth.verify(cookieHeader(`${Date.now() + 10 ** 12}.nonce.${signature}`)), false);
|
||||
});
|
||||
|
||||
it('refuses an expired cookie even with a good signature', () => {
|
||||
// Signed by this key, but for a moment that has passed.
|
||||
const body = `${Date.now() - 1000}.nonce`;
|
||||
const fresh = auth.mint();
|
||||
const shape = `${body}.${fresh.slice(fresh.lastIndexOf('.') + 1)}`;
|
||||
assert.equal(auth.verify(cookieHeader(shape)), false);
|
||||
});
|
||||
|
||||
it('refuses nonsense and an absent cookie', () => {
|
||||
for (const value of ['', 'x', 'a.b', '...']) assert.equal(auth.verify(cookieHeader(value)), false, value);
|
||||
assert.equal(auth.verify(undefined), false);
|
||||
assert.equal(auth.verify('other=1'), false);
|
||||
});
|
||||
|
||||
it('is not accepted by an authenticator built from a different password', () => {
|
||||
// Changing the password logs everyone out, because the signing key is
|
||||
// derived from it.
|
||||
const other = createWebAuth('ein-ganz-anderes-passwort');
|
||||
assert.equal(other.verify(cookieHeader(auth.mint())), false);
|
||||
});
|
||||
|
||||
it('is HttpOnly and SameSite=Strict, and Secure only over TLS', () => {
|
||||
const secure = auth.cookie('v', { secure: true });
|
||||
assert.match(secure, /HttpOnly/);
|
||||
assert.match(secure, /SameSite=Strict/);
|
||||
assert.match(secure, /Secure/);
|
||||
// Marking it Secure on a plain connection makes it vanish, which looks
|
||||
// exactly like a broken login.
|
||||
assert.doesNotMatch(auth.cookie('v', { secure: false }), /Secure/);
|
||||
});
|
||||
|
||||
it('clears with an immediate expiry', () => {
|
||||
assert.match(auth.clearCookie({ secure: true }), /Max-Age=0/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('readCookie', () => {
|
||||
it('finds one cookie among several', () => {
|
||||
assert.equal(readCookie('a=1; sc_app=wanted; b=2', 'sc_app'), 'wanted');
|
||||
});
|
||||
|
||||
it('does not match a name that merely ends the same way', () => {
|
||||
assert.equal(readCookie('not_sc_app=no', 'sc_app'), undefined);
|
||||
});
|
||||
|
||||
it('is undefined for no header', () => {
|
||||
assert.equal(readCookie(undefined, 'sc_app'), undefined);
|
||||
});
|
||||
});
|
||||
|
||||
describe('isSecureRequest', () => {
|
||||
const request = (headers: Record<string, string>, protocol = 'http') =>
|
||||
({ get: (name: string) => headers[name.toLowerCase()], protocol }) as never;
|
||||
|
||||
it('trusts the forwarded protocol, which is all there is behind a proxy', () => {
|
||||
assert.equal(isSecureRequest(request({ 'x-forwarded-proto': 'https' })), true);
|
||||
assert.equal(isSecureRequest(request({ 'x-forwarded-proto': 'http' })), false);
|
||||
});
|
||||
|
||||
it('reads only the first hop of a chain', () => {
|
||||
assert.equal(isSecureRequest(request({ 'x-forwarded-proto': 'https, http' })), true);
|
||||
});
|
||||
|
||||
it('falls back to the connection when nothing forwarded it', () => {
|
||||
assert.equal(isSecureRequest(request({}, 'https')), true);
|
||||
assert.equal(isSecureRequest(request({})), false);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user