@ranzenjs/client 0.2.1 → 0.4.0

package/dist/kurswahl/parse.js

@@ -0,0 +1,149 @@
+import { layoutChanged } from '../errors.js';
+import { all, attr, cells, hasClass, one, ownText, parseHtml, stripTags, text } from '../html.js';
+import { isoDate } from '../util.js';
+const DAYS = ['montag', 'dienstag', 'mittwoch', 'donnerstag', 'freitag', 'samstag', 'sonntag'];
+// "<b>Leiste 1: LK 1:  MATHEMATIK bei Muster, Frau<br>Raum: 101, Woche: A</b><br>Realkurs: 7"
+const TOOLTIP = /^<b>\s*Leiste\s+(\d+):\s*(.*?)(?:\s+bei\s+(.*?))?\s*<br\s*\/?>\s*Raum:\s*(.*?)(?:,\s*Woche:\s*([AB]))?\s*<\/b>\s*<br\s*\/?>\s*Realkurs:\s*(\d+)\s*$/is;
+// "2: LK 2:  PH-LK (Mu)" or "18: TUT (Bsp)".
+const LABEL = /^(\d+):\s*(?:LK\s*\d+:\s*)?(.+?)(?:\s*\(([^()]+)\))?$/;
+// "27.08.26  12:12:51"
+const STAMP = /(\d{2})\.(\d{2})\.(\d{2}|\d{4})\s+(\d{2}):(\d{2}):(\d{2})/g;
+/** The anti-CSRF token every Kurswahl page carries. */
+export function csrfToken(html) {
+    const token = attr(one('meta[name="anti_csrf_token"]', parseHtml(html)), 'content');
+    return token && isToken(token) ? token : null;
+}
+/** The timetable database the page's week form posts, e.g. "musterschule_stundenplan_1". */
+export function timetableDatabase(doc) {
+    const database = attr(one('input[name="db_name"]', doc), 'value');
+    if (!database || !isDatabase(database))
+        throw layoutChanged('the timetable database field');
+    return database;
+}
+/** Kurswahl marks "allgemeiner Stundenplan" as selected only when it shows the general plan. */
+export function isGeneralPlan(html) {
+    return all('select[name="woche"] option[selected]', parseHtml(html)).some((option) => attr(option, 'value') === '0');
+}
+/** Visible ASCII only, since the token travels in a header; shared with state validation. */
+export function isToken(value) {
+    return /^[\x21-\x7e]{1,512}$/.test(value);
+}
+export function isDatabase(value) {
+    return /^[\w-]{1,200}$/.test(value);
+}
+export function parseTimetable(html, drift) {
+    const doc = parseHtml(html);
+    const database = timetableDatabase(doc);
+    const table = one('table.stundenplan', doc);
+    if (!table)
+        throw layoutChanged('the timetable table');
+    const [head, ...body] = all('tr', table);
+    const days = all('th', head ?? table)
+        .slice(1)
+        .map((th) => DAYS.indexOf(text(th).toLowerCase()) + 1);
+    if (!days.length || !days.every(isWeekday))
+        throw layoutChanged('weekday headers in the timetable');
+    const periods = [];
+    const courses = new Map();
+    const lessons = [];
+    for (const row of body) {
+        const [first, ...slots] = cells(row);
+        const match = /^(\d+)\.\s*(?:(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2}))?/.exec(text(first));
+        if (!match || slots.length !== days.length)
+            throw layoutChanged('timetable rows per period');
+        const period = Number(match[1]);
+        periods.push({ period, start: match[2] ?? null, end: match[3] ?? null });
+        slots.forEach((slot, index) => {
+            const entries = all('div[tooltip]', slot);
+            if (!entries.length && text(slot))
+                throw layoutChanged('course entries in timetable cells');
+            for (const entry of entries) {
+                const { course, room, rotation } = parseEntry(entry);
+                const known = courses.get(course.id);
+                if (!known)
+                    courses.set(course.id, course);
+                else if (JSON.stringify(known) !== JSON.stringify(course)) {
+                    drift('A course shows different details in different cells.');
+                }
+                lessons.push({ course: course.id, day: days[index], period, room, rotation });
+            }
+        });
+    }
+    const options = all('select[name="woche"] option', doc).map((option) => {
+        const value = attr(option, 'value') ?? '';
+        const week = parseWeek(value, text(option));
+        if (!week && value !== '0')
+            drift('A week option has an unknown format.');
+        return { value, week, selected: 'selected' in option.attribs };
+    });
+    // The general plan selects no option (or "0"); an unreadable dated week must not pass for it.
+    const chosen = options.find((option) => option.selected && option.value !== '0');
+    if (chosen && !chosen.week)
+        throw layoutChanged('the selected week');
+    return {
+        database,
+        week: chosen?.week ?? null,
+        weeks: options.flatMap((option) => (option.week ? [option.week] : [])),
+        periods,
+        courses: [...courses.values()],
+        lessons,
+        ...changeTimes(doc)
+    };
+}
+function parseEntry(entry) {
+    const tooltip = TOOLTIP.exec((attr(entry, 'tooltip') ?? '').trim());
+    const label = LABEL.exec(ownText(entry));
+    if (!tooltip || !label)
+        throw layoutChanged('a known course entry in the timetable');
+    const [, block = '', heading = '', teacher = '', room = '', week, id = ''] = tooltip;
+    const code = label[2] ?? '';
+    const level = /^(LK|GK)\b\s*(?:\d+:)?\s*(.*)$/.exec(stripTags(heading));
+    // The heading names the level; failing that, a "-LK"/"-GK" code or the cell's lk class does.
+    const kind = level?.[1] ?? /-(LK|GK)$/.exec(code)?.[1] ?? (hasClass(entry, 'lk') ? 'LK' : null);
+    const person = /^(.*?)(?:,\s*(Frau|Herr))?$/.exec(stripTags(teacher));
+    const shown = text(one('span', entry));
+    return {
+        course: {
+            id,
+            block: Number(block),
+            code,
+            title: (level ? level[2] : stripTags(heading)) || null,
+            level: kind,
+            teacher: {
+                code: label[3]?.trim() || null,
+                lastName: person?.[1] || null,
+                salutation: person?.[2] ?? null
+            }
+        },
+        room: stripTags(room) || shown.replace(/\[[AB]\]/, '').trim() || null,
+        rotation: (week ?? /\[([AB])\]/.exec(shown)?.[1] ?? null)
+    };
+}
+function isWeekday(day) {
+    return day >= 1 && day <= 7;
+}
+function parseWeek(value, label) {
+    const [start, end] = label.split(/\s+-\s+/).map((part) => isoDate(part));
+    return /^\d{2}_\d{2}_\d{4}$/.test(value) && start && end ? { id: value, start, end } : null;
+}
+// "Letzte Änderung Stundenplan (Kurszuteilung): 27.08.26 12:12:51 (25.08.26 09:02:04)"
+function changeTimes(doc) {
+    let updatedAt = null;
+    let assignedAt = null;
+    let examsUpdatedAt = null;
+    for (const row of all('tr', doc)) {
+        const [label = '', value = ''] = cells(row).map((cell) => text(cell));
+        if (!label.startsWith('Letzte Änderung'))
+            continue;
+        const [first = null, second = null] = [...value.matchAll(STAMP)].map(localTime);
+        if (label.includes('Klausurplan'))
+            examsUpdatedAt = first;
+        else if (label.includes('Stundenplan'))
+            [updatedAt, assignedAt] = [first, second];
+    }
+    return { updatedAt, assignedAt, examsUpdatedAt };
+}
+function localTime([, day, month, year = '', hours, minutes, seconds]) {
+    const date = isoDate(`${day}.${month}.${year.length === 2 ? `20${year}` : year}`);
+    return date && `${date}T${hours}:${minutes}:${seconds}`;
+}

package/dist/kurswahl/session.d.ts

@@ -0,0 +1,29 @@
+import type { Reply, Transport } from '../transport/http.js';
+export interface KurswahlAccount {
+    /** The school's subdomain, e.g. "musterschule". */
+    readonly school: string;
+    readonly username: string;
+}
+export declare const WWW = "https://www.kurswahl-online.de";
+export declare function schoolUrl(school: string): string;
+export declare class KurswahlSession {
+    #private;
+    readonly account: KurswahlAccount;
+    readonly transport: Transport;
+    token: string | null;
+    database: string | null;
+    constructor(account: KurswahlAccount, transport: Transport, token: string | null, database?: string | null);
+    get disposed(): boolean;
+    ensureOpen(): void;
+    dispose(): void;
+    /** A page the way post_link() opens it: a multipart POST carrying the current token. */
+    page(path: string, fields: Record<string, string>, signal?: AbortSignal): Promise<Reply>;
+    /** An XHR call; the token travels as a header, and a new one may come back the same way. */
+    ajax(path: string, form: Record<string, string>, signal?: AbortSignal): Promise<Reply>;
+    /** Leaves through the logout link, after any request still running. */
+    leave(signal?: AbortSignal): Promise<void>;
+}
+/** A token handed back in the XHR header, kept only if exported state would accept it. */
+export declare function nextToken(reply: Reply, current: string | null): string | null;
+/** The sign-in form, which Kurswahl serves in place of any page once the session is gone. */
+export declare function isLoginPage(html: string): boolean;

package/dist/kurswahl/session.js

@@ -0,0 +1,125 @@
+import { ensureOk } from '../app.js';
+import { fail, isRanzenError, layoutChanged } from '../errors.js';
+import { Limiter } from '../transport/limiter.js';
+import { csrfToken, isToken } from './parse.js';
+export const WWW = 'https://www.kurswahl-online.de';
+export function schoolUrl(school) {
+    return `https://${school}.kurswahl-online.de`;
+}
+// Package-internal: one request at a time, since every reply hands out the next CSRF token.
+export class KurswahlSession {
+    account;
+    transport;
+    token;
+    database;
+    #life = new AbortController();
+    #queue = new Limiter(1);
+    constructor(account, transport, token, database = null) {
+        this.account = account;
+        this.transport = transport;
+        this.token = token;
+        this.database = database;
+    }
+    get disposed() {
+        return this.#life.signal.aborted;
+    }
+    ensureOpen() {
+        if (this.disposed)
+            throw fail('DISPOSED', 'The connection was disposed.');
+    }
+    dispose() {
+        this.#life.abort();
+        this.transport.jar.clear();
+    }
+    /** A page the way post_link() opens it: a multipart POST carrying the current token. */
+    page(path, fields, signal) {
+        return this.#run(signal, async (bound) => {
+            const form = new FormData();
+            for (const [name, value] of Object.entries(fields))
+                form.set(name, value);
+            form.set('_scrollLeft', '0');
+            form.set('_scrollTop', '0');
+            form.set('_scrollLocation', `/${path}`);
+            if (this.token)
+                form.set('_anti_csrf_token', this.token);
+            const reply = await this.transport.send({
+                url: `${schoolUrl(this.account.school)}/${path}`,
+                method: 'POST',
+                multipart: form,
+                redirects: 'manual',
+                signal: bound
+            });
+            this.#check(reply, path);
+            // Every page hands out the token for the next request; going on with a stale one would fail later.
+            const token = csrfToken(reply.text);
+            if (!token)
+                throw layoutChanged('an anti-CSRF token on the page');
+            this.token = token;
+            return reply;
+        });
+    }
+    /** An XHR call; the token travels as a header, and a new one may come back the same way. */
+    ajax(path, form, signal) {
+        return this.#run(signal, async (bound) => {
+            const headers = { 'x-requested-with': 'XMLHttpRequest' };
+            if (this.token)
+                headers['x-csrf-token'] = this.token;
+            const reply = await this.transport.send({
+                url: `${schoolUrl(this.account.school)}/${path}`,
+                method: 'POST',
+                form,
+                headers,
+                redirects: 'manual',
+                signal: bound
+            });
+            this.#check(reply, path);
+            this.token = nextToken(reply, this.token);
+            return reply;
+        });
+    }
+    /** Leaves through the logout link, after any request still running. */
+    leave(signal) {
+        return this.#run(signal, async (bound) => {
+            const url = `${schoolUrl(this.account.school)}/login.php`;
+            const reply = await this.transport.send({ url, redirects: 'manual', signal: bound });
+            // A refused logout may leave the session alive, so it must not pass for success.
+            if (!reply.location)
+                ensureOk(reply.status, 'login.php');
+        });
+    }
+    // Kurswahl flags an ended session with X-LOGIN-FORM on XHR and a redirect to login.php on pages.
+    #check(reply, path) {
+        const toLogin = reply.location && /\/login\.php$|^\/?$/.test(reply.location.pathname);
+        if (reply.headers.get('x-login-form') === 'true' || toLogin || isLoginPage(reply.text)) {
+            throw fail('SESSION_EXPIRED', 'The Kurswahl session has ended.');
+        }
+        if (reply.location)
+            throw layoutChanged(`${path} to answer without a redirect`);
+        ensureOk(reply.status, path);
+    }
+    async #run(signal, work) {
+        this.ensureOpen();
+        const life = this.#life.signal;
+        const bound = signal ? AbortSignal.any([signal, life]) : life;
+        try {
+            return await this.#queue.run(() => work(bound), bound);
+        }
+        catch (error) {
+            if (isRanzenError(error) || !bound.aborted)
+                throw error;
+            throw fail('ABORTED', 'Request aborted.', error);
+        }
+        finally {
+            this.ensureOpen();
+        }
+    }
+}
+/** A token handed back in the XHR header, kept only if exported state would accept it. */
+export function nextToken(reply, current) {
+    const token = reply.headers.get('x-csrf-token');
+    return token && isToken(token) ? token : current;
+}
+/** The sign-in form, which Kurswahl serves in place of any page once the session is gone. */
+export function isLoginPage(html) {
+    return /<input\b[^>]*\bname\s*=\s*["']?realpasswort\b/i.test(html);
+}

package/dist/kurswahl/sign-in.d.ts

@@ -0,0 +1,19 @@
+import type { Transport } from '../transport/http.js';
+import { KurswahlSession } from './session.js';
+export interface KurswahlCredentials {
+    /** The school's subdomain, e.g. "musterschule"; see schools(). */
+    school: string;
+    username: string;
+    password: string;
+}
+interface Argon2Parameters {
+    type: 1 | 2;
+    time: number;
+    mem: number;
+    parallelism: number;
+    hashLen: number;
+}
+/** Signs in like the login page's script does, hashing the password with Argon2 on this side. */
+export declare function signIn(transport: Transport, { school, username, password }: KurswahlCredentials, signal: AbortSignal | undefined): Promise<KurswahlSession>;
+export declare function argon2(password: string, salt: string, parameters: Argon2Parameters | null | undefined): Promise<string>;
+export {};

package/dist/kurswahl/sign-in.js

@@ -0,0 +1,134 @@
+import { argon2i, argon2id } from 'hash-wasm';
+import { fail, layoutChanged } from '../errors.js';
+import { isRecord, parseJson } from '../util.js';
+import { csrfToken } from './parse.js';
+import { isLoginPage, KurswahlSession, nextToken, schoolUrl } from './session.js';
+/** Signs in like the login page's script does, hashing the password with Argon2 on this side. */
+export async function signIn(transport, { school, username, password }, signal) {
+    const base = schoolUrl(school);
+    const login = await transport.send({ url: `${base}/login.php`, redirects: 'manual', signal });
+    // An unknown subdomain bounces to the main site.
+    if (login.location)
+        throw fail('NOT_FOUND', 'Kurswahl Online does not know this school.');
+    const versions = argon2Parameters(login.text);
+    let token = csrfToken(login.text);
+    // The login page's XHR carries the token as a header and may get the next one back.
+    const headers = { 'x-requested-with': 'XMLHttpRequest' };
+    if (token)
+        headers['x-csrf-token'] = token;
+    const answer = await transport.send({
+        url: `${base}/login.php`,
+        method: 'POST',
+        form: { ajax: 'argon2', username },
+        headers,
+        redirects: 'manual',
+        signal
+    });
+    token = nextToken(answer, token);
+    const { salts, rotating } = readSalts(parseJson(answer.text, 'the Argon2 salts'));
+    const latest = versions.length - 1;
+    const hash = (salt, version) => argon2(password, salt, versions[version]);
+    const hashes = await Promise.all(salts.map(async ({ version, raw, salt, upgradeSalt }) => {
+        const entry = {
+            version: raw,
+            hash: version === 0 ? password : await hash(salt, version),
+            rotating: false
+        };
+        if (upgradeSalt)
+            entry.upgrade_hash = await hash(upgradeSalt, latest);
+        return entry;
+    }));
+    if (rotating) {
+        hashes.push({
+            version: latest,
+            hash: await hash(rotating, latest),
+            upgrade_hash: null,
+            rotating: true
+        });
+    }
+    const form = new FormData();
+    form.set('username', username);
+    form.set('passwort', '');
+    form.set('keep_active', 'on');
+    form.set('resolution', '1920x1080');
+    form.set('realpasswort', JSON.stringify(hashes));
+    form.set('_scrollLeft', '0');
+    form.set('_scrollTop', '0');
+    form.set('_scrollLocation', '/login.php');
+    if (token)
+        form.set('_anti_csrf_token', token);
+    const result = await transport.send({
+        url: `${base}/login.php`,
+        method: 'POST',
+        multipart: form,
+        redirects: 'manual',
+        signal
+    });
+    if (isLoginPage(result.text))
+        throw fail('AUTH_FAILED', 'Kurswahl Online rejected the login.');
+    // The answer is an interstitial whose script continues with post_link("index.php").
+    if (result.status !== 200 || !/post_link\(\s*["']index\.php["']/.test(result.text)) {
+        throw layoutChanged('the page that follows a Kurswahl login');
+    }
+    const account = { school, username };
+    const session = new KurswahlSession(account, transport, csrfToken(result.text) ?? token);
+    await session.page('index.php', {}, signal);
+    return session;
+}
+// kwo.settings("argon2_client_parameters", ["dummy for old schema", {type, time, mem, ...}, ...])
+function argon2Parameters(html) {
+    const json = /kwo\.settings\(\s*"argon2_client_parameters"\s*,\s*(\[.*?\])\s*\)\s*;/s.exec(html)?.[1];
+    const list = json === undefined ? null : parseJson(json, 'the Argon2 parameters');
+    if (!Array.isArray(list) || list.length < 2)
+        throw layoutChanged('the Argon2 parameters');
+    return list.map((entry) => (isParameters(entry) ? entry : null));
+}
+// Far above today's cost (time 14, 56 MiB), so a broken page cannot exhaust the host.
+const LIMITS = { time: 100, mem: 512 * 1024, parallelism: 16, hashLen: 256 };
+function isParameters(value) {
+    if (!isRecord(value) || (value.type !== 1 && value.type !== 2))
+        return false;
+    return ['time', 'mem', 'parallelism', 'hashLen'].every((key) => {
+        const number = value[key];
+        return Number.isSafeInteger(number) && Number(number) > 0 && Number(number) <= LIMITS[key];
+    });
+}
+function readSalts(data) {
+    if (!isRecord(data) || !Array.isArray(data.salts) || !data.salts.length) {
+        throw layoutChanged('Argon2 salts for the login');
+    }
+    const salts = data.salts.map((entry) => {
+        const version = isRecord(entry) ? Number(entry.version) : NaN;
+        if (!isRecord(entry) || !Number.isSafeInteger(version) || version < 0) {
+            throw layoutChanged('Argon2 salts for the login');
+        }
+        const salt = typeof entry.salt === 'string' ? entry.salt : '';
+        if (version !== 0 && !salt)
+            throw layoutChanged('Argon2 salts for the login');
+        return {
+            version,
+            raw: entry.version,
+            salt,
+            upgradeSalt: typeof entry.upgrade_salt === 'string' ? entry.upgrade_salt : null
+        };
+    });
+    return { salts, rotating: typeof data.rotating_salt === 'string' ? data.rotating_salt : null };
+}
+// The browser worker passes UTF-8 bytes but the JS string length, so longer UTF-8 input is cut short.
+export function argon2(password, salt, parameters) {
+    if (!parameters)
+        throw layoutChanged('Argon2 parameters for every salt version');
+    const bytes = (value) => new TextEncoder().encode(value).slice(0, value.length);
+    return (parameters.type === 2 ? argon2id : argon2i)({
+        password: bytes(password),
+        salt: bytes(salt),
+        iterations: parameters.time,
+        memorySize: parameters.mem,
+        parallelism: parameters.parallelism,
+        hashLength: parameters.hashLen,
+        outputType: 'hex'
+    }).catch((error) => {
+        // hash-wasm refuses combinations such as too little memory per lane or a short salt.
+        throw layoutChanged('usable Argon2 parameters and salts', error);
+    });
+}

package/dist/kurswahl/state.d.ts

@@ -0,0 +1,12 @@
+import type { StoredCookie } from '../transport/cookies.js';
+import type { KurswahlAccount } from './session.js';
+export interface KurswahlState {
+    account: KurswahlAccount;
+    token: string | null;
+    database: string | null;
+    cookies: StoredCookie[];
+}
+export declare function writeKurswahlState({ account, token, database, cookies }: KurswahlState): string;
+export declare function readKurswahlState(text: string): KurswahlState;
+/** A Kurswahl subdomain, so a school key can never point a request at another host. */
+export declare function isSchool(value: string): boolean;

package/dist/kurswahl/state.js

@@ -0,0 +1,43 @@
+import { fail } from '../errors.js';
+import { copyCookie, isCookie } from '../state.js';
+import { isRecord } from '../util.js';
+import { isDatabase, isToken } from './parse.js';
+const FORMAT = 'ranzen/kurswahl@1';
+export function writeKurswahlState({ account, token, database, cookies }) {
+    const { school, username } = account;
+    return JSON.stringify({ format: FORMAT, school, username, token, database, cookies });
+}
+export function readKurswahlState(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw fail('INVALID_STATE', 'Connection state is not valid JSON.');
+    }
+    if (!isRecord(data) || data.format !== FORMAT) {
+        throw fail('INVALID_STATE', 'Connection state has an unknown format.');
+    }
+    const { school, username, token, database, cookies } = data;
+    if (typeof school !== 'string' || !isSchool(school)) {
+        throw fail('INVALID_STATE', 'Connection state has an invalid school.');
+    }
+    if (typeof username !== 'string' || !username) {
+        throw fail('INVALID_STATE', 'Connection state has an invalid username.');
+    }
+    if (!isNullOr(token, isToken) || !isNullOr(database, isDatabase)) {
+        throw fail('INVALID_STATE', 'Connection state has an invalid token or database.');
+    }
+    if (!Array.isArray(cookies) || !cookies.every(isCookie)) {
+        throw fail('INVALID_STATE', 'Connection state has invalid cookies.');
+    }
+    return { account: { school, username }, token, database, cookies: cookies.map(copyCookie) };
+}
+/** A Kurswahl subdomain, so a school key can never point a request at another host. */
+export function isSchool(value) {
+    return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(value) && value !== 'www';
+}
+// The same checks the parser applies, so every exported state restores.
+function isNullOr(value, valid) {
+    return value === null || (typeof value === 'string' && valid(value));
+}

package/dist/kurswahl/types.d.ts

@@ -0,0 +1,68 @@
+import type { Rotation } from '../rotation.js';
+export type { Rotation };
+/** ISO weekday, 1 = Monday. */
+export type Weekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export interface School {
+    /** The subdomain, e.g. "musterschule" for musterschule.kurswahl-online.de. */
+    id: string;
+    name: string;
+}
+export interface KurswahlTeacher {
+    /** The school's short code, the same one SPH uses, e.g. "Mu". */
+    code: string | null;
+    /** As written, e.g. "McLeod"; named like the SPH teacher field. */
+    lastName: string | null;
+    salutation: 'Frau' | 'Herr' | null;
+}
+export interface KurswahlCourse {
+    /** Kurswahl's "Realkurs" number; unrelated to SPH course ids. */
+    id: string;
+    /** The "Leiste" the course runs in. */
+    block: number | null;
+    /** The short name shown in the timetable, e.g. "M-LK" or "TUT". */
+    code: string;
+    /** The long name as written, e.g. "MATHEMATIK" or "Politik&Wirtschaft". */
+    title: string | null;
+    level: 'LK' | 'GK' | null;
+    teacher: KurswahlTeacher;
+}
+export interface KurswahlLesson {
+    /** A KurswahlCourse id. */
+    course: string;
+    day: Weekday;
+    /** The period number, as SPH counts them. */
+    period: number;
+    room: string | null;
+    /** Null when the lesson takes place every week. */
+    rotation: Rotation | null;
+}
+export interface PeriodTime {
+    period: number;
+    /** Local time, e.g. "08:00". */
+    start: string | null;
+    end: string | null;
+}
+export interface Week {
+    /** The portal's value, e.g. "25_08_2025". */
+    id: string;
+    /** ISO calendar dates. */
+    start: string;
+    end: string;
+}
+export interface Timetable {
+    /** The timetable database, e.g. "musterschule_stundenplan_1". */
+    database: string;
+    /** The week shown; null for the general plan. */
+    week: Week | null;
+    /** Weeks the portal offers; schools sometimes leave last year's dates here, so prefer rotation. */
+    weeks: Week[];
+    periods: PeriodTime[];
+    courses: KurswahlCourse[];
+    lessons: KurswahlLesson[];
+    /** Local portal time of the last timetable change, e.g. "2026-08-27T12:12:51". */
+    updatedAt: string | null;
+    /** Local portal time of the last course assignment change. */
+    assignedAt: string | null;
+    /** Local portal time of the last exam plan change. */
+    examsUpdatedAt: string | null;
+}

package/dist/kurswahl/types.js

@@ -0,0 +1 @@
+export {};

package/dist/rotation.d.ts

@@ -0,0 +1,2 @@
+/** The A/B week; Schulportal labels it "A-Woche" or "WA-Woche", Kurswahl Online "Woche: A". */
+export type Rotation = 'A' | 'B';

package/dist/rotation.js

@@ -0,0 +1 @@
+export {};

package/dist/state.d.ts

@@ -7,3 +7,5 @@ export interface ConnectionState {
 }
 export declare function writeState({ account, secret, cookies }: ConnectionState): string;
 export declare function readState(text: string): ConnectionState;
+export declare function copyCookie({ name, value, domain, hostOnly, path, secure, expires }: StoredCookie): StoredCookie;
+export declare function isCookie(value: unknown): value is StoredCookie;

package/dist/state.js

@@ -38,15 +38,19 @@ export function readState(text) {
     return {
         account: { schoolId, username },
         secret: key,
-        cookies: cookies.map(({ name, value, domain, hostOnly, path, secure, expires }) => expires === undefined
-            ? { name, value, domain, hostOnly, path, secure }
-            : { name, value, domain, hostOnly, path, secure, expires })
+        cookies: cookies.map(copyCookie)
     };
 }
+// Only the known fields, so stray keys in stored state never reach the jar.
+export function copyCookie({ name, value, domain, hostOnly, path, secure, expires }) {
+    return expires === undefined
+        ? { name, value, domain, hostOnly, path, secure }
+        : { name, value, domain, hostOnly, path, secure, expires };
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function isCookie(value) {
+export function isCookie(value) {
     return (isRecord(value) &&
         typeof value.name === 'string' &&
         typeof value.value === 'string' &&

package/dist/transport/cookies.js

@@ -25,6 +25,7 @@ export class CookieJar {
             secure: false
         };
         let maxAge;
+        let pathSet = false;
         for (const attribute of attributes) {
             const index = attribute.indexOf('=');
             const key = (index < 0 ? attribute : attribute.slice(0, index)).trim().toLowerCase();
@@ -36,8 +37,10 @@ export class CookieJar {
                 cookie.domain = domain;
                 cookie.hostOnly = false;
             }
-            else if (key === 'path' && value.startsWith('/'))
+            else if (key === 'path' && value.startsWith('/')) {
                 cookie.path = value;
+                pathSet = true;
+            }
             else if (key === 'secure')
                 cookie.secure = true;
             else if (key === 'max-age' && /^-?\d+$/.test(value))
@@ -50,6 +53,8 @@ export class CookieJar {
         }
         if (maxAge !== undefined)
             cookie.expires = this.now() + maxAge * 1000;
+        if (!prefixAllows(cookie, url, pathSet))
+            return;
         const key = `${cookie.domain};${cookie.path};${cookie.name}`;
         if (cookie.expires !== undefined && cookie.expires <= this.now())
             this.cookies.delete(key);
@@ -90,6 +95,15 @@ export class CookieJar {
             .sort((a, b) => b.path.length - a.path.length);
     }
 }
+// RFC 6265bis §4.1.3: __Secure- needs Secure over https; __Host- also needs no Domain and an explicit Path=/.
+function prefixAllows(cookie, url, pathSet) {
+    const name = cookie.name.toLowerCase();
+    const secure = cookie.secure && url.protocol === 'https:';
+    if (name.startsWith('__host-')) {
+        return secure && cookie.hostOnly && pathSet && cookie.path === '/';
+    }
+    return !name.startsWith('__secure-') || secure;
+}
 function domainMatches(host, domain) {
     return host === domain || host.endsWith(`.${domain}`);
 }