@wilm-ai/wilma-cli 1.6.2 → 2.0.0

package/dist/config.js

@@ -1,4 +1,5 @@
-import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, stat, writeFile, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
 import { dirname, resolve } from "node:path";
 import { homedir } from "node:os";
 const SALT = "wilmai::";
@@ -13,38 +14,76 @@ export function getConfigPath() {
 }
 export async function loadConfig() {
     const path = getConfigPath();
+    let raw;
     try {
-        const raw = await readFile(path, "utf-8");
-        const data = JSON.parse(raw);
-        if (!data.profiles) {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
             return { profiles: [] };
-        }
-        // Backward-compat: migrate single-student fields if present
-        data.profiles = data.profiles.map((p) => {
-            if (!p.students && p.studentNumber) {
-                p.students = [{ studentNumber: p.studentNumber, name: p.studentName ?? p.studentNumber }];
-            }
-            if (!p.lastStudentNumber && p.studentNumber) {
-                p.lastStudentNumber = p.studentNumber;
-                p.lastStudentName = p.studentName ?? p.studentNumber;
-            }
-            if (!p.tenantName) {
-                p.tenantName = p.tenantUrl;
-            }
-            delete p.studentNumber;
-            delete p.studentName;
-            return p;
-        });
-        return data;
+        throw err;
     }
-    catch {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        // Treating a damaged file as empty would overwrite every saved login on the next save.
+        throw new Error(`The WilmAI config at ${path} isn't valid JSON (${err.message}). ` +
+            "Fix the file, or remove it with `wilma config clear` and log in again.");
+    }
+    await tightenPermissions(path);
+    if (!data || !Array.isArray(data.profiles)) {
         return { profiles: [] };
     }
+    // Backward-compat: migrate single-student fields if present
+    data.profiles = data.profiles.map((p) => {
+        if (!p.students && p.studentNumber) {
+            p.students = [{ studentNumber: p.studentNumber, name: p.studentName ?? p.studentNumber }];
+        }
+        if (!p.lastStudentNumber && p.studentNumber) {
+            p.lastStudentNumber = p.studentNumber;
+            p.lastStudentName = p.studentName ?? p.studentNumber;
+        }
+        if (!p.tenantName) {
+            p.tenantName = p.tenantUrl;
+        }
+        delete p.studentNumber;
+        delete p.studentName;
+        return p;
+    });
+    return data;
+}
+/**
+ * The config holds Wilma passwords (encoded, not encrypted), so it should be
+ * readable by this user only. Older versions could leave the folder or file
+ * open to other users of the computer; fix that when found.
+ */
+async function tightenPermissions(path) {
+    if (process.platform === "win32")
+        return;
+    const tighten = async (target, mode) => {
+        try {
+            if (((await stat(target)).mode & 0o077) !== 0)
+                await chmod(target, mode);
+        }
+        catch {
+            // Missing, or not ours to fix (owned by another user): leave it.
+        }
+    };
+    await tighten(path, 0o600);
+    // Only the default folder: a custom WILMAI_CONFIG_PATH may live in a shared folder.
+    if (!process.env.WILMAI_CONFIG_PATH)
+        await tighten(dirname(path), 0o700);
 }
 export async function saveConfig(config) {
     const path = getConfigPath();
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    await writeFile(path, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    await tightenPermissions(path);
+    // Write to a temp file and rename, so a concurrent reader never sees a half-written file.
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tmp, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    await rename(tmp, path);
 }
 export async function clearConfig() {
     const path = getConfigPath();

package/dist/credentials.d.ts

@@ -0,0 +1,69 @@
+import { WilmaClient, type MfaCallback, type StudentInfo, type WilmaProfile } from "@wilm-ai/wilma-client";
+import { type CliConfig, type StoredProfile } from "./config.js";
+/**
+ * Environment variables for agents that keep secrets in their own store
+ * (cloud VMs, CI-like sandboxes) instead of a config file.
+ */
+export declare const ENV_VARS: {
+    readonly tenant: "WILMA_TENANT";
+    readonly username: "WILMA_USERNAME";
+    readonly password: "WILMA_PASSWORD";
+    readonly totpSecret: "WILMA_TOTP_SECRET";
+};
+export interface ActiveAccount {
+    profile: WilmaProfile;
+    totpSecret?: string;
+    /** Present when the account comes from the saved config. */
+    stored?: StoredProfile;
+    source: "config" | "env";
+}
+export declare class TotpSecretRequiredError extends Error {
+    constructor();
+}
+export declare class TotpSecretInvalidError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Answers Wilma's two-step challenge from the saved authenticator key. If
+ * Wilma rejects a code and asks again for the same challenge (a code is
+ * usually rejected because it was already used — logins less than 30 seconds
+ * apart share one), it waits for the next 30-second window and gives a fresh
+ * code. No delay unless Wilma actually refuses.
+ */
+export declare function mfaCallbackFor(totpSecret?: string | null, clock?: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}): MfaCallback | undefined;
+/** Environment variables win over the saved config when all three are set. */
+export declare function resolveAccount(config: CliConfig, env?: NodeJS.ProcessEnv): Promise<ActiveAccount | null>;
+/**
+ * Every Wilma login the family has. Environment variables give exactly one;
+ * otherwise all saved logins, the active one first. Families with children on
+ * different Wilmas (e.g. a city school and a private school) save one login each.
+ */
+export declare function resolveAccounts(config: CliConfig, env?: NodeJS.ProcessEnv): Promise<ActiveAccount[]>;
+/**
+ * Log in once and return the logged-in client with the account's students.
+ * Throws TotpSecretRequiredError for MFA accounts without a key.
+ */
+export declare function verifyLoginSession(input: {
+    tenantUrl: string;
+    username: string;
+    password: string;
+    totpSecret?: string | null;
+}): Promise<{
+    client: WilmaClient;
+    students: StudentInfo[];
+}>;
+/** Save a verified login as the active profile, replacing any profile with the same tenant and username. */
+export declare function saveLogin(config: CliConfig, input: {
+    tenantUrl: string;
+    tenantName?: string | null;
+    username: string;
+    password: string;
+    totpSecret?: string | null;
+    students: StudentInfo[];
+}): Promise<StoredProfile>;
+/** The client reports a rejected one-time code as an AuthenticationError starting "MFA verification failed". */
+export declare function isMfaFailure(err: unknown): boolean;
+export { AuthenticationError } from "@wilm-ai/wilma-client";

package/dist/credentials.js

@@ -0,0 +1,195 @@
+import { AuthenticationError, MfaRequiredError, WilmaClient, } from "@wilm-ai/wilma-client";
+import { obfuscateSecret, revealSecret, saveConfig, } from "./config.js";
+import { generateTOTP, parseTotpSecret, TOTP_PERIOD_MS, totpCounter } from "./totp.js";
+import { normalizeTenantUrl, resolveTenant } from "./tenant-search.js";
+/**
+ * Environment variables for agents that keep secrets in their own store
+ * (cloud VMs, CI-like sandboxes) instead of a config file.
+ */
+export const ENV_VARS = {
+    tenant: "WILMA_TENANT",
+    username: "WILMA_USERNAME",
+    password: "WILMA_PASSWORD",
+    totpSecret: "WILMA_TOTP_SECRET",
+};
+export class TotpSecretRequiredError extends Error {
+    constructor() {
+        super("This Wilma account uses two-step verification. Provide the authenticator setup key (base32 key or otpauth:// link) so logins can run unattended.");
+    }
+}
+export class TotpSecretInvalidError extends Error {
+    constructor(message = "Wilma didn't accept the two-step verification code. Check the authenticator setup key.") {
+        super(message);
+    }
+}
+/** Reject obvious mistakes, like a 6-digit one-time code pasted where the setup key belongs. */
+function checkTotpSecret(raw) {
+    const value = raw.trim();
+    if (/^\d{6,8}$/.test(value)) {
+        throw new TotpSecretInvalidError("That looks like a one-time code. Paste the authenticator setup key instead (a long base32 key or an otpauth:// link).");
+    }
+    try {
+        const secret = parseTotpSecret(value);
+        if (secret.replace(/=+$/, "").length < 16)
+            throw new Error("too short");
+        generateTOTP(secret);
+    }
+    catch {
+        throw new TotpSecretInvalidError("That doesn't look like an authenticator setup key (a base32 key or an otpauth:// link).");
+    }
+}
+/**
+ * Answers Wilma's two-step challenge from the saved authenticator key. If
+ * Wilma rejects a code and asks again for the same challenge (a code is
+ * usually rejected because it was already used — logins less than 30 seconds
+ * apart share one), it waits for the next 30-second window and gives a fresh
+ * code. No delay unless Wilma actually refuses.
+ */
+export function mfaCallbackFor(totpSecret, clock = {
+    now: Date.now,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+    if (!totpSecret)
+        return undefined;
+    const secret = parseTotpSecret(totpSecret);
+    const usedFor = new Map(); // challenge (formkey) -> time step of the code given
+    return async (formkey) => {
+        let counter = totpCounter(clock.now());
+        const previous = usedFor.get(formkey);
+        if (previous !== undefined && previous >= counter) {
+            await clock.sleep((previous + 1) * TOTP_PERIOD_MS - clock.now() + 50);
+            counter = previous + 1;
+        }
+        usedFor.set(formkey, counter);
+        return generateTOTP(secret, counter * TOTP_PERIOD_MS);
+    };
+}
+function hasEnvAccount(env = process.env) {
+    return Boolean(env[ENV_VARS.tenant] && env[ENV_VARS.username] && env[ENV_VARS.password]);
+}
+/** Environment variables win over the saved config when all three are set. */
+export async function resolveAccount(config, env = process.env) {
+    if (hasEnvAccount(env)) {
+        const tenant = await resolveTenant(env[ENV_VARS.tenant]);
+        return {
+            profile: {
+                baseUrl: tenant.url,
+                username: env[ENV_VARS.username],
+                password: env[ENV_VARS.password],
+            },
+            totpSecret: env[ENV_VARS.totpSecret] || undefined,
+            source: "env",
+        };
+    }
+    const stored = config.profiles.find((p) => p.id === config.lastProfileId);
+    if (!stored)
+        return null;
+    const password = revealSecret(stored.passwordObfuscated);
+    if (!password) {
+        throw new Error("Stored password could not be decoded. Run `wilma login` again.");
+    }
+    return {
+        profile: {
+            baseUrl: stored.tenantUrl,
+            username: stored.username,
+            password,
+            studentNumber: stored.lastStudentNumber ?? undefined,
+        },
+        totpSecret: stored.totpSecretObfuscated ? revealSecret(stored.totpSecretObfuscated) ?? undefined : undefined,
+        stored,
+        source: "config",
+    };
+}
+/**
+ * Every Wilma login the family has. Environment variables give exactly one;
+ * otherwise all saved logins, the active one first. Families with children on
+ * different Wilmas (e.g. a city school and a private school) save one login each.
+ */
+export async function resolveAccounts(config, env = process.env) {
+    if (hasEnvAccount(env)) {
+        const account = await resolveAccount(config, env);
+        return account ? [account] : [];
+    }
+    const ordered = [...config.profiles].sort((a, b) => Number(b.id === config.lastProfileId) - Number(a.id === config.lastProfileId));
+    const accounts = [];
+    const seen = new Set();
+    for (const stored of ordered) {
+        // One session per Wilma account, even if an older config saved it twice in different case.
+        const key = `${normalizeTenantUrl(stored.tenantUrl)}|${stored.username.toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const password = revealSecret(stored.passwordObfuscated);
+        if (!password)
+            continue;
+        accounts.push({
+            profile: {
+                baseUrl: stored.tenantUrl,
+                username: stored.username,
+                password,
+                studentNumber: stored.lastStudentNumber ?? undefined,
+            },
+            totpSecret: stored.totpSecretObfuscated ? revealSecret(stored.totpSecretObfuscated) ?? undefined : undefined,
+            stored,
+            source: "config",
+        });
+    }
+    return accounts;
+}
+/**
+ * Log in once and return the logged-in client with the account's students.
+ * Throws TotpSecretRequiredError for MFA accounts without a key.
+ */
+export async function verifyLoginSession(input) {
+    if (input.totpSecret)
+        checkTotpSecret(input.totpSecret);
+    try {
+        const client = await WilmaClient.login({ baseUrl: normalizeTenantUrl(input.tenantUrl), username: input.username, password: input.password, studentNumber: null }, mfaCallbackFor(input.totpSecret));
+        return { client, students: await client.students() };
+    }
+    catch (err) {
+        if (err instanceof MfaRequiredError)
+            throw new TotpSecretRequiredError();
+        if (isMfaFailure(err))
+            throw new TotpSecretInvalidError();
+        throw err;
+    }
+}
+/** Save a verified login as the active profile, replacing any profile with the same tenant and username. */
+export async function saveLogin(config, input) {
+    const tenantUrl = normalizeTenantUrl(input.tenantUrl);
+    // Wilma usernames are case-insensitive: "Matti.M" and "matti.m" are one account
+    // (saving it twice would make two sessions that keep cancelling each other).
+    const sameAccount = (p) => normalizeTenantUrl(p.tenantUrl) === tenantUrl && p.username.toLowerCase() === input.username.toLowerCase();
+    const previous = config.profiles.find(sameAccount);
+    const id = previous?.id ?? `${tenantUrl}|${input.username}`;
+    const keepLast = previous?.lastStudentNumber
+        ? input.students.find((s) => s.studentNumber === previous.lastStudentNumber)
+        : undefined;
+    const lastStudent = keepLast ?? input.students[0];
+    const stored = {
+        id,
+        tenantUrl,
+        tenantName: input.tenantName ?? previous?.tenantName ?? tenantUrl,
+        username: input.username,
+        passwordObfuscated: obfuscateSecret(input.password),
+        totpSecretObfuscated: input.totpSecret ? obfuscateSecret(input.totpSecret.trim()) : previous?.totpSecretObfuscated ?? null,
+        students: input.students.map((s) => ({ studentNumber: s.studentNumber, name: s.name })),
+        lastStudentNumber: lastStudent?.studentNumber ?? null,
+        lastStudentName: lastStudent?.name ?? null,
+        lastUsedAt: new Date().toISOString(),
+    };
+    // Logging in again keeps the login's place in the list (`wilma accounts` numbers stay put).
+    const at = config.profiles.findIndex(sameAccount);
+    const others = config.profiles.filter((p) => !sameAccount(p));
+    config.profiles = at === -1 ? [...others, stored] : [...others.slice(0, at), stored, ...others.slice(at)];
+    config.lastProfileId = id;
+    await saveConfig(config);
+    return stored;
+}
+/** The client reports a rejected one-time code as an AuthenticationError starting "MFA verification failed". */
+export function isMfaFailure(err) {
+    return err instanceof AuthenticationError && /^MFA verification failed/.test(err.message);
+}
+// Re-exported so other hosts use the same client classes the CLI does.
+export { AuthenticationError } from "@wilm-ai/wilma-client";

package/dist/downloads.d.ts

@@ -0,0 +1,23 @@
+import type { NewsResource } from "@wilm-ai/wilma-client";
+export declare function normalizeResourceId(raw: string | undefined): string | undefined;
+export declare function fileNameFromResponse(resource: NewsResource, contentDisposition: string | null, contentType: string | null): string;
+/**
+ * A file name that is safe to create in the download folder on any OS: no
+ * path separators or reserved characters, no control or text-direction
+ * characters (which can disguise an extension), no leading dot (hidden files,
+ * ".npmrc"-style config), and none of Windows' reserved device names.
+ */
+export declare function sanitizeFileName(value: string): string;
+export declare function createUniqueDownloadFile(directory: string, preferredName: string): Promise<{
+    path: string;
+    handle: import("fs/promises").FileHandle;
+}>;
+/** Read a fetched resource into memory, enforcing the same 50 MB cap as CLI downloads. */
+export declare function readResponseCapped(response: {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    body: ReadableStream<Uint8Array> | null;
+}): Promise<Buffer>;

package/dist/downloads.js

@@ -0,0 +1,105 @@
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+const MAX_NEWS_RESOURCE_BYTES = 50 * 1024 * 1024;
+export function normalizeResourceId(raw) {
+    if (!raw)
+        return undefined;
+    return /^\d+$/.test(raw) ? `resource-${raw}` : raw;
+}
+export function fileNameFromResponse(resource, contentDisposition, contentType) {
+    const encoded = /filename\*=UTF-8''([^;]+)/i.exec(contentDisposition ?? "")?.[1];
+    const quoted = /filename="([^"]+)"/i.exec(contentDisposition ?? "")?.[1];
+    const plain = /filename=([^;]+)/i.exec(contentDisposition ?? "")?.[1]?.trim();
+    let name = encoded ? decodeURIComponentSafely(encoded) : quoted ?? plain ?? resource.fileName ?? resource.label;
+    name = sanitizeFileName(name) || "wilma-resource";
+    if (!/\.[A-Za-z0-9]{1,8}$/.test(name)) {
+        const extension = extensionForContentType(contentType);
+        if (extension)
+            name += extension;
+    }
+    return name;
+}
+/**
+ * A file name that is safe to create in the download folder on any OS: no
+ * path separators or reserved characters, no control or text-direction
+ * characters (which can disguise an extension), no leading dot (hidden files,
+ * ".npmrc"-style config), and none of Windows' reserved device names.
+ */
+export function sanitizeFileName(value) {
+    let name = value
+        .replace(/[\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, "")
+        .replace(/[\\/:*?"<>|\u0000-\u001f\u007f-\u009f]/g, "_");
+    // Trim spaces and dots together until stable: " .npmrc" -> "npmrc".
+    name = name.replace(/^[\s.]+|[\s.]+$/g, "");
+    if (/^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(name))
+        name = `_${name}`;
+    return name.slice(0, 180).replace(/[\s.]+$/g, "");
+}
+function extensionForContentType(contentType) {
+    const extensions = {
+        "application/pdf": ".pdf",
+        "application/zip": ".zip",
+        "image/jpeg": ".jpg",
+        "image/png": ".png",
+        "text/plain": ".txt",
+        "text/csv": ".csv",
+    };
+    return contentType ? extensions[contentType] ?? "" : "";
+}
+function decodeURIComponentSafely(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+export async function createUniqueDownloadFile(directory, preferredName) {
+    const dot = preferredName.lastIndexOf(".");
+    const hasExtension = dot > 0;
+    const stem = hasExtension ? preferredName.slice(0, dot) : preferredName;
+    const extension = hasExtension ? preferredName.slice(dot) : "";
+    for (let index = 0; index < 1000; index += 1) {
+        const candidate = index === 0 ? preferredName : `${stem}-${index}${extension}`;
+        const path = resolve(directory, candidate);
+        try {
+            const handle = await open(path, "wx", 0o600);
+            return { path, handle };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    throw new Error("Could not choose a unique output filename");
+}
+/** Read a fetched resource into memory, enforcing the same 50 MB cap as CLI downloads. */
+export async function readResponseCapped(response) {
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`News resource download failed with HTTP ${response.status}`);
+    }
+    const declaredLength = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_NEWS_RESOURCE_BYTES) {
+        await response.body?.cancel();
+        throw new Error("News resource exceeds the 50 MB download limit");
+    }
+    if (!response.body)
+        throw new Error("News resource response had no body");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > MAX_NEWS_RESOURCE_BYTES) {
+            await reader.cancel();
+            throw new Error("News resource exceeds the 50 MB download limit");
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}