handmux 0.23.0 → 0.25.0

package/{src → dist/src}/appName.js

@@ -1,23 +1,22 @@
 // Runtime app-name injection. The web bundle ships prebuilt, so a user's custom name (set at
 // `handmux start --name`) can't be baked at build time — instead the server rewrites the name into
 // the shell HTML and the PWA manifest as it serves them. Pure string/object transforms so they're
-// unit-testable; the server side-effects (read file / send) live in server.js.
-
-const escAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
-  .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
+// unit-testable; the server side-effects (read file / send) live in server.ts.
+const escAttr = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 // Replace the browser-tab title and the iOS home-screen label in index.html. Matches by tag/attr,
 // not by the default text, so it survives a changed default. No-op when a tag is absent.
 export function applyAppName(html, name) {
-  if (!name) return html;
-  const e = escAttr(name);
-  return html
-    .replace(/<title>[^<]*<\/title>/, `<title>${e}</title>`)
-    .replace(/(<meta name="apple-mobile-web-app-title" content=")[^"]*(")/, `$1${e}$2`);
+    if (!name)
+        return html;
+    const e = escAttr(name);
+    return html
+        .replace(/<title>[^<]*<\/title>/, `<title>${e}</title>`)
+        .replace(/(<meta name="apple-mobile-web-app-title" content=")[^"]*(")/, `$1${e}$2`);
 }
-
 // Override the PWA install name (Android uses short_name; both set so home-screen + app list agree).
 export function applyManifestName(manifest, name) {
-  if (!name) return manifest;
-  return { ...manifest, name, short_name: name };
+    if (!name)
+        return manifest;
+    return { ...manifest, name, short_name: name };
 }

package/dist/src/asr/iflyConfig.js

@@ -0,0 +1,7 @@
+export function asrConfig(env = process.env) {
+    return { appId: env.XFYUN_APPID || '', apiKey: env.XFYUN_APIKEY || '', apiSecret: env.XFYUN_APISECRET || '' };
+}
+export function isAsrConfigured(env = process.env) {
+    const c = asrConfig(env);
+    return !!(c.appId && c.apiKey && c.apiSecret);
+}

package/dist/src/asr/iflySign.js

@@ -0,0 +1,14 @@
+import { createHmac } from 'node:crypto';
+// Build a fully-signed iFlytek IAT v2 WebSocket URL. The secret (apiSecret) is used only here on the
+// server — the browser receives only the resulting URL (HMAC output, not the key). `host`/`date` are
+// injectable so this is deterministic and unit-testable; production passes host='iat-api.xfyun.cn'
+// and date=new Date().toUTCString() (RFC1123 GMT, iFlytek allows ±300s skew).
+export function buildIatSignedUrl({ appId, apiKey, apiSecret, host = 'iat-api.xfyun.cn', date, }) {
+    const requestLine = 'GET /v2/iat HTTP/1.1';
+    const signatureOrigin = `host: ${host}\ndate: ${date}\n${requestLine}`;
+    const signature = createHmac('sha256', apiSecret).update(signatureOrigin).digest('base64');
+    const authorizationOrigin = `api_key="${apiKey}", algorithm="hmac-sha256", headers="host date request-line", signature="${signature}"`;
+    const authorization = Buffer.from(authorizationOrigin, 'utf8').toString('base64');
+    const qs = new URLSearchParams({ authorization, date, host });
+    return { url: `wss://${host}/v2/iat?${qs.toString()}`, appId };
+}

package/dist/src/auth.js

@@ -0,0 +1,27 @@
+import crypto from 'node:crypto';
+export function loadToken(env = process.env) {
+    let token = env.HANDMUX_TOKEN;
+    if (!token) {
+        token = crypto.randomBytes(24).toString('base64url');
+        console.log(`[handmux] no HANDMUX_TOKEN set; generated token: ${token}`);
+    }
+    return token;
+}
+const sha = (value) => crypto.createHash('sha256').update(String(value)).digest();
+export function tokenEquals(a, b) {
+    return crypto.timingSafeEqual(sha(a), sha(b));
+}
+export function bearerFrom(header) {
+    if (!header)
+        return null;
+    const m = /^Bearer (.+)$/.exec(header);
+    return m?.[1] ?? null;
+}
+export function expressAuth(token) {
+    return (req, res, next) => {
+        const provided = bearerFrom(req.get('authorization'));
+        if (provided && tokenEquals(provided, token))
+            return next();
+        res.status(401).json({ error: 'unauthorized' });
+    };
+}

package/dist/src/browser/bootstrap.js

@@ -0,0 +1,72 @@
+import { randomBytes } from 'node:crypto';
+const BOOTSTRAP_PREFIX = '/_browser-bootstrap/';
+function normalizedOrigin(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Error('browser bootstrap origin must use http or https');
+    return url.origin;
+}
+export function isBrowserBootstrapPath(pathname) {
+    return String(pathname || '').startsWith(BOOTSTRAP_PREFIX);
+}
+export function createBrowserBootstrapStore({ randomToken = () => randomBytes(24).toString('base64url'), now = Date.now, ttlMs = 60_000, } = {}) {
+    const tickets = new Map();
+    const prune = () => {
+        const current = now();
+        for (const [token, entry] of tickets)
+            if (entry.expiresAt <= current)
+                tickets.delete(token);
+    };
+    return {
+        issue({ url, origin, deviceId, preserveMethod = false, redirectStatus = 302, }) {
+            prune();
+            const expectedOrigin = normalizedOrigin(origin);
+            const target = new URL(url);
+            if (target.origin !== expectedOrigin || !target.pathname.split('/')[1]?.startsWith('_browser-')) {
+                throw new Error('browser bootstrap target must be a session on its public origin');
+            }
+            const token = randomToken();
+            tickets.set(token, {
+                url: target.toString(),
+                origin: expectedOrigin,
+                deviceId,
+                preserveMethod,
+                redirectStatus,
+                expiresAt: now() + ttlMs,
+            });
+            return new URL(`${BOOTSTRAP_PREFIX}${encodeURIComponent(token)}`, expectedOrigin).toString();
+        },
+        consume(pathname, origin) {
+            prune();
+            if (!isBrowserBootstrapPath(pathname))
+                return null;
+            let token;
+            try {
+                token = decodeURIComponent(String(pathname).slice(BOOTSTRAP_PREFIX.length));
+            }
+            catch {
+                return null;
+            }
+            const entry = tickets.get(token);
+            let requestedOrigin;
+            try {
+                requestedOrigin = normalizedOrigin(origin);
+            }
+            catch {
+                return null;
+            }
+            if (!entry || entry.origin !== requestedOrigin)
+                return null;
+            tickets.delete(token);
+            if (entry.preserveMethod) {
+                return {
+                    url: entry.url,
+                    deviceId: entry.deviceId,
+                    preserveMethod: true,
+                    redirectStatus: entry.redirectStatus,
+                };
+            }
+            return { url: entry.url, deviceId: entry.deviceId };
+        },
+    };
+}

package/dist/src/browser/cookieProfiles.js

@@ -0,0 +1,413 @@
+const MUTATION_METHODS = ['setByServer', 'setByClient', 'setCookies', 'deleteCookies'];
+const DAY = 24 * 60 * 60 * 1000;
+const MAX_TIMER_DELAY = 2_147_483_647;
+const noPersistence = {
+    async read() { return null; },
+    async write() { },
+    async remove() { },
+    async readMetadata() { return null; },
+    async writeMetadata() { },
+    async removeMetadata() { },
+    async close() { },
+};
+export function createDeviceCookieProfiles({ createCookies, onMutation = () => { }, persistence = noPersistence, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout, }) {
+    const profiles = new Map();
+    const pending = new Set();
+    let closing = false;
+    const track = (operation) => {
+        pending.add(operation);
+        operation.then(() => pending.delete(operation), () => pending.delete(operation));
+        return operation;
+    };
+    const profileFor = (deviceId) => {
+        let profile = profiles.get(deviceId);
+        if (!profile) {
+            profile = {
+                cookies: createCookies(),
+                attached: new Set(),
+                persist: false,
+                retentionDays: 30,
+                loaded: false,
+                used: false,
+                active: false,
+                idleSince: null,
+                retentionTimer: null,
+                flushTimer: null,
+                dirty: false,
+                operationPromise: Promise.resolve(),
+                configurePromise: Promise.resolve(),
+                useVersion: 0,
+                retentionEpoch: 0,
+            };
+            profiles.set(deviceId, profile);
+        }
+        return profile;
+    };
+    const installCookies = (profile, cookies) => {
+        profile.cookies = cookies;
+        for (const attached of profile.attached) {
+            attached._cookieJar = cookies._cookieJar;
+            attached._pendingSyncCookies = [];
+        }
+    };
+    const replaceJar = (profile, serialized) => {
+        profile.cookies.setJar(serialized);
+        for (const cookies of profile.attached) {
+            cookies._cookieJar = profile.cookies._cookieJar;
+            cookies._pendingSyncCookies = [];
+        }
+    };
+    const queueOperation = (profile, operation) => {
+        const result = profile.operationPromise.then(operation);
+        profile.operationPromise = result.catch(() => { });
+        return track(result);
+    };
+    const queueWrite = (deviceId, profile, serialized = profile.cookies.serializeJar()) => (queueOperation(profile, () => persistence.write(deviceId, serialized)));
+    const queueMetadata = (deviceId, profile) => queueOperation(profile, () => persistence.writeMetadata?.(deviceId, {
+        persist: profile.persist,
+        retentionDays: profile.retentionDays,
+        noLeaseSince: profile.idleSince,
+    }));
+    const flush = async (deviceId) => {
+        const profile = profiles.get(deviceId);
+        if (!profile || !profile.persist)
+            return;
+        if (!profile.dirty) {
+            await profile.operationPromise;
+            return;
+        }
+        if (profile.flushTimer !== null) {
+            clearTimer(profile.flushTimer);
+            profile.flushTimer = null;
+        }
+        profile.dirty = false;
+        try {
+            await queueWrite(deviceId, profile);
+        }
+        catch (error) {
+            profile.dirty = true;
+            throw error;
+        }
+    };
+    const markDirty = (deviceId) => {
+        const profile = profileFor(deviceId);
+        profile.used = true;
+        profile.useVersion += 1;
+        onMutation(deviceId);
+        if (!profile.persist)
+            return;
+        profile.dirty = true;
+        if (closing || profile.flushTimer !== null)
+            return;
+        profile.flushTimer = setTimer(() => {
+            profile.flushTimer = null;
+            void flush(deviceId).catch(() => { });
+        }, 500);
+    };
+    const clearRetentionTimer = (profile) => {
+        if (profile.retentionTimer === null)
+            return;
+        clearTimer(profile.retentionTimer);
+        profile.retentionTimer = null;
+    };
+    const clearExpired = async (deviceId, profile, expectedEpoch, expectedIdleSince) => {
+        clearRetentionTimer(profile);
+        if (profile.dirty)
+            await flush(deviceId);
+        else
+            await profile.operationPromise;
+        if (profile.active
+            || profile.retentionEpoch !== expectedEpoch
+            || profile.idleSince !== expectedIdleSince)
+            return;
+        installCookies(profile, createCookies());
+        profile.used = false;
+        profile.useVersion += 1;
+        profile.idleSince = null;
+        profile.dirty = false;
+        await queueOperation(profile, () => persistence.remove(deviceId));
+    };
+    const scheduleRetention = (deviceId, profile) => {
+        clearRetentionTimer(profile);
+        if (closing || profile.active || profile.idleSince === null || profile.retentionDays === null)
+            return null;
+        const remaining = profile.idleSince + profile.retentionDays * DAY - now();
+        if (remaining <= 0) {
+            return track(clearExpired(deviceId, profile, profile.retentionEpoch, profile.idleSince));
+        }
+        profile.retentionTimer = setTimer(() => {
+            profile.retentionTimer = null;
+            const operation = scheduleRetention(deviceId, profile);
+            if (operation)
+                void operation.catch(() => { });
+        }, Math.min(remaining, MAX_TIMER_DELAY));
+        return null;
+    };
+    const saveCurrent = async (deviceId, profile) => {
+        if (profile.flushTimer !== null) {
+            clearTimer(profile.flushTimer);
+            profile.flushTimer = null;
+        }
+        profile.dirty = false;
+        await queueWrite(deviceId, profile);
+    };
+    const configureImpl = async (deviceId, prefs) => {
+        const preferences = prefs && typeof prefs === 'object' && !Array.isArray(prefs)
+            ? prefs : null;
+        if (typeof preferences?.persist !== 'boolean'
+            || ![1, 7, 30, null].includes(preferences?.retentionDays)) {
+            throw new Error('invalid browser profile preferences');
+        }
+        const validPreferences = preferences;
+        const profile = profileFor(deviceId);
+        const wasPersisting = profile.persist;
+        profile.retentionEpoch += 1;
+        let warning = null;
+        if (validPreferences.persist && !wasPersisting) {
+            if (!profile.loaded) {
+                const metadata = await persistence.readMetadata?.(deviceId);
+                if (metadata?.persist)
+                    profile.idleSince = metadata.noLeaseSince;
+            }
+            profile.persist = true;
+            profile.retentionDays = validPreferences.retentionDays;
+            if (!profile.loaded && !profile.used) {
+                profile.loaded = true;
+                const useVersion = profile.useVersion;
+                try {
+                    const serialized = await persistence.read(deviceId);
+                    if (profile.used || profile.useVersion !== useVersion) {
+                        await saveCurrent(deviceId, profile);
+                    }
+                    else if (serialized !== null) {
+                        replaceJar(profile, serialized);
+                    }
+                }
+                catch {
+                    warning = 'profile-recovery-failed';
+                    await queueOperation(profile, () => persistence.remove(deviceId));
+                    if (profile.used || profile.useVersion !== useVersion) {
+                        await saveCurrent(deviceId, profile);
+                    }
+                    else {
+                        installCookies(profile, createCookies());
+                        profile.used = false;
+                        profile.useVersion += 1;
+                    }
+                }
+            }
+            else {
+                profile.loaded = true;
+                await saveCurrent(deviceId, profile);
+            }
+        }
+        else if (!validPreferences.persist && wasPersisting) {
+            const wasDirty = profile.dirty;
+            if (profile.flushTimer !== null) {
+                clearTimer(profile.flushTimer);
+                profile.flushTimer = null;
+            }
+            profile.dirty = false;
+            try {
+                await queueOperation(profile, () => persistence.remove(deviceId));
+            }
+            catch (error) {
+                profile.dirty ||= wasDirty;
+                const retention = scheduleRetention(deviceId, profile);
+                if (retention)
+                    await retention;
+                throw error;
+            }
+            if (profile.flushTimer !== null) {
+                clearTimer(profile.flushTimer);
+                profile.flushTimer = null;
+            }
+            profile.dirty = false;
+            profile.persist = false;
+            profile.retentionDays = validPreferences.retentionDays;
+            await queueOperation(profile, () => persistence.removeMetadata?.(deviceId));
+        }
+        else {
+            profile.persist = validPreferences.persist;
+            profile.retentionDays = validPreferences.retentionDays;
+        }
+        if (profile.persist)
+            await queueMetadata(deviceId, profile);
+        const retention = scheduleRetention(deviceId, profile);
+        if (retention)
+            await retention;
+        return { persist: profile.persist, retentionDays: profile.retentionDays, warning };
+    };
+    const configure = (deviceId, prefs) => {
+        const profile = profileFor(deviceId);
+        // Preference changes span reads, jar restoration, disk removal, and metadata writes. Serialize that
+        // whole transaction per device; serializing only the individual file operations lets an older enable
+        // finish after a newer disable and silently turn persistence back on.
+        const result = profile.configurePromise.catch(() => { }).then(() => configureImpl(deviceId, prefs));
+        profile.configurePromise = result.catch(() => { });
+        return track(result);
+    };
+    const setActive = (deviceId, active) => {
+        const profile = profiles.get(deviceId);
+        if (!profile)
+            return;
+        profile.retentionEpoch += 1;
+        if (active) {
+            profile.active = true;
+            profile.idleSince = null;
+            clearRetentionTimer(profile);
+            if (profile.persist)
+                void queueMetadata(deviceId, profile).catch(() => { });
+            return;
+        }
+        if (profile.active || profile.idleSince === null)
+            profile.idleSince = now();
+        profile.active = false;
+        if (profile.persist)
+            void queueMetadata(deviceId, profile).catch(() => { });
+        const retention = scheduleRetention(deviceId, profile);
+        if (retention)
+            void retention.catch(() => { });
+    };
+    const attach = (deviceId, sessionCookies) => {
+        const profile = profileFor(deviceId);
+        if (!profile.cookies?._cookieJar || !sessionCookies?._cookieJar) {
+            throw new Error('browser cookie profile unsupported');
+        }
+        profile.used = true;
+        profile.useVersion += 1;
+        sessionCookies._cookieJar = profile.cookies._cookieJar;
+        sessionCookies._pendingSyncCookies = [];
+        profile.attached.add(sessionCookies);
+        const originals = new Map();
+        for (const name of MUTATION_METHODS) {
+            const original = sessionCookies[name];
+            originals.set(name, {
+                hadOwn: Object.prototype.hasOwnProperty.call(sessionCookies, name),
+                value: original,
+            });
+            if (typeof original !== 'function')
+                throw new Error('browser cookie profile unsupported');
+            sessionCookies[name] = (...args) => {
+                const result = original.apply(sessionCookies, args);
+                markDirty(deviceId);
+                return result;
+            };
+        }
+        let attached = true;
+        return () => {
+            if (!attached)
+                return;
+            attached = false;
+            profile.attached.delete(sessionCookies);
+            for (const [name, original] of originals) {
+                if (original.hadOwn)
+                    sessionCookies[name] = original.value;
+                else
+                    delete sessionCookies[name];
+            }
+        };
+    };
+    const serialize = (deviceId) => {
+        const profile = profiles.get(deviceId);
+        if (!profile)
+            return null;
+        profile.used = true;
+        profile.useVersion += 1;
+        return profile.cookies.serializeJar();
+    };
+    const clear = (deviceId, { url, hostname } = {}) => {
+        const fullClear = !hostname && !url;
+        const profile = profiles.get(deviceId) || (fullClear ? profileFor(deviceId) : null);
+        if (!profile)
+            return { cleared: false };
+        profile.used = true;
+        profile.useVersion += 1;
+        let targetHostname = hostname;
+        if (!targetHostname && url) {
+            try {
+                targetHostname = new URL(url).hostname;
+            }
+            catch {
+                return { cleared: false };
+            }
+        }
+        if (!targetHostname) {
+            replaceJar(profile, null);
+            onMutation(deviceId);
+            profile.dirty = false;
+            if (profile.flushTimer !== null) {
+                clearTimer(profile.flushTimer);
+                profile.flushTimer = null;
+            }
+            return queueOperation(profile, () => persistence.remove(deviceId))
+                .then(() => ({ cleared: true }));
+        }
+        const normalizedHostname = targetHostname.toLowerCase();
+        const internalCookies = profile.cookies._getAllCookiesSync().filter((cookie) => {
+            const domain = cookie.domain?.replace(/^\./, '').toLowerCase();
+            if (!domain)
+                return false;
+            if (cookie.hostOnly)
+                return domain === normalizedHostname;
+            return normalizedHostname === domain || normalizedHostname.endsWith(`.${domain}`);
+        });
+        if (!internalCookies.length)
+            return { cleared: false };
+        const matches = profile.cookies._convertToExternalCookies(internalCookies);
+        for (let index = 0; index < matches.length; index++) {
+            const match = matches[index];
+            const internal = internalCookies[index];
+            if (!match || !internal)
+                continue;
+            match.expires = internal.expires;
+            match.maxAge = internal.maxAge;
+            match.sameSite = internal.sameSite;
+        }
+        profile.cookies.deleteCookies(matches);
+        markDirty(deviceId);
+        return { cleared: true };
+    };
+    const remove = (deviceId) => {
+        const profile = profiles.get(deviceId);
+        if (!profile)
+            return false;
+        clearRetentionTimer(profile);
+        if (profile.flushTimer !== null)
+            clearTimer(profile.flushTimer);
+        profiles.delete(deviceId);
+        if (profile.persist) {
+            queueOperation(profile, () => persistence.remove(deviceId));
+            queueOperation(profile, () => persistence.removeMetadata?.(deviceId));
+        }
+        return true;
+    };
+    const has = (deviceId) => profiles.has(deviceId);
+    const close = async () => {
+        closing = true;
+        for (const profile of profiles.values())
+            clearRetentionTimer(profile);
+        while (true) {
+            const flushes = [];
+            for (const [deviceId, profile] of profiles) {
+                if (profile.dirty)
+                    flushes.push(flush(deviceId));
+                else if (profile.flushTimer !== null) {
+                    clearTimer(profile.flushTimer);
+                    profile.flushTimer = null;
+                }
+            }
+            await Promise.all(flushes);
+            const operations = [...pending];
+            if (!operations.length)
+                break;
+            await Promise.all(operations);
+        }
+        for (const profile of profiles.values())
+            clearRetentionTimer(profile);
+        await persistence.close();
+    };
+    return {
+        attach, serialize, clear, remove, has, configure, setActive, flush, close,
+    };
+}

package/dist/src/browser/coordinator.js

@@ -0,0 +1,51 @@
+const DEVICE_ID = /^[A-Za-z0-9_-]{32,128}$/;
+function jsonBody(response) {
+    if (!response.body?.length)
+        return null;
+    try {
+        const parsed = JSON.parse(response.body.toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sendProxy(res, response, generation, stampGeneration) {
+    if (!response)
+        return res.status(503).json({ error: 'browser unavailable' });
+    for (const [name, value] of Object.entries(response.headers || {})) {
+        if (value != null && !['connection', 'content-length', 'transfer-encoding'].includes(name.toLowerCase())) {
+            res.setHeader(name, value);
+        }
+    }
+    if (stampGeneration && response.status >= 200 && response.status < 300) {
+        const payload = jsonBody(response);
+        if (payload)
+            return res.status(response.status).json({ ...payload, generation });
+    }
+    return res.status(response.status).send(response.body);
+}
+export function createBrowserCoordinator({ proxyRequest, getStatus = () => ({ ready: false, generation: 0 }), }) {
+    const handler = async (req, res) => {
+        if (req.method === 'GET' && req.path === '/status') {
+            return res.json(getStatus());
+        }
+        const deviceId = req.get('x-handmux-browser-device');
+        if (!DEVICE_ID.test(deviceId || '')) {
+            return res.status(400).json({ error: 'browser device id required' });
+        }
+        const path = `/api/browser-proxy${req.path}`;
+        const response = await proxyRequest({
+            req,
+            method: req.method,
+            path,
+            body: ['PUT', 'POST', 'PATCH'].includes(req.method) ? req.body : undefined,
+        });
+        const stampGeneration = /^\/leases\/[^/]+(?:\/navigate)?$/.test(req.path)
+            && ['PUT', 'POST'].includes(req.method);
+        return sendProxy(res, response, getStatus().generation, stampGeneration);
+    };
+    handler.close = () => { };
+    return handler;
+}