@nbtca/prompt 1.3.2 → 1.4.1

package/dist/auth/cookie-transport.js

@@ -0,0 +1,222 @@
+import makeFetchCookie from 'fetch-cookie';
+import { CookieJar } from 'tough-cookie';
+import { AuthError, SessionExpiredError } from './errors.js';
+const WEBVPN_HOST = 'webvpn.nbt.edu.cn';
+const AUTH_HOST = 'authserver-443.webvpn.nbt.edu.cn';
+export const JWXT_HOST = 'jwxt-443.webvpn.nbt.edu.cn';
+const WEBVPN_PATHS = new Set([
+    '/',
+    '/users/sign_in',
+    '/users/auth/cas',
+    '/users/auth/cas/callback',
+    '/vpn_key/update',
+]);
+const AUTH_PATHS = new Set([
+    '/authserver/login',
+    '/authserver/checkNeedCaptcha.htl',
+]);
+const JWXT_EXACT_PATHS = new Set([
+    '/sso/jziotlogin',
+    '/jwglxt/ticketlogin',
+    '/jwglxt/xtgl/login_slogin.html',
+    '/jwglxt/xtgl/index_initMenu.html',
+    '/jwglxt/kbcx/xskbcx_cxXskbcxIndex.html',
+    '/jwglxt/kbcx/xskbcx_cxXsgrkb.html',
+    '/jwglxt/kbcx/xskbcx_cxRjc.html',
+]);
+function isAllowedJwxtPath(pathname) {
+    return JWXT_EXACT_PATHS.has(pathname);
+}
+function assertAllowedVpnOrigin(value) {
+    let nested;
+    try {
+        nested = new URL(value);
+    }
+    catch {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service returned an untrusted redirect.');
+    }
+    if (nested.protocol !== 'https:'
+        || (nested.port !== '' && nested.port !== '443')
+        || nested.username !== ''
+        || nested.password !== '') {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service returned an untrusted redirect.');
+    }
+    const host = nested.hostname.toLowerCase();
+    const allowed = (host === JWXT_HOST && isAllowedJwxtPath(nested.pathname)) || (host === AUTH_HOST && nested.pathname === '/authserver/login') || (host === WEBVPN_HOST && [
+        '/',
+        '/users/sign_in',
+        '/users/auth/cas',
+        '/users/auth/cas/callback',
+    ].includes(nested.pathname));
+    if (!allowed) {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service returned an untrusted redirect.');
+    }
+}
+function assertAllowedCasService(value) {
+    let service;
+    try {
+        service = new URL(value);
+    }
+    catch {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service returned an untrusted redirect.');
+    }
+    const allowed = service.protocol === 'https:'
+        && (service.port === '' || service.port === '443')
+        && service.username === ''
+        && service.password === ''
+        && ((service.hostname.toLowerCase() === WEBVPN_HOST
+            && service.pathname === '/users/auth/cas/callback') || (service.hostname.toLowerCase() === JWXT_HOST
+            && service.pathname === '/sso/jziotlogin'));
+    if (!allowed) {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service returned an untrusted redirect.');
+    }
+}
+export function assertAllowedCampusUrl(url) {
+    const hostname = url.hostname.toLowerCase();
+    if (url.protocol !== 'https:'
+        || (url.port !== '' && url.port !== '443')
+        || url.username !== ''
+        || url.password !== '') {
+        throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service URL is not allowed.');
+    }
+    if (hostname === WEBVPN_HOST && WEBVPN_PATHS.has(url.pathname)) {
+        if (url.pathname === '/vpn_key/update') {
+            const origin = url.searchParams.get('origin');
+            // The post-CAS callback currently uses this route without `origin`;
+            // unauthenticated JWXT redirects include one and are validated below.
+            if (origin)
+                assertAllowedVpnOrigin(origin);
+        }
+        return;
+    }
+    if (hostname === AUTH_HOST && AUTH_PATHS.has(url.pathname)) {
+        const service = url.searchParams.get('service');
+        if (service)
+            assertAllowedCasService(service);
+        return;
+    }
+    if (hostname === JWXT_HOST && isAllowedJwxtPath(url.pathname))
+        return;
+    throw new AuthError('UNTRUSTED_URL', 'session', 'The campus service URL is not allowed.');
+}
+function safeHeaders(headers) {
+    const result = new Headers(headers);
+    for (const forbidden of ['authorization', 'cookie', 'host']) {
+        if (result.has(forbidden)) {
+            throw new AuthError('UNTRUSTED_URL', 'session', 'Caller-supplied authentication headers are not allowed.');
+        }
+    }
+    return Object.fromEntries(result.entries());
+}
+function abortSignal(signal, timeoutMs) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    const onAbort = () => controller.abort(signal?.reason);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted)
+        onAbort();
+    const timer = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        cleanup() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        },
+        timedOut: () => didTimeout,
+    };
+}
+function safeFetchError(error, stage, didTimeout) {
+    if (error instanceof AuthError)
+        return error;
+    if (didTimeout)
+        return new AuthError('TIMEOUT', stage, 'The campus service request timed out.', { retryable: true });
+    if (typeof error === 'object' && error !== null && Reflect.get(error, 'name') === 'AbortError') {
+        return new DOMException('The campus service request was aborted.', 'AbortError');
+    }
+    return new AuthError('NETWORK', stage, 'The campus service request failed.', { retryable: true });
+}
+export function createCampusCookieSession(options = {}) {
+    // Tough Cookie's secure defaults reject public suffixes and use strict
+    // parsing while tolerating legacy prefix mistakes. The campus WebVPN relies
+    // on its default special-domain handling during the CAS callback.
+    const jar = options.jar ?? new CookieJar();
+    const baseFetch = options.baseFetch ?? globalThis.fetch;
+    const guardedFetch = async (input, init) => {
+        const url = new URL(input instanceof Request ? input.url : input.toString());
+        assertAllowedCampusUrl(url);
+        // Caller headers were checked before fetch-cookie received them. A Cookie
+        // header at this layer was added by the private jar and is expected.
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        for (const [name, value] of new Headers(init?.headers))
+            headers.set(name, value);
+        if (headers.has('authorization') || headers.has('host')) {
+            throw new AuthError('UNTRUSTED_URL', 'session', 'Authentication headers are not allowed.');
+        }
+        return baseFetch(input, init);
+    };
+    const cookieFetch = makeFetchCookie(guardedFetch, jar, false);
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    async function request(url, init = {}, stage = 'session') {
+        assertAllowedCampusUrl(url);
+        if (init.method && init.method !== 'GET' && init.method !== 'POST') {
+            throw new AuthError('UNTRUSTED_URL', stage, 'Only read and login requests are allowed.');
+        }
+        const controlled = abortSignal(init.signal, timeoutMs);
+        try {
+            return await cookieFetch(url, {
+                ...init,
+                headers: safeHeaders(init.headers),
+                signal: controlled.signal,
+                maxRedirect: 8,
+            });
+        }
+        catch (error) {
+            throw safeFetchError(error, stage, controlled.timedOut());
+        }
+        finally {
+            controlled.cleanup();
+        }
+    }
+    async function timetableTransport(url, init) {
+        if (url.hostname.toLowerCase() !== JWXT_HOST || !isAllowedJwxtPath(url.pathname)) {
+            throw new AuthError('UNTRUSTED_URL', 'session', 'The timetable transport only accepts JWXT routes.');
+        }
+        const response = await request(url, init, 'session');
+        try {
+            const finalUrl = new URL(response.url);
+            if (finalUrl.hostname.toLowerCase() !== JWXT_HOST
+                || finalUrl.pathname.includes('/authserver/login')
+                || finalUrl.pathname.includes('/users/sign_in')
+                || finalUrl.pathname === '/vpn_key/update')
+                throw new SessionExpiredError();
+        }
+        catch (error) {
+            if (error instanceof AuthError)
+                throw error;
+            throw new SessionExpiredError();
+        }
+        if (response.status === 401 || response.status === 403)
+            throw new SessionExpiredError();
+        return response;
+    }
+    return {
+        request,
+        timetableTransport,
+        serialize: () => jar.serialize(),
+        close: () => jar.removeAllCookies(),
+    };
+}
+export async function cookieSessionFromSerialized(serialized, options = {}) {
+    let jar;
+    try {
+        jar = await CookieJar.deserialize(serialized);
+    }
+    catch {
+        throw new SessionExpiredError();
+    }
+    return createCampusCookieSession({ ...options, jar });
+}

package/dist/auth/errors.js

@@ -0,0 +1,18 @@
+export class AuthError extends Error {
+    code;
+    stage;
+    retryable;
+    constructor(code, stage, message, options = {}) {
+        super(message);
+        this.name = 'AuthError';
+        this.code = code;
+        this.stage = stage;
+        this.retryable = options.retryable ?? false;
+    }
+}
+export class SessionExpiredError extends AuthError {
+    constructor() {
+        super('SESSION_EXPIRED', 'session', 'The campus login session has expired.', { retryable: true });
+        this.name = 'SessionExpiredError';
+    }
+}

package/dist/auth/nbt-auth.js

@@ -0,0 +1,239 @@
+import { createCipheriv, randomBytes } from 'node:crypto';
+import { load } from 'cheerio';
+import { AuthError } from './errors.js';
+import { JWXT_HOST, cookieSessionFromSerialized, createCampusCookieSession, } from './cookie-transport.js';
+const WEBVPN_ENTRY = new URL('https://webvpn.nbt.edu.cn/');
+const SSO_ENTRY = new URL(`https://${JWXT_HOST}/sso/jziotlogin`);
+const JWXT_MENU = new URL(`https://${JWXT_HOST}/jwglxt/xtgl/index_initMenu.html`);
+const TIMETABLE_INDEX = new URL(`https://${JWXT_HOST}/jwglxt/kbcx/xskbcx_cxXskbcxIndex.html?gnmkdm=N2151&layout=default`);
+const RANDOM_ALPHABET = 'ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678';
+const MAX_AUTH_HTML_BYTES = 2 * 1024 * 1024;
+const SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+function randomCharacters(length, source) {
+    const bytes = source(length);
+    if (bytes.length < length)
+        throw new AuthError('LOGIN_PAGE_CHANGED', 'credentials', 'Secure login initialization failed.');
+    let result = '';
+    for (let index = 0; index < length; index += 1) {
+        result += RANDOM_ALPHABET[bytes[index] % RANDOM_ALPHABET.length];
+    }
+    return result;
+}
+export function encryptCampusPassword(password, salt, source = randomBytes) {
+    const key = Buffer.from(salt, 'utf8');
+    if (key.length !== 16) {
+        key.fill(0);
+        throw new AuthError('LOGIN_PAGE_CHANGED', 'credentials', 'The campus login page changed unexpectedly.');
+    }
+    const ivText = randomCharacters(16, source);
+    const prefix = randomCharacters(64, source);
+    const iv = Buffer.from(ivText, 'utf8');
+    const plaintext = Buffer.from(prefix + password, 'utf8');
+    try {
+        const cipher = createCipheriv('aes-128-cbc', key, iv);
+        return Buffer.concat([cipher.update(plaintext), cipher.final()]).toString('base64');
+    }
+    finally {
+        key.fill(0);
+        iv.fill(0);
+        plaintext.fill(0);
+    }
+}
+function parseLoginForm(html, responseUrl) {
+    const $ = load(html);
+    const form = $('#pwdFromId');
+    const execution = String(form.find('input[name="execution"], #execution').first().val() ?? '').trim();
+    const salt = String(form.find('#pwdEncryptSalt, input[name="pwdEncryptSalt"]').first().val() ?? '').trim();
+    const actionValue = form.attr('action');
+    if (form.length === 0 || !execution || !salt || !actionValue) {
+        throw new AuthError('LOGIN_PAGE_CHANGED', 'login-page', 'The campus login page changed unexpectedly.');
+    }
+    let current;
+    let action;
+    try {
+        current = new URL(responseUrl);
+        action = new URL(actionValue, current);
+    }
+    catch {
+        throw new AuthError('LOGIN_PAGE_CHANGED', 'login-page', 'The campus login page changed unexpectedly.');
+    }
+    const service = current.searchParams.get('service');
+    if (service && !action.searchParams.has('service'))
+        action.searchParams.set('service', service);
+    return { action, execution, salt };
+}
+function hasLoginFingerprint(html) {
+    return /(?:id=["']pwdFromId["']|id=["']pwdEncryptSalt["']|name=["']execution["'])/i.test(html);
+}
+function classifyRejectedLogin(html) {
+    const $ = load(html);
+    const visibleError = [
+        $('#showErrorTip').text(),
+        $('#showWarnTip').text(),
+        $('#errorMsg').text(),
+        $('.alert-danger').text(),
+    ].join(' ').replace(/\s+/g, ' ').trim();
+    if (/锁定|冻结|次数过多|稍后再试/.test(visibleError)) {
+        return new AuthError('ACCOUNT_LOCKED', 'credentials', 'The campus account is temporarily locked.');
+    }
+    if (/激活|未启用/.test(visibleError)) {
+        return new AuthError('ACCOUNT_INACTIVE', 'credentials', 'The campus account must be activated first.');
+    }
+    if (/验证码|滑块|captcha/i.test(visibleError)) {
+        return new AuthError('INTERACTIVE_CHALLENGE', 'credentials', 'The campus login requires an interactive browser challenge.');
+    }
+    if (/用户名|账号|密码|credential|password/i.test(visibleError)) {
+        return new AuthError('INVALID_CREDENTIALS', 'credentials', 'The student id or password was rejected.');
+    }
+    return new AuthError('UNEXPECTED_RESPONSE', 'credentials', 'Campus login could not be confirmed.');
+}
+async function readText(response, stage) {
+    if (response.status < 200 || response.status >= 300) {
+        throw new AuthError('HTTP_ERROR', stage, 'The campus service returned an error.', { retryable: response.status >= 500 });
+    }
+    const length = Number.parseInt(response.headers.get('content-length') ?? '', 10);
+    if (Number.isFinite(length) && length > MAX_AUTH_HTML_BYTES) {
+        throw new AuthError('UNEXPECTED_RESPONSE', stage, 'The campus service returned an unexpected response.');
+    }
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > MAX_AUTH_HTML_BYTES) {
+        throw new AuthError('UNEXPECTED_RESPONSE', stage, 'The campus service returned an unexpected response.');
+    }
+    return text;
+}
+async function challengeRequired(cookies, loginUrl, username, signal) {
+    const endpoint = new URL('/authserver/checkNeedCaptcha.htl', loginUrl);
+    endpoint.searchParams.set('username', username);
+    const response = await cookies.request(endpoint, {
+        method: 'GET',
+        headers: { Accept: 'application/json', 'X-Requested-With': 'XMLHttpRequest' },
+        signal,
+    }, 'challenge-check');
+    const text = await readText(response, 'challenge-check');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AuthError('LOGIN_PAGE_CHANGED', 'challenge-check', 'The campus challenge response changed unexpectedly.');
+    }
+    if (typeof parsed === 'boolean')
+        return parsed;
+    if (typeof parsed === 'object' && parsed !== null) {
+        const value = Reflect.get(parsed, 'isNeed') ?? Reflect.get(parsed, 'needCaptcha');
+        if (value === true || value === 'true' || value === 1 || value === '1')
+            return true;
+        if (value === false || value === 'false' || value === 0 || value === '0')
+            return false;
+    }
+    throw new AuthError('LOGIN_PAGE_CHANGED', 'challenge-check', 'The campus challenge response changed unexpectedly.');
+}
+function maskAccountId(username) {
+    const characters = [...username];
+    if (characters.length <= 2)
+        return '•'.repeat(characters.length);
+    return `${'•'.repeat(characters.length - 2)}${characters.slice(-2).join('')}`;
+}
+function createAuthenticatedSession(cookies, metadata) {
+    return {
+        accountHint: metadata.accountHint,
+        timetableTransport: (url, init) => cookies.timetableTransport(url, init),
+        async snapshot(validatedAt = new Date()) {
+            const validatedAtText = validatedAt.toISOString();
+            return {
+                version: 1,
+                provider: 'nbt-webvpn',
+                jar: await cookies.serialize(),
+                accountHint: metadata.accountHint,
+                authenticatedAt: metadata.authenticatedAt,
+                validatedAt: validatedAtText,
+                expiresAt: new Date(validatedAt.getTime() + SESSION_MAX_AGE_MS).toISOString(),
+            };
+        },
+        close: () => cookies.close(),
+    };
+}
+async function verifyJwxtSession(cookies, signal) {
+    await readText(await cookies.request(SSO_ENTRY, { method: 'GET', signal }, 'sso'), 'sso');
+    await readText(await cookies.request(JWXT_MENU, { method: 'GET', signal }, 'sso'), 'sso');
+    const response = await cookies.request(TIMETABLE_INDEX, { method: 'GET', signal }, 'sso');
+    const html = await readText(response, 'sso');
+    let finalUrl;
+    try {
+        finalUrl = new URL(response.url);
+    }
+    catch {
+        throw new AuthError('UNEXPECTED_RESPONSE', 'sso', 'Campus login could not be confirmed.');
+    }
+    if (finalUrl.hostname.toLowerCase() !== JWXT_HOST
+        || hasLoginFingerprint(html)
+        || !/<select\b[^>]*(?:id|name)=["']xnm["']/i.test(html)
+        || !/<select\b[^>]*(?:id|name)=["']xqm["']/i.test(html)) {
+        throw new AuthError('UNEXPECTED_RESPONSE', 'sso', 'Campus login could not be confirmed.');
+    }
+}
+export async function loginWithStudentPassword(username, password, options = {}) {
+    if (!username.trim() || !password) {
+        throw new AuthError('INVALID_CREDENTIALS', 'credentials', 'Student id and password are required.');
+    }
+    const normalizedUsername = username.trim();
+    const cookies = createCampusCookieSession(options);
+    try {
+        const loginResponse = await cookies.request(WEBVPN_ENTRY, {
+            method: 'GET',
+            headers: {
+                Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+            },
+            signal: options.signal,
+        }, 'login-page');
+        const loginHtml = await readText(loginResponse, 'login-page');
+        const form = parseLoginForm(loginHtml, loginResponse.url);
+        if (await challengeRequired(cookies, form.action, normalizedUsername, options.signal)) {
+            throw new AuthError('INTERACTIVE_CHALLENGE', 'challenge-check', 'The campus login requires an interactive browser challenge.');
+        }
+        const encryptedPassword = encryptCampusPassword(password, form.salt, options.randomBytes ?? randomBytes);
+        const body = new URLSearchParams({
+            username: normalizedUsername,
+            password: encryptedPassword,
+            _eventId: 'submit',
+            cllt: 'userNameLogin',
+            dllt: 'generalLogin',
+            execution: form.execution,
+        });
+        const credentialResponse = await cookies.request(form.action, {
+            method: 'POST',
+            headers: {
+                Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Referer: loginResponse.url,
+            },
+            body: body.toString(),
+            signal: options.signal,
+        }, 'credentials');
+        const credentialHtml = await readText(credentialResponse, 'credentials');
+        if (hasLoginFingerprint(credentialHtml))
+            throw classifyRejectedLogin(credentialHtml);
+        await verifyJwxtSession(cookies, options.signal);
+        const authenticatedAt = (options.now ?? (() => new Date()))().toISOString();
+        return createAuthenticatedSession(cookies, {
+            accountHint: maskAccountId(normalizedUsername),
+            authenticatedAt,
+        });
+    }
+    catch (error) {
+        await cookies.close();
+        if (error instanceof AuthError)
+            throw error;
+        if (typeof error === 'object' && error !== null && Reflect.get(error, 'name') === 'AbortError')
+            throw error;
+        throw new AuthError('NETWORK', 'credentials', 'The campus login request failed.', { retryable: true });
+    }
+}
+export async function restoreNbtSession(persisted, options = {}) {
+    const cookies = await cookieSessionFromSerialized(persisted.jar, options);
+    return createAuthenticatedSession(cookies, {
+        accountHint: persisted.accountHint,
+        authenticatedAt: persisted.authenticatedAt,
+    });
+}

package/dist/auth/session-store.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getStateDir, getWritableStateDir } from '../config/paths.js';
+export const SESSION_SCHEMA_VERSION = 1;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isIsoDate(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isSerializedJar(value) {
+    return isRecord(value) && Array.isArray(value['cookies']);
+}
+function parseSession(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['version'] !== SESSION_SCHEMA_VERSION || value['provider'] !== 'nbt-webvpn')
+        return null;
+    if (!isSerializedJar(value['jar']))
+        return null;
+    if (!isIsoDate(value['authenticatedAt']) || !isIsoDate(value['validatedAt']))
+        return null;
+    if (value['expiresAt'] !== undefined && !isIsoDate(value['expiresAt']))
+        return null;
+    if (value['accountHint'] !== undefined
+        && (typeof value['accountHint'] !== 'string'
+            || value['accountHint'].length > 64
+            || /[\u0000-\u001f\u007f]/.test(value['accountHint'])))
+        return null;
+    return {
+        version: SESSION_SCHEMA_VERSION,
+        provider: 'nbt-webvpn',
+        jar: value['jar'],
+        accountHint: value['accountHint'],
+        authenticatedAt: value['authenticatedAt'],
+        validatedAt: value['validatedAt'],
+        expiresAt: value['expiresAt'],
+    };
+}
+function removeFile(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch (error) {
+        if (!isRecord(error) || error['code'] !== 'ENOENT')
+            throw error;
+    }
+}
+function clearTemporaryFiles(filePath) {
+    const directory = path.dirname(filePath);
+    const prefix = `${path.basename(filePath)}.`;
+    try {
+        for (const entry of fs.readdirSync(directory)) {
+            if (entry.startsWith(prefix) && entry.endsWith('.tmp'))
+                removeFile(path.join(directory, entry));
+        }
+    }
+    catch (error) {
+        if (!isRecord(error) || error['code'] !== 'ENOENT')
+            throw error;
+    }
+}
+export function createSessionStore(options = {}) {
+    const now = options.now ?? (() => new Date());
+    const filePath = options.filePath ?? path.join(getStateDir(), 'session.json');
+    function clear() {
+        removeFile(filePath);
+        clearTemporaryFiles(filePath);
+    }
+    function load() {
+        try {
+            const parsed = parseSession(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+            if (!parsed || (parsed.expiresAt && Date.parse(parsed.expiresAt) <= now().getTime())) {
+                clear();
+                return null;
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (isRecord(error) && error['code'] === 'ENOENT')
+                return null;
+            clear();
+            return null;
+        }
+    }
+    function save(session) {
+        const validated = parseSession(session);
+        if (!validated)
+            throw new TypeError('Invalid persisted session.');
+        const directory = options.filePath ? path.dirname(filePath) : getWritableStateDir();
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        try {
+            fs.chmodSync(directory, 0o700);
+        }
+        catch { /* Best effort on non-POSIX filesystems. */ }
+        const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            fs.writeFileSync(temporaryPath, `${JSON.stringify(validated)}\n`, {
+                encoding: 'utf8',
+                flag: 'wx',
+                mode: 0o600,
+            });
+            fs.renameSync(temporaryPath, filePath);
+            try {
+                fs.chmodSync(filePath, 0o600);
+            }
+            catch { /* Best effort on non-POSIX filesystems. */ }
+        }
+        finally {
+            try {
+                removeFile(temporaryPath);
+            }
+            catch { /* The main write result is authoritative. */ }
+        }
+    }
+    return { filePath, load, save, clear };
+}

package/dist/config/paths.js

@@ -1,13 +1,24 @@
 import { existsSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { isAbsolute, join } from 'path';
+function absoluteEnvPath(name, fallback) {
+    const value = process.env[name];
+    return value && isAbsolute(value) ? value : fallback;
+}
 function getXdgConfigDir() {
-    const xdgHome = process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config');
+    const xdgHome = absoluteEnvPath('XDG_CONFIG_HOME', join(homedir(), '.config'));
     return join(xdgHome, 'nbtca');
 }
 function getLegacyConfigDir() {
     return join(homedir(), '.nbtca');
 }
+function getDefaultStateDir() {
+    if (process.platform === 'win32' && process.env['LOCALAPPDATA']) {
+        return join(process.env['LOCALAPPDATA'], 'nbtca');
+    }
+    const xdgHome = absoluteEnvPath('XDG_STATE_HOME', join(homedir(), '.local', 'state'));
+    return join(xdgHome, 'nbtca');
+}
 export function getConfigDir() {
     const xdgDir = getXdgConfigDir();
     if (existsSync(xdgDir))
@@ -22,3 +33,12 @@ export function getWritableConfigDir() {
     mkdirSync(dir, { recursive: true });
     return dir;
 }
+/** User-level runtime state shared by npx, local and global installations. */
+export function getStateDir() {
+    return getDefaultStateDir();
+}
+export function getWritableStateDir() {
+    const dir = getDefaultStateDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}

package/dist/core/canvas.js

@@ -0,0 +1,23 @@
+const CSI = '\x1b[';
+export const ansi = {
+    hideCursor: `${CSI}?25l`,
+    showCursor: `${CSI}?25h`,
+    eraseDown: `${CSI}0J`,
+    cursorToCol0: '\r',
+    cursorUp: (n) => (n > 0 ? `${CSI}${n}A` : ''),
+    enterAlt: `${CSI}?1049h`,
+    leaveAlt: `${CSI}?1049l`,
+    home: `${CSI}H`,
+    clearAll: `${CSI}2J`,
+};
+let registered = false;
+export function ensureCursorRestored() {
+    if (registered)
+        return;
+    registered = true;
+    const restore = () => {
+        if (process.stdout.isTTY)
+            process.stdout.write(ansi.showCursor);
+    };
+    process.on('exit', restore);
+}